Gradient aware harmonisation (Getting Started)¶

Here we introduce a method for harmonising two timeseries. This part may be more unusual or unfamiliar to people used to working with arrays, so it serves as an introduction into some of the concepts used in this package.

Imports¶

In [1]:

# Imports
import numpy as np

from gradient_aware_harmonisation import harmonise
from gradient_aware_harmonisation.plotting import plotting
from gradient_aware_harmonisation.timeseries import Timeseries

# Imports import numpy as np from gradient_aware_harmonisation import harmonise from gradient_aware_harmonisation.plotting import plotting from gradient_aware_harmonisation.timeseries import Timeseries

Toy Example 1: Artificial data¶

Create some data¶

In [2]:

# create some data
harmonisation_time = 3.0

x1 = np.arange(-2, 3.0, 0.1)
y1 = -16 * x1

x2 = np.arange(2, 10, 0.1)
y2 = 0.5 * x2 + x2**3

target_timeseries = Timeseries(time_axis=x1, values=y1)
harmonisee_timeseries = Timeseries(time_axis=x2, values=y2)

# create some data harmonisation_time = 3.0 x1 = np.arange(-2, 3.0, 0.1) y1 = -16 * x1 x2 = np.arange(2, 10, 0.1) y2 = 0.5 * x2 + x2**3 target_timeseries = Timeseries(time_axis=x1, values=y1) harmonisee_timeseries = Timeseries(time_axis=x2, values=y2)

Harmonise functions using harmonise¶

Inspect harmoniser function¶

In [3]:

help(harmonise)

harmonised_timeseries = harmonise(
    target_timeseries=target_timeseries,
    harmonisee_timeseries=harmonisee_timeseries,
    harmonisation_time=harmonisation_time,
    convergence_time=None,
)

help(harmonise) harmonised_timeseries = harmonise( target_timeseries=target_timeseries, harmonisee_timeseries=harmonisee_timeseries, harmonisation_time=harmonisation_time, convergence_time=None, )

Help on function harmonise in module gradient_aware_harmonisation:

harmonise(harmonisee_timeseries: gradient_aware_harmonisation.timeseries.Timeseries, target_timeseries: gradient_aware_harmonisation.timeseries.Timeseries, harmonisation_time: Union[int, float], convergence_timeseries: Optional[gradient_aware_harmonisation.timeseries.Timeseries] = None, convergence_time: Union[int, float, NoneType] = None, get_harmonised_spline: gradient_aware_harmonisation.utils.GetHarmonisedSplineLike = <function get_cosine_decay_harmonised_spline at 0x789000174d60>) -> gradient_aware_harmonisation.timeseries.Timeseries
    Harmonise two timeseries
    
    When we say harmonise, we mean make it
    such that the harmonisee matches with the target at some
    specified time point (called harmonisation time)
    before returning to some other timeseries
    (the convergence timeseries)
    at the convergence time.
    
    Parameters
    ----------
    harmonisee_timeseries
        Harmonisee timeseries (i.e. the timeseries we want to harmonise)
    
    target_timeseries
        Target timeseries (i.e. what we harmonise to)
    
    harmonisation_time
        Time point at which harmonisee should be matched to the target
    
    convergence_timeseries
        The timeseries to which the result should converge.
    
        If not supplied, we use `harmonisee_timeseries`
        i.e. we converge back to the timeseries we are harmonising.
    
    convergence_time
        Time point at which the harmonised data
        should converge to the convergence timeseries.
    
        If not supplied, we converge to convergence timeseries
        at the last time point in harmonisee_timeseries.
    
    get_harmonised_spline
        Function used to get the harmonised spline from a gradient-
        preserving spline and the timeseries to converge to
    
    Returns
    -------
    harmonised_timeseries :
        Harmonised timeseries

Plot results¶

In [4]:

plotting(
    harmonisee_timeseries,
    target_timeseries,
    harmonised_timeseries,
    harmonisation_time,
    convergence_time=None,
)

plotting( harmonisee_timeseries, target_timeseries, harmonised_timeseries, harmonisation_time, convergence_time=None, )

Introduce a convergence_time at $x=8.$¶

In [5]:

convergence_time = 8.0

harmonised_timeseries = harmonise(
    target_timeseries=target_timeseries,
    harmonisee_timeseries=harmonisee_timeseries,
    harmonisation_time=harmonisation_time,
    convergence_time=convergence_time,
)

plotting(
    harmonisee_timeseries,
    target_timeseries,
    harmonised_timeseries,
    harmonisation_time,
    convergence_time,
)

convergence_time = 8.0 harmonised_timeseries = harmonise( target_timeseries=target_timeseries, harmonisee_timeseries=harmonisee_timeseries, harmonisation_time=harmonisation_time, convergence_time=convergence_time, ) plotting( harmonisee_timeseries, target_timeseries, harmonised_timeseries, harmonisation_time, convergence_time, )

Toy Example 2: Use timeseries data¶

Read data¶

In [6]:

# select harmonization time point
harmonisation_time = 2004
convergence_time = 2006

# get timeseries
target_timeseries = Timeseries(
    time_axis=np.array([2001, 2002, 2003, 2004]),
    values=np.array([371.77, 373.72, 376.33, 378.83]),
)
harmonisee_timeseries = Timeseries(
    time_axis=np.array([2003, 2004, 2005, 2006, 2007]),
    values=np.array([375.56, 376.28, 378.83, 381.20, 382.55]),
)

# select harmonization time point harmonisation_time = 2004 convergence_time = 2006 # get timeseries target_timeseries = Timeseries( time_axis=np.array([2001, 2002, 2003, 2004]), values=np.array([371.77, 373.72, 376.33, 378.83]), ) harmonisee_timeseries = Timeseries( time_axis=np.array([2003, 2004, 2005, 2006, 2007]), values=np.array([375.56, 376.28, 378.83, 381.20, 382.55]), )

Run harmonise for different settings¶

In [7]:

# harmonise timeseries at t0
harmonised_timeseries = harmonise(
    target_timeseries=target_timeseries,
    harmonisee_timeseries=harmonisee_timeseries,
    harmonisation_time=harmonisation_time,
    convergence_time=None,
)

# harmonise timeseries at t0 and assure convergence at t1 (converge_t)
harmonised_timeseries2 = harmonise(
    target_timeseries=target_timeseries,
    harmonisee_timeseries=harmonisee_timeseries,
    harmonisation_time=harmonisation_time,
    convergence_time=convergence_time,
)

# harmonise timeseries at t0 harmonised_timeseries = harmonise( target_timeseries=target_timeseries, harmonisee_timeseries=harmonisee_timeseries, harmonisation_time=harmonisation_time, convergence_time=None, ) # harmonise timeseries at t0 and assure convergence at t1 (converge_t) harmonised_timeseries2 = harmonise( target_timeseries=target_timeseries, harmonisee_timeseries=harmonisee_timeseries, harmonisation_time=harmonisation_time, convergence_time=convergence_time, )

Plot results¶

In [8]:

plotting(
    harmonisee_timeseries=harmonisee_timeseries,
    target_timeseries=target_timeseries,
    interpolated_timeseries=harmonised_timeseries,
    harmonisation_time=harmonisation_time,
    convergence_time=None,
)

plotting(
    harmonisee_timeseries,
    target_timeseries,
    harmonised_timeseries2,
    harmonisation_time,
    convergence_time,
)

plotting( harmonisee_timeseries=harmonisee_timeseries, target_timeseries=target_timeseries, interpolated_timeseries=harmonised_timeseries, harmonisation_time=harmonisation_time, convergence_time=None, ) plotting( harmonisee_timeseries, target_timeseries, harmonised_timeseries2, harmonisation_time, convergence_time, )