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, 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 in weights 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/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 weights

  • cube (ScmCube) – Cube to create weights for

  • kwargs (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 weights

  • cube (ScmCube) – Cube to create weights for

  • sftlf_cube (ScmCube) – Cube containing the surface land-fraction data

  • kwargs (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_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 weights

  • cube (ScmCube) – Cube to create weights for

  • kwargs (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 weights

  • cube (ScmCube) – Cube to create weights for

  • sftof_cube (ScmCube) – Cube containing the surface ocean-fraction data

  • kwargs (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 weights

  • cube (ScmCube) – Cube to create weights for

  • kwargs (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 to cube.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
  • lower_lat (int or float) – Lower latitude bound (degrees North)

  • left_lon (int or float) – Lower longitude bound (degrees East)

  • upper_lat (int or float) – Upper latitude bound (degrees North)

  • right_lon (int or float) – Upper longitude bound (degrees East)

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 weights

  • cube (ScmCube) – Cube to create weights for

  • kwargs (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
  • weights_to_subtract (str) – Name of the weights to subtract. These weights are loaded at evaluation time.

  • subtract_from (float) – The number from which to subtract the values of weights_to_invert (once loaded)

Returns

WeightFunc which subtracts the input weights from subtract_from

Return type

WeightFunc()