Skip to content

gradient_aware_harmonisation#

Gradient-aware harmonisation of timeseries

Modules:

Name Description
exceptions

Exceptions that are used throughout
helpers

Helper functions
spline

Spline handling
utils

Utility functions

Functions:

Name Description
harmonise

Harmonise two timeseries

harmonise #

harmonise(
    target_timeseries: Timeseries,
    harmonisee_timeseries: Timeseries,
    harmonisation_time: Union[int, float],
    convergence_time: Optional[Union[int, float]],
    interpolation_target: str = "original",
    decay_method: str = "cosine",
    **kwargs: Any,
) -> 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)

Parameters#

target_timeseries Target timeseries (i.e. what we harmonise to)

harmonisee_timeseries Harmonisee timeseries (i.e. the timeseries we want to harmonise)

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

convergence_time Time point at which the harmonised data should converge towards the prediced data.

interpolation_target Target to which the harmonised timeseries should converge.

If original, we converge back to harmonisee.
If bias-corrected, we converge back to harmonissee
having applied a basic constant offset bias correction
(see the docs for further info TODO put a cross link to a notebook).

decay_method Decay function used to decay weights when interpolating between the target and our harmonisation target. If 'polynomial' is used an additional argument 'pow' to specify the power is required (should be => 1.)

**kwargs keyword arguments passed to make_interp_spline or 'polynomial_decay'

Returns#

harmonised_timeseries : timeseries of harmonised data set

Raises#

ValueError interpolation_target must be either 'original' or 'bias_corrected'

Source code in src/gradient_aware_harmonisation/__init__.py 
 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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def harmonise(  # noqa: PLR0913
    target_timeseries: Timeseries,
    harmonisee_timeseries: Timeseries,
    harmonisation_time: Union[int, float],
    convergence_time: Optional[Union[int, float]],
    interpolation_target: str = "original",
    decay_method: str = "cosine",
    **kwargs: Any,
) -> 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)

    Parameters
    ----------
    target_timeseries
        Target timeseries (i.e. what we harmonise to)

    harmonisee_timeseries
        Harmonisee timeseries (i.e. the timeseries we want to harmonise)

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

    convergence_time
        Time point at which the harmonised data
        should converge towards the prediced data.

    interpolation_target
        Target to which the harmonised timeseries should converge.

        If original, we converge back to harmonisee.
        If bias-corrected, we converge back to harmonissee
        having applied a basic constant offset bias correction
        (see the docs for further info TODO put a cross link to a notebook).

    decay_method
        Decay function used to decay weights
        when interpolating between the target and our harmonisation target.
        If 'polynomial' is used an additional argument 'pow' to specify the power
        is required (should be => 1.)

    **kwargs
        keyword arguments passed to `make_interp_spline` or 'polynomial_decay'

    Returns
    -------
    harmonised_timeseries :
        timeseries of harmonised data set

    Raises
    ------
    ValueError
        interpolation_target must be either 'original' or 'bias_corrected'
    """
    if interpolation_target not in ["original", "bias_corrected"]:
        raise ValueError(  # noqa: TRY003
            "interpolation_target must be 'original' or 'bias_corrected'. "
            f"Got {interpolation_target=}"
        )

    # compute splines
    target_spline = timeseries_to_spline(target_timeseries, **kwargs)
    harmonisee_spline = timeseries_to_spline(harmonisee_timeseries, **kwargs)

    # compute harmonised spline
    harmonised_spline = harmonise_splines(
        target=target_spline,
        harmonisee=harmonisee_spline,
        harmonisation_time=harmonisation_time,
        **kwargs,
    )

    # get target of interpolation
    if interpolation_target == "original":
        interpol_target: Spline = harmonisee_spline
    if interpolation_target == "bias_corrected":
        interpol_target = harmonise_constant_offset(
            target=target_spline,
            harmonisee=harmonisee_spline,
            harmonisation_time=harmonisation_time,
        )

    # compute interpolation timeseries
    interpolated_timeseries = interpolate_harmoniser(
        interpol_target,
        harmonised_spline,
        harmonisee_timeseries,
        convergence_time,
        harmonisation_time,
        decay_method,
        **kwargs,
    )

    return interpolated_timeseries