gcpy.units
Contains methods for converting the units of data. Mainly used for model benchmarking purposes.
Module Contents
Functions
|
Creates a consistent unit string that will be used in the unit |
|
Converts a data array from kg to one of several types of target units. |
|
Converts data stored in an xarray DataArray object from its native |
|
Ensures the units of two xarray DataArrays are the same. |
Check if the units of an xarray DataArray are mol/mol based on a set |
- gcpy.units.adjust_units(units)
Creates a consistent unit string that will be used in the unit conversion routines below.
- Args:
- units: str
Input unit string.
- Returns:
- adjusted_units: str
Output unit string, adjusted to a consistent value.
- Remarks:
Unit list is incomplete – currently is geared to units from common model diagnostics (e.g. kg/m2/s, kg, and variants).
- gcpy.units.convert_kg_to_target_units(data_kg, target_units, kg_to_kgC)
Converts a data array from kg to one of several types of target units.
- Args:
- data_kg: numpy ndarray
Input data array, in units of kg.
- target_units: str
String containing the name of the units to which the “data_kg” argument will be converted. Examples: ‘Tg’, ‘Tg C’, ‘Mg’, ‘Mg C’, ‘kg, ‘kg C’, etc.
- kg_to_kg_C: float
Conversion factor from kg to kg carbon.
- Returns:
- data: numpy ndarray
Ouptut data array, converted to the units specified by the ‘target_units’ argument.
- Remarks:
At present, only those unit conversions corresponding to the GEOS-Chem benchmarks have been implemented.
This is an internal routine, which is meant to be called directly from convert_units.
- gcpy.units.convert_units(dr, species_name, species_properties, target_units, interval=[2678400.0], area_m2=None, delta_p=None, box_height=None)
Converts data stored in an xarray DataArray object from its native units to a target unit.
- Args:
- 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 (e.g. molecular weights and other metadata) for the given species.
- target_units: str
Units to which the data will be converted.
- Keyword Args (optional):
- interval: float
The length of the averaging period in seconds. Default value: [2678400.0]
- area_m2: xarray DataArray
Surface area in square meters Default value: None
- delta_p: xarray DataArray
Delta-pressure between top and bottom edges of grid box (dry air) in hPa Default value: None
- box_height: xarray DataArray
Grid box height in meters Default value: None
- Returns:
- dr_new: xarray DataArray
Data converted to target units.
- Remarks:
At present, only certain types of unit conversions have been implemented (corresponding to the most commonly used unit conversions for model benchmark output).
When molmol-1 is present as unit, assumes dry air.
- gcpy.units.check_units(ref_da, dev_da, enforce_units=True)
Ensures the units of two xarray DataArrays are the same.
- Args:
- ref_da: xarray DataArray
First data array containing a units attribute.
- dev_da: xarray DataArray
Second data array containing a units attribute.
- Keyword Args (optional):
- enforce_units: bool
Whether to stop program if ref and dev units do not match Default value: True
- Returns:
units_match: bool
- gcpy.units.data_unit_is_mol_per_mol(da)
Check if the units of an xarray DataArray are mol/mol based on a set list of unit strings mol/mol may be.
- Args:
- da: xarray DataArray
Data array containing a units attribute
- Returns:
- is_molmol: bool
Whether input units are mol/mol