Skip to content

gradient_aware_harmonisation.utils#

Utility functions

Classes:

Name Description
GetHarmonisedSplineLike

A callable which can generate a final, harmonised spline

Functions:

Name Description
add_constant_to_spline

Add a constant value to a spline
harmonise_splines

Harmonise spline

GetHarmonisedSplineLike #

Bases: Protocol

A callable which can generate a final, harmonised spline

The harmonised spline is generated based on a harmonised spline that doesn't consider convergence and a spline to which the final, harmonised spline should converge.

Methods:

Name Description
__call__

Generate the harmonised spline
Source code in src/gradient_aware_harmonisation/utils.py 
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
class GetHarmonisedSplineLike(Protocol):
    """
    A callable which can generate a final, harmonised spline

    The harmonised spline is generated based on a
    harmonised spline that doesn't consider convergence
    and a spline to which the final, harmonised spline should converge.
    """

    def __call__(
        self,
        harmonisation_time: Union[int, float],
        convergence_time: Union[int, float],
        harmonised_spline_no_convergence: Spline,
        convergence_spline: Spline,
    ) -> Spline:
        """
        Generate the harmonised spline

        Parameters
        ----------
        harmonisation_time
            Harmonisation time

            This is the time at and before which
            the solution should be equal to `harmonised_spline_no_convergence`.

        convergence_time
            Convergence time

            This is the time at and after which
            the solution should be equal to `convergence_spline`.

        harmonised_spline_no_convergence
            Harmonised spline that does not consider convergence

        convergence_spline
            The spline to which the result should converge

        Returns
        -------
        :
            Harmonised spline
        """

__call__ #

__call__(
    harmonisation_time: Union[int, float],
    convergence_time: Union[int, float],
    harmonised_spline_no_convergence: Spline,
    convergence_spline: Spline,
) -> Spline

Generate the harmonised spline

Parameters:

Name Type Description Default
harmonisation_time Union[int, float]

Harmonisation time

This is the time at and before which the solution should be equal to harmonised_spline_no_convergence.

 required
convergence_time Union[int, float]

Convergence time

This is the time at and after which the solution should be equal to convergence_spline.

 required
harmonised_spline_no_convergence Spline

Harmonised spline that does not consider convergence

 required
convergence_spline Spline

The spline to which the result should converge

 required

Returns:

Type Description
Spline

Harmonised spline
Source code in src/gradient_aware_harmonisation/utils.py 
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
def __call__(
    self,
    harmonisation_time: Union[int, float],
    convergence_time: Union[int, float],
    harmonised_spline_no_convergence: Spline,
    convergence_spline: Spline,
) -> Spline:
    """
    Generate the harmonised spline

    Parameters
    ----------
    harmonisation_time
        Harmonisation time

        This is the time at and before which
        the solution should be equal to `harmonised_spline_no_convergence`.

    convergence_time
        Convergence time

        This is the time at and after which
        the solution should be equal to `convergence_spline`.

    harmonised_spline_no_convergence
        Harmonised spline that does not consider convergence

    convergence_spline
        The spline to which the result should converge

    Returns
    -------
    :
        Harmonised spline
    """

add_constant_to_spline #

add_constant_to_spline(
    in_spline: Spline, constant: float | int
) -> Spline

Add a constant value to a spline

Parameters:

Name Type Description Default
in_spline Spline

Input spline

 required
constant float | int

Constant to add

 required

Returns:

Type Description
Spline

Spline plus the given constant
Source code in src/gradient_aware_harmonisation/utils.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def add_constant_to_spline(in_spline: Spline, constant: float | int) -> Spline:
    """
    Add a constant value to a spline

    Parameters
    ----------
    in_spline
        Input spline

    constant
        Constant to add

    Returns
    -------
    :
        Spline plus the given constant
    """
    try:
        import scipy.interpolate
    except ImportError as exc:
        raise MissingOptionalDependencyError(
            "add_constant_to_spline", requirement="scipy"
        ) from exc

    return SumOfSplines(
        spline_one=in_spline,
        spline_two=SplineScipy(
            scipy.interpolate.PPoly(
                c=[[constant]],
                # # TODO: Problem: Currently domain is defined for SumOfSplines
                # #  and SplineScipy should be specified only once
                # #  preferably in SplineScipy
                # x=in_spline.domain,
                # TODO: better solution for domain handling
                x=[-1e8, 1e8],
            )
        ),
    )

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