Skip to content

Conversions reference

Source code in c3s_event_attribution_tools/data/conversions.py 
 10
 11
 12
 13
 14
 15
 16
 17
 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
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
148
149
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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
class Conversions:
    @staticmethod
    def convert_unit(array: T, from_unit: str, to_unit: str) -> T:
        """
        Convert units of measurement for the provided array or pandas Series.

        This method currently supports temperature conversions between Kelvin (k),
        Celsius (c), and Fahrenheit (f). Additional unit conversions can be added
        as needed.

        Parameters:
            array (np.ndarray or pd.Series):
                The input array or Series containing values to be converted.
            from_unit (str):
                Source unit of measurement (e.g., 'k', 'c', 'f', 'm').
            to_unit (str):
                Target unit of measurement (e.g., 'k', 'c', 'f', 'mm').
        Returns:
            np.ndarray or pd.Series: The array or Series with values converted to the
            target unit.
        """
        if from_unit in ['k', 'c', 'f'] and to_unit in ['k', 'c', 'f']:
            return Conversions.convert_temperature(array, from_unit, to_unit)
        elif from_unit in ['m', 'mm'] and to_unit in ['m', 'mm']:
            return Conversions.convert_precipitation(array, from_unit, to_unit)
        else:
            raise ValueError(f"Unsupported unit conversion from {from_unit} to {to_unit}")

    @staticmethod
    def convert_precipitation(array: T, from_unit: str, to_unit: str) -> T:
        """
        Convert precipitation values from one unit to another.

        This method performs in-place precipitation conversion on the provided array or
        pandas Series and supports meters (m) and millimeters (mm).

        Parameters:
            array (np.ndarray or pd.Series):
                The input array or Series containing precipitation values to be converted.
            from_unit (str):
                Source precipitation unit ('m' or 'mm'). Default is 'm'.
            to_unit (str):
                Target precipitation unit ('m' or 'mm'). Default is 'mm'.
        Returns:
            np.ndarray or pd.Series: The array or Series with precipitation values converted to the
            target unit.
        """
        if isinstance(array, np.ndarray):
            return Conversions._inner_convert_precipitation(array, from_unit, to_unit)
        elif isinstance(array, pd.Series):
            pandas_np_array : np.ndarray = array.values # type: ignore
            return pd.Series(Conversions._inner_convert_precipitation(pandas_np_array, from_unit, to_unit))
        else:
            raise TypeError("Unsupported type for temperature conversion: " + str(type(array)))

    @staticmethod
    def _inner_convert_precipitation(array: np.ndarray, from_unit: str, to_unit: str) -> np.ndarray:
        """
        This static helper method handles the mathematical transformation between 
        meters and millimeters.

        Parameters:
            array (np.ndarray):
                The numeric array containing precipitation values to be converted.
            from_unit (str):
                The current unit of the data. Supported values: "m", "mm".
            to_unit (str):
                The target unit for the data. Supported values: "m", "mm".
        Returns:
            np.ndarray: A new array containing the converted precipitation values.
        """
        if from_unit == to_unit:
            return array
        elif from_unit == "m" and to_unit == "mm":
            return array * 1000.0
        elif from_unit == "mm" and to_unit == "m":
            return array / 1000.0
        else:
            raise ValueError(f"Unsupported precipitation conversion from {from_unit} to {to_unit}")

    @staticmethod
    def convert_temperature(array: T, from_unit: str, to_unit: str) -> T:
        """
        Convert temperature values from one unit to another.

        This method performs in-place temperature conversion on the provided array or
        pandas Series and supports Kelvin (k), Celsius (c), and Fahrenheit (f).

        Parameters:
            array (np.ndarray or pd.Series):
                The input array or Series containing temperature values to be converted.
            from_unit (str, optional):
                Source temperature unit ('k', 'c', or 'f'). Default is 'k'.
            to_unit (str, optional):
                Target temperature unit ('k', 'c', or 'f'). Default is 'c'.

        Returns:
            np.ndarray or pd.Series: The array or Series with temperature values converted to the
            target unit.

        Raises:
            ValueError: If from_unit is not one of 'k', 'c', or 'f'.
            TypeError: If the input array is neither a numpy ndarray nor a pandas Series.

        Notes:
            - If from_unit and to_unit are identical, no conversion is performed.
            - Conversion modifies the input array or Series in place.
            - Conversion formulas:
                - Kelvin to Celsius: C = K - 273.15
                - Kelvin to Fahrenheit: F = (K - 273.15) × 9/5 + 32
                - Celsius to Kelvin: K = C + 273.15
                - Celsius to Fahrenheit: F = C × 9/5 + 32
                - Fahrenheit to Kelvin: K = (F - 32) × 5/9 + 273.15
                - Fahrenheit to Celsius: C = (F - 32) × 5/9
        """
        if isinstance(array, np.ndarray):
            return Conversions._inner_convert_temperature(array, from_unit, to_unit)
        elif isinstance(array, pd.Series):
            pandas_np_array : np.ndarray = array.values # type: ignore
            return pd.Series(Conversions._inner_convert_temperature(pandas_np_array, from_unit, to_unit))
        else:
            raise TypeError("Unsupported type for temperature conversion: " + str(type(array)))

    @staticmethod
    def _inner_convert_temperature(array: np.ndarray, from_unit: str, to_unit: str) -> np.ndarray:
        """
        This static helper method handles the mathematical transformation between 
        Kelvin, Celsius, and Fahrenheit. It ensures consistency by normalizing 
        unit strings to lowercase before processing.

        Parameters:
            array (np.ndarray):
                The numeric array containing temperature values to be converted.
            from_unit (str):
                The current unit of the data. Supported values: "k", "c", "f".
            to_unit (str):
                The target unit for the data. Supported values: "k", "c", "f".

        Returns:
            np.ndarray: A new array containing the converted temperature values.

        Raises:
            ValueError: If an unsupported unit or conversion pair is provided.
        """
        if from_unit == to_unit:
            return array
        # Convert unit lowercase for consistency
        from_unit = from_unit.lower()
        to_unit = to_unit.lower()

        if from_unit == "k" and to_unit == "c":
            return array - 273.15
        elif from_unit == "c" and to_unit == "k":
            return array + 273.15
        elif from_unit == "c" and to_unit == "f":
            return (array * 9/5) + 32
        elif from_unit == "f" and to_unit == "c":
            return (array - 32) * 5/9
        elif from_unit == "k" and to_unit == "f":
            return (array - 273.15) * 9/5 + 32
        elif from_unit == "f" and to_unit == "k":
            return (array - 32) * 5/9 + 273.15
        else:
            raise ValueError(f"Unsupported temperature conversion from {from_unit} to {to_unit}")


    @staticmethod
    def convert_bbox_to_0_360(bbox: tuple[float,float,float,float], eps=1e-9) -> list[tuple[float,float,float,float]]:
        """
        Convert a bounding box from [-180, 180] longitude to [0, 360] longitude.

        If the converted box crosses 0°, return two wrapped bounding boxes.

        Parameters:
            bbox (tuple):
                (min_lon, min_lat, max_lon, max_lat) with longitude in [-180, 180].
            eps (float):
                Small tolerance value.

        Returns:
            list: List of bounding boxes in
            (min_lon_360, min_lat, max_lon_360, max_lat) format or shapely boxes.
        """
        min_lon, min_lat, max_lon, max_lat = bbox

        # Handle antimeridian-style input like (170, ..., -170, ...) meaning it crosses -180/180 already
        if min_lon > max_lon:
            max_lon += 360.0

        # Full-world guard
        if (max_lon - min_lon) >= 360.0 - eps:
            return [(0.0, min_lat, 360.0, max_lat)]
        else:
            to360 = lambda x: x % 360.0
            lo = to360(min_lon)
            hi = to360(max_lon)

            if lo <= hi:  # no wrap in 0–360 space
                out = [(lo, min_lat, hi, max_lat)]
            else:
                # wraps across 0° in 0–360; split into two
                out = [
                    (lo,  min_lat, 360.0, max_lat),
                    (0.0, min_lat, hi,    max_lat),
                ]
            return out

    @staticmethod
    def variable_name_translation(variable_name: str) -> str:
        """
        Translate variable names between different conventions.

        Parameters:
            variable_name (str):
                The variable name to translate.

        Returns:
            str: The translated variable name.
        """
        translation_dict = {
            '2m_temperature': 't2m',
            'total_precipitation': 'tp',
        }
        return translation_dict.get(variable_name, variable_name)

convert_bbox_to_0_360(bbox, eps=1e-09) staticmethod

Convert a bounding box from [-180, 180] longitude to [0, 360] longitude.

If the converted box crosses 0°, return two wrapped bounding boxes.

Parameters:

Name Type Description Default
bbox tuple

(min_lon, min_lat, max_lon, max_lat) with longitude in [-180, 180].

 required
eps float

Small tolerance value.

 1e-09

Returns:

Name Type Description
list list[tuple[float, float, float, float]]

List of bounding boxes in
list[tuple[float, float, float, float]]

(min_lon_360, min_lat, max_lon_360, max_lat) format or shapely boxes.
Source code in c3s_event_attribution_tools/data/conversions.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
@staticmethod
def convert_bbox_to_0_360(bbox: tuple[float,float,float,float], eps=1e-9) -> list[tuple[float,float,float,float]]:
    """
    Convert a bounding box from [-180, 180] longitude to [0, 360] longitude.

    If the converted box crosses 0°, return two wrapped bounding boxes.

    Parameters:
        bbox (tuple):
            (min_lon, min_lat, max_lon, max_lat) with longitude in [-180, 180].
        eps (float):
            Small tolerance value.

    Returns:
        list: List of bounding boxes in
        (min_lon_360, min_lat, max_lon_360, max_lat) format or shapely boxes.
    """
    min_lon, min_lat, max_lon, max_lat = bbox

    # Handle antimeridian-style input like (170, ..., -170, ...) meaning it crosses -180/180 already
    if min_lon > max_lon:
        max_lon += 360.0

    # Full-world guard
    if (max_lon - min_lon) >= 360.0 - eps:
        return [(0.0, min_lat, 360.0, max_lat)]
    else:
        to360 = lambda x: x % 360.0
        lo = to360(min_lon)
        hi = to360(max_lon)

        if lo <= hi:  # no wrap in 0–360 space
            out = [(lo, min_lat, hi, max_lat)]
        else:
            # wraps across 0° in 0–360; split into two
            out = [
                (lo,  min_lat, 360.0, max_lat),
                (0.0, min_lat, hi,    max_lat),
            ]
        return out

convert_precipitation(array, from_unit, to_unit) staticmethod

Convert precipitation values from one unit to another.

This method performs in-place precipitation conversion on the provided array or pandas Series and supports meters (m) and millimeters (mm).

Parameters:

Name Type Description Default
array ndarray or Series

The input array or Series containing precipitation values to be converted.

 required
from_unit str

Source precipitation unit ('m' or 'mm'). Default is 'm'.

 required
to_unit str

Target precipitation unit ('m' or 'mm'). Default is 'mm'.

 required

Returns: np.ndarray or pd.Series: The array or Series with precipitation values converted to the target unit.

Source code in c3s_event_attribution_tools/data/conversions.py 
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
@staticmethod
def convert_precipitation(array: T, from_unit: str, to_unit: str) -> T:
    """
    Convert precipitation values from one unit to another.

    This method performs in-place precipitation conversion on the provided array or
    pandas Series and supports meters (m) and millimeters (mm).

    Parameters:
        array (np.ndarray or pd.Series):
            The input array or Series containing precipitation values to be converted.
        from_unit (str):
            Source precipitation unit ('m' or 'mm'). Default is 'm'.
        to_unit (str):
            Target precipitation unit ('m' or 'mm'). Default is 'mm'.
    Returns:
        np.ndarray or pd.Series: The array or Series with precipitation values converted to the
        target unit.
    """
    if isinstance(array, np.ndarray):
        return Conversions._inner_convert_precipitation(array, from_unit, to_unit)
    elif isinstance(array, pd.Series):
        pandas_np_array : np.ndarray = array.values # type: ignore
        return pd.Series(Conversions._inner_convert_precipitation(pandas_np_array, from_unit, to_unit))
    else:
        raise TypeError("Unsupported type for temperature conversion: " + str(type(array)))

convert_temperature(array, from_unit, to_unit) staticmethod

Convert temperature values from one unit to another.

This method performs in-place temperature conversion on the provided array or pandas Series and supports Kelvin (k), Celsius (c), and Fahrenheit (f).

Parameters:

Name Type Description Default
array ndarray or Series

The input array or Series containing temperature values to be converted.

 required
from_unit str

Source temperature unit ('k', 'c', or 'f'). Default is 'k'.

 required
to_unit str

Target temperature unit ('k', 'c', or 'f'). Default is 'c'.

 required

Returns:

Type Description
T

np.ndarray or pd.Series: The array or Series with temperature values converted to the
T

target unit.

Raises:

Type Description
ValueError

If from_unit is not one of 'k', 'c', or 'f'.
TypeError

If the input array is neither a numpy ndarray nor a pandas Series.
Notes
  • If from_unit and to_unit are identical, no conversion is performed.
  • Conversion modifies the input array or Series in place.
  • Conversion formulas:
    • Kelvin to Celsius: C = K - 273.15
    • Kelvin to Fahrenheit: F = (K - 273.15) × 9/5 + 32
    • Celsius to Kelvin: K = C + 273.15
    • Celsius to Fahrenheit: F = C × 9/5 + 32
    • Fahrenheit to Kelvin: K = (F - 32) × 5/9 + 273.15
    • Fahrenheit to Celsius: C = (F - 32) × 5/9
Source code in c3s_event_attribution_tools/data/conversions.py 
 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
@staticmethod
def convert_temperature(array: T, from_unit: str, to_unit: str) -> T:
    """
    Convert temperature values from one unit to another.

    This method performs in-place temperature conversion on the provided array or
    pandas Series and supports Kelvin (k), Celsius (c), and Fahrenheit (f).

    Parameters:
        array (np.ndarray or pd.Series):
            The input array or Series containing temperature values to be converted.
        from_unit (str, optional):
            Source temperature unit ('k', 'c', or 'f'). Default is 'k'.
        to_unit (str, optional):
            Target temperature unit ('k', 'c', or 'f'). Default is 'c'.

    Returns:
        np.ndarray or pd.Series: The array or Series with temperature values converted to the
        target unit.

    Raises:
        ValueError: If from_unit is not one of 'k', 'c', or 'f'.
        TypeError: If the input array is neither a numpy ndarray nor a pandas Series.

    Notes:
        - If from_unit and to_unit are identical, no conversion is performed.
        - Conversion modifies the input array or Series in place.
        - Conversion formulas:
            - Kelvin to Celsius: C = K - 273.15
            - Kelvin to Fahrenheit: F = (K - 273.15) × 9/5 + 32
            - Celsius to Kelvin: K = C + 273.15
            - Celsius to Fahrenheit: F = C × 9/5 + 32
            - Fahrenheit to Kelvin: K = (F - 32) × 5/9 + 273.15
            - Fahrenheit to Celsius: C = (F - 32) × 5/9
    """
    if isinstance(array, np.ndarray):
        return Conversions._inner_convert_temperature(array, from_unit, to_unit)
    elif isinstance(array, pd.Series):
        pandas_np_array : np.ndarray = array.values # type: ignore
        return pd.Series(Conversions._inner_convert_temperature(pandas_np_array, from_unit, to_unit))
    else:
        raise TypeError("Unsupported type for temperature conversion: " + str(type(array)))

convert_unit(array, from_unit, to_unit) staticmethod

Convert units of measurement for the provided array or pandas Series.

This method currently supports temperature conversions between Kelvin (k), Celsius (c), and Fahrenheit (f). Additional unit conversions can be added as needed.

Parameters:

Name Type Description Default
array ndarray or Series

The input array or Series containing values to be converted.

 required
from_unit str

Source unit of measurement (e.g., 'k', 'c', 'f', 'm').

 required
to_unit str

Target unit of measurement (e.g., 'k', 'c', 'f', 'mm').

 required

Returns: np.ndarray or pd.Series: The array or Series with values converted to the target unit.

Source code in c3s_event_attribution_tools/data/conversions.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@staticmethod
def convert_unit(array: T, from_unit: str, to_unit: str) -> T:
    """
    Convert units of measurement for the provided array or pandas Series.

    This method currently supports temperature conversions between Kelvin (k),
    Celsius (c), and Fahrenheit (f). Additional unit conversions can be added
    as needed.

    Parameters:
        array (np.ndarray or pd.Series):
            The input array or Series containing values to be converted.
        from_unit (str):
            Source unit of measurement (e.g., 'k', 'c', 'f', 'm').
        to_unit (str):
            Target unit of measurement (e.g., 'k', 'c', 'f', 'mm').
    Returns:
        np.ndarray or pd.Series: The array or Series with values converted to the
        target unit.
    """
    if from_unit in ['k', 'c', 'f'] and to_unit in ['k', 'c', 'f']:
        return Conversions.convert_temperature(array, from_unit, to_unit)
    elif from_unit in ['m', 'mm'] and to_unit in ['m', 'mm']:
        return Conversions.convert_precipitation(array, from_unit, to_unit)
    else:
        raise ValueError(f"Unsupported unit conversion from {from_unit} to {to_unit}")

variable_name_translation(variable_name) staticmethod

Translate variable names between different conventions.

Parameters:

Name Type Description Default
variable_name str

The variable name to translate.

 required

Returns:

Name Type Description
str str

The translated variable name.
Source code in c3s_event_attribution_tools/data/conversions.py 
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
@staticmethod
def variable_name_translation(variable_name: str) -> str:
    """
    Translate variable names between different conventions.

    Parameters:
        variable_name (str):
            The variable name to translate.

    Returns:
        str: The translated variable name.
    """
    translation_dict = {
        '2m_temperature': 't2m',
        'total_precipitation': 'tp',
    }
    return translation_dict.get(variable_name, variable_name)