Weights API¶
Module which calculates the weights to be used when taking SCM-box averages
This typically requires considering both the fraction of each cell which is of the desired type (e.g. land or ocean) and the area of each cell. The combination of these two pieces of information creates the weights for each cell which are used when taking area-weighted means.
-
class
netcdf_scm.weights.
AreaSurfaceFractionWeightCalculator
(cube, **kwargs)[source]¶ Bases:
netcdf_scm.weights.CubeWeightCalculator
Calculates weights which are both area and surface fraction weighted
\[\begin{split}w(lat, lon) = a(lat, lon) \\times s(lat, lon)\end{split}\]where \(w(lat, lon)\) is the weight of the cell at given latitude and longitude, \(a\) is area of the cell and \(s\) is the surface fraction of the cell (e.g. fraction of ocean area for ocean based regions).
-
get_weights
(weights_names)¶ Get a number of weights
- Parameters
weights_names (list of str) – List of weights to attempt to load/calculate.
- Returns
dict of str – Dictionary where keys are weights names and values are
np.ndarray
of bool. The result only contains valid weights. Any invalid weights are dropped.- Return type
np.ndarray
Notes
This method handles all exceptions and will only return weights which can actually be calculated. If no weights could be calculated, an empty dictionary will be returned.
-
get_weights_array
(weights_name)¶ Get a single weights array
If the weights have previously been calculated the precalculated result is returned from the cache. Otherwise the appropriate WeightFunc is called with any kwargs specified in the constructor.
- Parameters
weights_name (str) – Region to get weights for
- Returns
Weights for the region specified by
weights_name
- Return type
ndarray[bool]
- Raises
InvalidWeightsError – If the cube has no data which matches the input weights or is invalid in any other way
-
get_weights_array_without_area_weighting
(weights_name)¶ Get a single normalised weights array without any consideration of area weighting
The weights are normalised to be in the range [0, 1]
- Parameters
weights_name (str) – Region to get weights for
- Returns
Weights, normalised to be in the range [0, 1]
- Return type
np.ndarray
- Raises
InvalidWeightsError – If the requested weights cannot be found or evaluated
ValueError – The retrieved weights are not normalised to the range [0, 1]
-
-
class
netcdf_scm.weights.
AreaWeightCalculator
(cube, **kwargs)[source]¶ Bases:
netcdf_scm.weights.CubeWeightCalculator
Calculates weights which are area weighted but surface fraction aware.
This means that any cells which have a surface fraction of zero will receive zero weight, otherwise cells are purely area weighted.
\[\begin{split}w(lat, lon) = \\begin{cases} a(lat, lon), & s(lat, lon) > 0 \\\\ 0, & s(lat, lon) = 0 \\end{cases}\end{split}\]where \(w(lat, lon)\) is the weight of the cell at given latitude and longitude, \(a\) is area of the cell and \(s\) is the surface fraction of the cell (e.g. fraction of ocean area for ocean based regions).
-
get_weights
(weights_names)¶ Get a number of weights
- Parameters
weights_names (list of str) – List of weights to attempt to load/calculate.
- Returns
dict of str – Dictionary where keys are weights names and values are
np.ndarray
of bool. The result only contains valid weights. Any invalid weights are dropped.- Return type
np.ndarray
Notes
This method handles all exceptions and will only return weights which can actually be calculated. If no weights could be calculated, an empty dictionary will be returned.
-
get_weights_array
(weights_name)¶ Get a single weights array
If the weights have previously been calculated the precalculated result is returned from the cache. Otherwise the appropriate WeightFunc is called with any kwargs specified in the constructor.
- Parameters
weights_name (str) – Region to get weights for
- Returns
Weights for the region specified by
weights_name
- Return type
ndarray[bool]
- Raises
InvalidWeightsError – If the cube has no data which matches the input weights or is invalid in any other way
-
get_weights_array_without_area_weighting
(weights_name)¶ Get a single normalised weights array without any consideration of area weighting
The weights are normalised to be in the range [0, 1]
- Parameters
weights_name (str) – Region to get weights for
- Returns
Weights, normalised to be in the range [0, 1]
- Return type
np.ndarray
- Raises
InvalidWeightsError – If the requested weights cannot be found or evaluated
ValueError – The retrieved weights are not normalised to the range [0, 1]
-
-
class
netcdf_scm.weights.
CubeWeightCalculator
(cube, **kwargs)[source]¶ Bases:
abc.ABC
Computes weights for a given cube in a somewhat efficient manner.
Previously calculated weights are cached so each set of weights is only calculated once. This implementation trades off some additional memory overhead for the ability to generate arbitary weights.
Adding new weights
Additional weights can be added to
netcdf_scm.weights.weights
. The values inweights
should be WeightFunc’s. A WeightFunc is a function which takes a ScmCube, CubeWeightCalculator and any additional keyword arguments. The function should return a numpy array with the same dimensionality as the ScmCube.These WeightFunc’s can be composed together to create more complex functionality using e.g.
multiply_weights
.-
get_weights
(weights_names)[source]¶ Get a number of weights
- Parameters
weights_names (list of str) – List of weights to attempt to load/calculate.
- Returns
dict of str – Dictionary where keys are weights names and values are
np.ndarray
of bool. The result only contains valid weights. Any invalid weights are dropped.- Return type
np.ndarray
Notes
This method handles all exceptions and will only return weights which can actually be calculated. If no weights could be calculated, an empty dictionary will be returned.
-
get_weights_array
(weights_name)[source]¶ Get a single weights array
If the weights have previously been calculated the precalculated result is returned from the cache. Otherwise the appropriate WeightFunc is called with any kwargs specified in the constructor.
- Parameters
weights_name (str) – Region to get weights for
- Returns
Weights for the region specified by
weights_name
- Return type
ndarray[bool]
- Raises
InvalidWeightsError – If the cube has no data which matches the input weights or is invalid in any other way
-
get_weights_array_without_area_weighting
(weights_name)[source]¶ Get a single normalised weights array without any consideration of area weighting
The weights are normalised to be in the range [0, 1]
- Parameters
weights_name (str) – Region to get weights for
- Returns
Weights, normalised to be in the range [0, 1]
- Return type
np.ndarray
- Raises
InvalidWeightsError – If the requested weights cannot be found or evaluated
ValueError – The retrieved weights are not normalised to the range [0, 1]
-
-
exception
netcdf_scm.weights.
InvalidWeightsError
[source]¶ Bases:
Exception
Raised when a weight cannot be calculated.
This error usually propogates. For example, if a child weight used in the calculation of a parent weight fails then the parent weight should also raise an InvalidWeightsError exception (unless it can be satisfactorily handled).
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
netcdf_scm.weights.
get_ar6_region_weights
(region)[source]¶ Get a function to calculate the weights for a given AR6 region
AR6 regions defined in Iturbide et al., 2020 https://essd.copernicus.org/preprints/essd-2019-258/
- Parameters
region (str) – AR6 region to extract
- Returns
WeightFunc which weights out everything except the specified area
- Return type
WeightFunc()
-
netcdf_scm.weights.
get_binary_nh_weights
(weight_calculator, cube, **kwargs)[source]¶ Get binary weights to only include the Northern Hemisphere
- Parameters
weight_calculator (
CubeWeightCalculator
) – Cube weight calculator from which to retrieve the weightscube (
ScmCube
) – Cube to create weights forkwargs (Any) – Ignored (required for compatibility with
CubeWeightCalculator
)
- Returns
Binary northern hemisphere weights
- Return type
np.ndarray
-
netcdf_scm.weights.
get_default_sftlf_cube
[source]¶ Load netCDF-SCM’s default (last resort) surface land fraction cube
-
netcdf_scm.weights.
get_land_weights
(weight_calculator, cube, sftlf_cube=None, **kwargs)[source]¶ Get the land weights
The weights are always adjusted to have units of percentage. If the units are detected to be fraction rather than percentage, they will be automatically adjusted and a warning will be thrown.
If the default sftlf cube is used, it is regridded onto
cube
’s grid using a linear interpolation. We hope to use an area-weighted regridding in future but at the moment its performance is not good enough to be put into production ( approximately 100x slower than the linear interpolation regridding).- Parameters
weight_calculator (
CubeWeightCalculator
) – Cube weight calculator from which to retrieve the weightscube (
ScmCube
) – Cube to create weights forsftlf_cube (
ScmCube
) – Cube containing the surface land-fraction datakwargs (Any) – Ignored (required for compatibility with
CubeWeightCalculator
)
- Returns
Land weights
- Return type
np.ndarray
- Raises
AssertionError – The land weights are incompatible with the cube’s lat-lon grid
-
netcdf_scm.weights.
get_nh_weights
(weight_calculator, cube, **kwargs)[source]¶ Get weights to only include the Northern Hemisphere
- Parameters
weight_calculator (
CubeWeightCalculator
) – Cube weight calculator from which to retrieve the weightscube (
ScmCube
) – Cube to create weights forkwargs (Any) – Ignored (required for compatibility with
CubeWeightCalculator
)
- Returns
Northern hemisphere weights
- Return type
np.ndarray
-
netcdf_scm.weights.
get_ocean_weights
(weight_calculator, cube, sftof_cube=None, **kwargs)[source]¶ Get the ocean weights
The weights are always adjusted to have units of percentage.
- Parameters
weight_calculator (
CubeWeightCalculator
) – Cube weight calculator from which to retrieve the weightscube (
ScmCube
) – Cube to create weights forsftof_cube (
ScmCube
) – Cube containing the surface ocean-fraction datakwargs (Any) – Ignored (required for compatibility with
CubeWeightCalculator
)
- Returns
Ocean weights
- Return type
np.ndarray
- Raises
AssertionError – The ocean weights are incompatible with the cube’s lat-lon grid
-
netcdf_scm.weights.
get_sh_weights
(weight_calculator, cube, **kwargs)[source]¶ Get weights to only include the Southern Hemisphere
- Parameters
weight_calculator (
CubeWeightCalculator
) – Cube weight calculator from which to retrieve the weightscube (
ScmCube
) – Cube to create weights forkwargs (Any) – Ignored (required for compatibility with
CubeWeightCalculator
)
- Returns
Southern hemisphere weights
- Return type
np.ndarray
-
netcdf_scm.weights.
get_weights_for_area
(lower_lat, left_lon, upper_lat, right_lon)[source]¶ Weights a subset of the globe using latitudes and longitudes (in degrees East)
Iris’ standard behaviour is to include any point whose bounds overlap with the given ranges e.g. if the range is (0, 130) then a cell whose bounds were (-90, 5) would be included even if its point were -42.5.
This can be altered with the
ignore_bounds
keyword argument tocube.intersection
. In this case only cells whose points lie within the range are included so if the range is (0, 130) then a cell whose bounds were (-90, 5) would be excluded if its point were -42.5.Here we follow the
ignore_bounds=True
behaviour (i.e. only include if the point lies within the specified range). If we want to only include the cell if the entire box is within a point we’re going to need to tweak things. Given this isn’t available in iris, it seems to be an unusual way to do intersection so we haven’t implemented it.Circular coordinates (longitude) can cross the 0E.
- Parameters
- Returns
WeightFunc which weights out everything except the specified area
- Return type
WeightFunc()
-
netcdf_scm.weights.
get_world_weights
(weight_calculator, cube, **kwargs)[source]¶ Get weights for the world
- Parameters
weight_calculator (
CubeWeightCalculator
) – Cube weight calculator from which to retrieve the weightscube (
ScmCube
) – Cube to create weights forkwargs (Any) – Ignored (required for compatibility with
CubeWeightCalculator
)
- Returns
Weights which can be used for the world mean calculation
- Return type
np.ndarray
-
netcdf_scm.weights.
multiply_weights
(weight_a, weight_b)[source]¶ Take the product of two weights
- Parameters
weight_a (str or WeightFunc) – If a string is provided, the weights specified by the string are retrieved. Otherwise the WeightFunc is evaluated at runtime
weight_b (str or WeightFunc) – If a string is provided, the weights specified by the string are retrieved. Otherwise the WeightFunc is evaluated at runtime
- Returns
WeightFunc which multiplies the input weights
- Return type
WeightFunc()
-
netcdf_scm.weights.
subtract_weights
(weights_to_subtract, subtract_from)[source]¶ Subtract weights from some other number
e.g. useful to convert e.g. from fraction of land to ocean (where ocean fractions are 1 - land fractions)
- Parameters
- Returns
WeightFunc which subtracts the input weights from
subtract_from
- Return type
WeightFunc()