openairclim.core.utils

Utility functions used over the entire framework

openairclim.core.utils.convert_mass_or_annual_rate(value, src_units: str, target_units: str)[source]

Convert a mass, or a mass accumulated per year, to target_units.

Some inputs (e.g. a time evolution file’s “fuel” variable) declare units as a rate (mass per year, e.g. “Tg yr-1”) that actually represents a total accumulated over exactly one year, not a true rate meant to be integrated over an arbitrary duration – so such a rate is cancelled by multiplying by exactly one year (exact, via unit algebra), rather than converted as a rate. A plain mass (e.g. “kg”, “Tg”) is converted directly.

Parameters:

value (float or np.ndarray) – Value(s) to convert.
src_units (str) – Source unit string – either a mass or a mass accumulated per year.
target_units (str) – Target unit string (a mass, e.g. “kg”).

Returns:

Converted value(s).

Return type:

float or np.ndarray

Raises:

ValueError – If src_units is neither a mass nor a mass-per-year rate, or target_units is incompatible/unparseable.

openairclim.core.utils.convert_nested_to_series(nested_dict)[source]

Convert nested dictionary to dictionary of np.arrays / time series

Parameters:

nested_dict (dict) – Dictionary of dictionaries, keys are species, years
{spec – {year: np.array, …}, …}

Returns:

Dictionary of np.arrays / time series, keys are species {spec: np.array, np.array, …}

Return type:

dict

openairclim.core.utils.convert_to_regular(inv)[source]

Convert flat / unstructured xarray into xarray with regular 3D grid lon/lat/plev

Parameters:: inv (xarray) – flat / unstructured xarray
Returns:: regular xarray with dimension lon/lat/plev
Return type:: xarray

openairclim.core.utils.convert_units(value: float, src_units: str, target_units: str) → float[source]

Convert a value between two UDUNITS/CF-style unit strings.

Parameters:

value (float) – Value to convert.
src_units (str) – Source unit string.
target_units (str) – Target unit string.

Returns:

Converted value.

Return type:

float

Raises:

ValueError – If the units aren’t parseable or compatible.

openairclim.core.utils.find_basenames(path_lst)[source]

Find basenames of a list of paths

Parameters:: path_arr (list) – List of paths
Returns:: List of basenames
Return type:: list

openairclim.core.utils.kgco2_to_tgc(co2)[source]

Converts mass of CO2 in kg to mass of C in Tg

Parameters:: co2 (float) – Mass of CO2 in kg
Returns:: Mass of C in Tg
Return type:: float

openairclim.core.utils.quantity(value: float, unit_str: str | None) → Quantity[source]

Build a pint Quantity from a value and a UDUNITS/CF-style unit string.

Parameters:

value (float) – Numeric value.
unit_str (str or None) – UDUNITS/CF-style unit string.

Returns:

The value tagged with its parsed unit.

Return type:

pint.Quantity

Raises:

ValueError – If unit_str isn’t parseable. pint raises a mix of pint.errors.PintError subclasses and bare TypeError (e.g. for “incorrect-unit”, where the “-” is parsed as a subtraction operator between two undefined identifiers).

openairclim.core.utils.tgco2_to_tgc(co2)[source]

Converts mass of CO2 in Tg to mass of C in Tg

Parameters:: co2 (float) – Mass of CO2 in Tg
Returns:: Mass of C in Tg
Return type:: float

openairclim.core.utils.to_pint_units(unit_str: str | None) → str[source]

Rewrite a UDUNITS/CF-style unit string into pint syntax.

pint doesn’t parse UDUNITS’ compact compound-unit notation (space means multiply, a trailing integer means exponent, e.g. “Tg yr-1” or “kg m-2 s-1”) on its own, so this rewrites each whitespace-separated token’s trailing exponent into pint’s “**” form and joins tokens with “*”.

Parameters:: unit_str (str or None) – UDUNITS/CF-style unit string, e.g. “kg”, “Tg yr-1”, “1” or “” for dimensionless.
Returns:: Equivalent unit string in pint syntax.
Return type:: str
Raises:: ValueError – If unit_str already contains “**” — CF/UDUNITS never uses it (exponents are a bare suffix, e.g. “m-2”), so its presence means the string is in the wrong convention (e.g. already pint syntax) rather than just an unusual CF string.

openairclim.core.utils.to_value(qty: Quantity, target_units: str) → float[source]

Convert a pint Quantity to a plain float in target_units.

Parameters:

qty (pint.Quantity) – Quantity to convert.
target_units (str) – Target UDUNITS/CF-style unit string.

Returns:

qty’s magnitude expressed in target_units.

Return type:

float

Raises:

ValueError – If target_units is incompatible or unparseable.