Weights API¶
Module which calculates the weights to be used when taking SCMbox 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 areaweighted 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, log_failure=False)¶ Get a number of weights
 Parameters
weights_names (list of str) – List of weights to attempt to load/calculate.
log_failure (bool) – Should failures be logged? If no, failures are raised as warnings.
 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, log_failure=False)¶ Get a number of weights
 Parameters
weights_names (list of str) – List of weights to attempt to load/calculate.
log_failure (bool) – Should failures be logged? If no, failures are raised as warnings.
 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, log_failure=False)[source]¶ Get a number of weights
 Parameters
weights_names (list of str) – List of weights to attempt to load/calculate.
log_failure (bool) – Should failures be logged? If no, failures are raised as warnings.
 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/essd2019258/
 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 netCDFSCM’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 areaweighted 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 landfraction 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 latlon grid

netcdf_scm.weights.
get_natural_earth_50m_scale_region_weights
(region)[source]¶ Get a function to calculate the weights for a given Natural Earth defined region
We use the 50m scale from Natural Earth and the implementation provided by regionmask.
 Parameters
region (str) – Natural Earth region to extract
 Returns
WeightFunc which weights out everything except the specified area
 Return type
WeightFunc()

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 oceanfraction 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 latlon 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()