gcpy.units

Contains methods for converting the units of data. Mainly used for model benchmarking purposes.

Functions

adjust_units(units)

Creates a consistent unit string used in unit conversion routines.

check_units(ref_da, dev_da[, enforce_units])

Ensures the units of two xarray DataArrays are the same.

convert_kg_to_target_units(data_kg, ...)

Converts a data array from kg to one of several target unit types.

convert_units(dr, species_name, ...[, ...])

Converts data in an xarray DataArray from native units to target units.

data_unit_is_mol_per_mol(da)

Checks whether the units of an xarray DataArray are mol/mol.
gcpy.units.adjust_units(units)[source]

Creates a consistent unit string used in unit conversion routines.

Parameters:

units (str) – Input unit string.

Returns:

adjusted_units – Output unit string, adjusted to a consistent value.

Return type:

str

Raises:

TypeError – If units is not of type str.

Notes

Unit list is incomplete – currently geared to units from common model diagnostics (e.g. kg/m2/s, kg, and variants).

Examples

>>> adjust_units("kg m-2 s-1")
'kg/m2/s'
>>> adjust_units("kgC/m2/s")
'kgC/m2/s'
gcpy.units.convert_kg_to_target_units(data_kg, target_units, kg_to_kgC)[source]

Converts a data array from kg to one of several target unit types.

Parameters:

  • data_kg (numpy.ndarray) – Input data array in units of kg.

  • target_units (str) – Name of the target units. Supported values include: 'Tg', 'Tg C', 'Gg', 'Gg C', 'Mg', 'Mg C', 'kg', 'kg C', 'g', 'g C'.

  • kg_to_kgC (float) – Conversion factor from kg species to kg carbon.

Returns:

data – Output data array converted to the units specified by target_units.

Return type:

numpy.ndarray

Raises:

ValueError – If target_units is not a supported unit string.

Notes

Only unit conversions corresponding to the GEOS-Chem benchmarks have been implemented. This is an internal routine intended to be called from convert_units().

Examples

>>> import numpy as np
>>> data_kg = np.array([1.0e9, 2.0e9])
>>> convert_kg_to_target_units(data_kg, 'Tg', 1.0)
array([1., 2.])
gcpy.units.convert_units(dr, species_name, species_properties, target_units, interval=[2678400.0], area_m2=None, delta_p=None, box_height=None)[source]

Converts data in an xarray DataArray from native units to target units.

Parameters:

  • dr (xarray.DataArray) – Data to be converted from native units to target units.

  • species_name (str) – Name of the species corresponding to the data stored in dr.

  • species_properties (dict) – Dictionary containing species properties such as molecular weights and other metadata for the given species.

  • target_units (str) – Units to which the data will be converted.

  • interval (list of float, optional) – Length of the averaging period in seconds. Default: [2678400.0]

  • area_m2 (xarray.DataArray, optional) – Surface area in square metres. Default: None

  • delta_p (xarray.DataArray, optional) – Delta-pressure between top and bottom edges of grid box (dry air) in hPa. Default: None

  • box_height (xarray.DataArray, optional) – Grid box height in metres. Default: None

Returns:

dr_new – Data converted to target_units. Identical to dr except for the data values and the units attribute.

Return type:

xarray.DataArray

Raises:

  • ValueError – If MW_g is not found in species_properties.

  • ValueError – If conversion from molmol-1dry is requested but area_m2 or delta_p are not provided.

  • ValueError – If a mass unit (containing 'g') is requested but MW_g is None.

  • ValueError – If interval has length > 1 but dr has no time dimension.

  • ValueError – If the native units of dr are not supported.

Notes

Only unit conversions corresponding to common GEOS-Chem benchmark output have been implemented. When molmol-1 is present as the unit, dry air is assumed.

Examples

>>> dr_converted = convert_units(
...     dr, 'O3', species_props, 'Tg',
...     interval=[2678400.0], area_m2=area
... )
gcpy.units.check_units(ref_da, dev_da, enforce_units=True)[source]

Ensures the units of two xarray DataArrays are the same.

Parameters:

  • ref_da (xarray.DataArray) – First data array containing a units attribute.

  • dev_da (xarray.DataArray) – Second data array containing a units attribute.

  • enforce_units (bool, optional) – Whether to raise an AssertionError if ref and dev units do not match. Default: True

Returns:

units_match – True if the units of ref_da and dev_da match, False otherwise.

Return type:

bool

Raises:

AssertionError – If enforce_units is True and the units do not match.

Examples

>>> match = check_units(ref_da, dev_da, enforce_units=False)
>>> print(match)
True
gcpy.units.data_unit_is_mol_per_mol(da)[source]

Checks whether the units of an xarray DataArray are mol/mol.

Parameters:

da (xarray.DataArray) – Data array containing a units attribute.

Returns:

is_molmol – True if the units attribute of da is a recognised mol/mol unit string, False otherwise.

Return type:

bool

Notes

Recognised mol/mol unit strings are: 'mol mol-1 dry', 'mol/mol', 'mol mol-1'.

Examples

>>> data_unit_is_mol_per_mol(da)
True