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.