Auxiliary functions for MLR scripts¶
Convenience functions for MLR diagnostics.
Functions:
|
Check keyword argument for |
|
Create alias key of a dataset using a list of attributes. |
|
Check (MLR) attributes of |
|
Convert 2 arrays to |
|
Convert time reference units to absolute ones. |
|
Get alias for dataset. |
|
Get all possible weights of cube. |
|
Get area weights of cube. |
|
Get horizontal weights of cube. |
|
Get input data and check MLR attributes if desired. |
|
Get land/sea fraction weights of cube using Natural Earth files. |
|
Convert old path to new diagnostic path. |
|
Get array of squared errors. |
|
Get time weights of cube. |
Ignore warnings given by |
|
|
Take the square root of the cube metadata. |
|
Raise a |
- esmvaltool.diag_scripts.mlr.check_predict_kwargs(predict_kwargs)[source]¶
Check keyword argument for
predict()
functions.- Parameters
predict_kwargs (keyword arguments, optional) – Keyword arguments for a
predict()
function.- Raises
RuntimeError –
return_var
andreturn_cov
are both set toTrue
in the keyword arguments.
- esmvaltool.diag_scripts.mlr.create_alias(dataset, attributes, delimiter='-')[source]¶
Create alias key of a dataset using a list of attributes.
- Parameters
- Returns
Dataset alias.
- Return type
- Raises
AttributeError –
dataset
does not contain one of theattributes
.
- esmvaltool.diag_scripts.mlr.datasets_have_mlr_attributes(datasets, log_level='debug', mode='full')[source]¶
Check (MLR) attributes of
datasets
.- Parameters
datasets (list of dict) – Datasets to check.
log_level (str, optional (default: 'debug')) – Verbosity level of the logger.
mode (str, optional (default: 'full')) – Checking mode. Must be one of
'only_missing'
(only check if attributes are missing),'only_var_type'
(check only var_type) or'full'
(check both).
- Returns
True
if all required attributes are available,False
if not.- Return type
- Raises
ValueError – Invalid value for argument
mode
is given.
- esmvaltool.diag_scripts.mlr.get_1d_cube(x_data, y_data, x_kwargs=None, y_kwargs=None)[source]¶
Convert 2 arrays to
iris.cube.Cube
(with single coordinate).- Parameters
x_data (numpy.ndarray) – Data for coordinate.
y_data (numpy.ndarray) – Data for cube.
x_kwargs (dict) – Keyword arguments passed to
iris.coords.AuxCoord
.y_kwargs (dict) – Keyword arguments passed to
iris.cube.Cube
.
- Returns
1D cube with single auxiliary coordinate.
- Return type
- Raises
ValueError – Arrays are not 1D and do not have matching shapes.
- esmvaltool.diag_scripts.mlr.get_absolute_time_units(units)[source]¶
Convert time reference units to absolute ones.
This function converts reference time units (like
'days since YYYY'
) to absolute ones (like'days'
).- Parameters
units (cf_units.Unit) – Time units to convert.
- Returns
Absolute time units.
- Return type
- Raises
ValueError – If conversion failed (e.g. input units are not time units).
- esmvaltool.diag_scripts.mlr.get_all_weights(cube, area_weighted=True, time_weighted=True, landsea_fraction_weighted=None, normalize=False)[source]¶
Get all possible weights of cube.
- Parameters
cube (iris.cube.Cube) – Input cube.
area_weighted (bool, optional (default: True)) – Use area weights.
time_weighted (bool, optional (default: True)) – Use time weights.
landsea_fraction_weighted (str, optional) – If given, use land/sea fraction weights. Must be one of
'land'
,'sea'
.normalize (bool, optional (default: False)) – Normalize weights with total area and total time range.
- Returns
Area weights.
- Return type
- esmvaltool.diag_scripts.mlr.get_area_weights(cube, normalize=False)[source]¶
Get area weights of cube.
- Parameters
cube (iris.cube.Cube) – Input cube.
normalize (bool, optional (default: False)) – Normalize weights with total area.
- Returns
Area weights.
- Return type
- Raises
iris.exceptions.CoordinateNotFoundError – Cube does not contain the coordinates
latitude
andlongitude
.
- esmvaltool.diag_scripts.mlr.get_horizontal_weights(cube, area_weighted=True, landsea_fraction_weighted=None, normalize=False)[source]¶
Get horizontal weights of cube.
- Parameters
cube (iris.cube.Cube) – Input cube.
area_weighted (bool, optional (default: True)) – Use area weights.
landsea_fraction_weighted (str, optional) – If given, use land/sea fraction weights. Must be one of
'land'
,'sea'
.normalize (bool, optional (default: False)) – Normalize weights with sum of weights over latitude and longitude (i.e. if only
area_weighted
is given, this is equal to the total area).
- Returns
Area weights.
- Return type
- Raises
iris.exceptions.CoordinateMultiDimError – Dimension of latitude or longitude coordinate is greater than 1.
iris.exceptions.CoordinateNotFoundError – Cube does not contain the coordinates
latitude
andlongitude
.ValueError –
landsea_fraction_weighted
is not one of'land'
,'sea'
.
- esmvaltool.diag_scripts.mlr.get_input_data(cfg, pattern=None, check_mlr_attributes=True, ignore=None)[source]¶
Get input data and check MLR attributes if desired.
Use
input_data
and ancestors to get all relevant input files.- Parameters
cfg (dict) – Recipe configuration.
pattern (str, optional) – Pattern matched against ancestor file names.
check_mlr_attributes (bool, optional (default: True)) – If
True
, only returns datasets with valid MLR attributes. IfFalse
, returns all found datasets.ignore (list of dict, optional) – Ignore specific datasets by specifying multiple
dict`s of metadata. By setting an attribute to ``None`
, ignore all datasets which do not have that attribute.
- Returns
List of input datasets.
- Return type
list of dict
- Raises
ValueError – No input data found or at least one dataset has invalid attributes.
- esmvaltool.diag_scripts.mlr.get_landsea_fraction_weights(cube, area_type, normalize=False)[source]¶
Get land/sea fraction weights of cube using Natural Earth files.
Note
The implementation of this feature is not optimal. For large cubes, calculating the land/sea fraction weights might be very slow.
- Parameters
cube (iris.cube.Cube) – Input cube.
area_type (str) – Area type. Must be one of
'land'
(land fraction weighting) or'sea'
(sea fraction weighting).normalize (bool, optional (default: False)) – Normalize weights with total land/sea fraction.
- Raises
iris.exceptions.CoordinateMultiDimError – Dimension of latitude or longitude coordinate is greater than 1.
iris.exceptions.CoordinateNotFoundError – Cube does not contain the coordinates
latitude
andlongitude
.ValueError –
area_type
is not one of'land'
,'sea'
.
- esmvaltool.diag_scripts.mlr.get_new_path(cfg, old_path)[source]¶
Convert old path to new diagnostic path.
- esmvaltool.diag_scripts.mlr.get_squared_error_cube(ref_cube, error_datasets)[source]¶
Get array of squared errors.
- Parameters
ref_cube (iris.cube.Cube) – Reference cube (determines mask, coordinates and attributes of output).
error_datasets (list of dict) – List of metadata dictionaries where each dictionary represents a single dataset.
- Returns
Cube containing squared errors.
- Return type
- Raises
ValueError – Shape of a dataset does not match shape of reference cube.
- esmvaltool.diag_scripts.mlr.get_time_weights(cube, normalize=False)[source]¶
Get time weights of cube.
- Parameters
cube (iris.cube.Cube) – Input cube.
normalize (bool, optional (default: False)) – Normalize weights with total time range.
- Returns
Time weights.
- Return type
- Raises
iris.exceptions.CoordinateNotFoundError – Cube does not contain the coordinate
time
.
- esmvaltool.diag_scripts.mlr.square_root_metadata(cube)[source]¶
Take the square root of the cube metadata.
- Parameters
cube (iris.cube.Cube) – Cube (will be modified in-place).
- esmvaltool.diag_scripts.mlr.units_power(units, power)[source]¶
Raise a
cf_units.Unit
to given power preserving symbols.Raise
cf_units.Unit
to given power without expanding it first. For example, usingunits_power(Unit('J'), 2)
givesUnit('J2')
. In contrast, simply usingUnit('J')**2
would yield'kg2 m4 s-4'
.- Parameters
units (cf_units.Unit) – Input units.
power (int) – Desired exponent.
- Returns
Input units raised to given power.
- Return type
- Raises
ValueError – Invalid unit given.