openairclim.core.utils

Utility functions used over the entire framework.

openairclim.core.utils.convert_mass_or_annual_rate(value: float | ndarray, src_units: str, target_units: str) → float | ndarray[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 numpy.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 numpy.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: dict) → dict[source]

Convert nested dictionary to dictionary of numpy.ndarrays / time series.

Parameters:: nested_dict (dict) – Dictionary of dictionaries, keys are species, years. {spec: {year: numpy.ndarray, ...}, ...}
Returns:: Dictionary of numpy.ndarrays / time series, keys are species. {spec: numpy.ndarray, ...}
Return type:: dict

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

Convert flat / unstructured xarray into xarray with a regular grid.

Regular 3D grid lon/lat/plev.

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

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: list[str | Path]) → list[str][source]

Find basenames of a list of paths.

Parameters:: path_lst (list[str or Path]) – List of paths
Returns:: List of basenames
Return type:: list[str]

openairclim.core.utils.kgco2_to_tgc(co2: float) → float[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 | ndarray, unit_str: str | None) → Quantity[source]

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

Parameters:

value (float or numpy.ndarray) – Numeric value(s).
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: float | ndarray) → float | ndarray[source]

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

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

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 | ndarray[source]

Convert a pint Quantity to a plain float (or array) 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 or numpy.ndarray

Raises:

ValueError – If target_units is incompatible or unparseable.