Skip to content

gradient_aware_harmonisation#

Gradient-aware harmonisation of timeseries

Modules:

Name Description
add_cubic

Harmonisation by adding a cubic
convergence

Implements the decay/convergence methods
exceptions

Exceptions that are used throughout
plotting

Helper functions
spline

Spline handling
timeseries

Definition of our timeseries class
typing

Type hinting support
utils

Utility functions

Functions:

Name Description
harmonise

Harmonise two timeseries
harmonise_splines

Harmonise spline

harmonise #

harmonise(
    harmonisee_timeseries: Timeseries,
    target_timeseries: Timeseries,
    harmonisation_time: Union[int, float],
    convergence_timeseries: Optional[Timeseries] = None,
    convergence_time: Optional[Union[int, float]] = None,
    get_harmonised_spline: GetHarmonisedSplineLike = get_cosine_decay_harmonised_spline,
) -> 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

Source code in src/gradient_aware_harmonisation/__init__.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def harmonise(  # noqa: PLR0913
    harmonisee_timeseries: Timeseries,
    target_timeseries: Timeseries,
    harmonisation_time: Union[int, float],
    convergence_timeseries: Optional[Timeseries] = None,
    convergence_time: Optional[Union[int, float]] = None,
    get_harmonised_spline: GetHarmonisedSplineLike = (
        get_cosine_decay_harmonised_spline
    ),
) -> 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
    """
    # use maximum time if no convergence time is provided
    if convergence_time is None:
        convergence_time = harmonisee_timeseries.time_axis.max()

    # use harmonisee as convergence target if nothing else is provided
    if convergence_timeseries is None:
        convergence_timeseries = harmonisee_timeseries

    # convert timeseries to splines
    target_spline = target_timeseries.to_spline()
    harmonisee_spline = harmonisee_timeseries.to_spline()
    convergence_spline = convergence_timeseries.to_spline()

    # get harmonised spline
    harmonised_spline = harmonise_splines(
        harmonisee=harmonisee_spline,
        target=target_spline,
        harmonisation_time=harmonisation_time,
        converge_to=convergence_spline,
        convergence_time=convergence_time,
        get_harmonised_spline=get_harmonised_spline,
    )

    # convert harmonised spline to timeseries
    res_time_axis = harmonisee_timeseries.time_axis[
        harmonisee_timeseries.time_axis >= harmonisation_time
    ]
    res = Timeseries(
        time_axis=res_time_axis,
        values=harmonised_spline(res_time_axis),
    )

    return res

harmonise_splines #

harmonise_splines(
    harmonisee: Spline,
    target: Spline,
    harmonisation_time: Union[int, float],
    converge_to: Spline,
    convergence_time: Union[int, float],
    get_harmonised_spline: GetHarmonisedSplineLike = get_cosine_decay_harmonised_spline,
) -> Spline

Harmonise spline

Parameters:

Name Type Description Default
harmonisee Spline

Spline that we want to harmonise

 required
target Spline

Spline to which we harmonise

 required
harmonisation_time Union[int, float]

Time point at which harmonisee should be matched to the target

 required
converge_to Spline

The spline to which the result should converge.

If not supplied, we use `harmonisee'. i.e. we converge back to the spline we are harmonising.

 required
convergence_time Union[int, float]

Time point at which the harmonised data should converge to the convergence spline

 required
get_harmonised_spline GetHarmonisedSplineLike

The method to use to converge back to the convergence spline.

 get_cosine_decay_harmonised_spline

Returns:

Type Description
Spline

harmonised spline
Source code in src/gradient_aware_harmonisation/utils.py 
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def harmonise_splines(  # noqa: PLR0913
    harmonisee: Spline,
    target: Spline,
    harmonisation_time: Union[int, float],
    converge_to: Spline,
    convergence_time: Union[int, float],
    get_harmonised_spline: GetHarmonisedSplineLike = get_cosine_decay_harmonised_spline,
) -> Spline:
    """
    Harmonise spline

    Parameters
    ----------
    harmonisee
        Spline that we want to harmonise

    target
        Spline to which we harmonise

    harmonisation_time
        Time point at which harmonisee should be matched to the target

    converge_to
        The spline to which the result should converge.

        If not supplied, we use `harmonisee'.
        i.e. we converge back to the spline we are harmonising.

    convergence_time
        Time point at which the harmonised data
        should converge to the convergence spline

    get_harmonised_spline
        The method to use to converge back to the convergence spline.

    Returns
    -------
    :
        harmonised spline
    """
    # compute derivatives of splines
    target_dspline = target.derivative()
    harmonisee_dspline = harmonisee.derivative()

    # match first-order derivatives
    diff_dspline = np.subtract(
        target_dspline(harmonisation_time), harmonisee_dspline(harmonisation_time)
    )

    harmonised_first_derivative = add_constant_to_spline(
        in_spline=harmonisee_dspline, constant=diff_dspline
    )

    # integrate to match zero-order derivative
    harmonised_spline_first_derivative_only = (
        harmonised_first_derivative.antiderivative()
    )

    # match zero-order derivatives
    diff_spline = np.subtract(
        target(harmonisation_time),
        harmonised_spline_first_derivative_only(harmonisation_time),
    )

    harmonised_spline_no_convergence = add_constant_to_spline(
        in_spline=harmonised_spline_first_derivative_only, constant=diff_spline
    )

    harmonised_spline = get_harmonised_spline(
        harmonisation_time=harmonisation_time,
        convergence_time=convergence_time,
        harmonised_spline_no_convergence=harmonised_spline_no_convergence,
        convergence_spline=converge_to,
    )

    return harmonised_spline