improver.threshold module

Module containing thresholding classes.

class BasicThreshold(thresholds, fuzzy_factor=None, fuzzy_bounds=None, threshold_units=None, comparison_operator='>', each_threshold_func=())[source]

Bases: PostProcessingPlugin

Apply a threshold truth criterion to a cube.

Calculate the threshold truth values based on a linear membership function around the threshold values provided. A cube will be returned with a new threshold dimension coordinate.

Can operate on multiple time sequences within a cube.

__init__(thresholds, fuzzy_factor=None, fuzzy_bounds=None, threshold_units=None, comparison_operator='>', each_threshold_func=())[source]

Set up for processing an in-or-out of threshold field, including the generation of fuzzy_bounds which are required to threshold an input cube (through self.process(cube)). If fuzzy_factor is not None, fuzzy bounds are calculated using the threshold value in the units in which it is provided.

The usage of fuzzy_factor is exemplified as follows:

For a 6 mm/hr threshold with a 0.75 fuzzy factor, a range of 25% around this threshold (between (6*0.75=) 4.5 and (6*(2-0.75)=) 7.5) would be generated. The probabilities of exceeding values within this range are scaled linearly, so that 4.5 mm/hr yields a thresholded value of 0 and 7.5 mm/hr yields a thresholded value of 1. Therefore, in this case, the thresholded exceedance probabilities between 4.5 mm/hr and 7.5 mm/hr would follow the pattern:

Data value  | Probability
------------|-------------
5     |   0
0     |   0.167
5     |   0.333
0     |   0.5
5     |   0.667
0     |   0.833
5     |   1.0

Parameters

thresholds (Union[float, List[float]]) – Values at which to evaluate the input data using the specified comparison operator.
fuzzy_factor (Optional[float]) – Optional: specifies lower bound for fuzzy membership value when multiplied by each threshold. Upper bound is equivalent linear distance above threshold.
fuzzy_bounds (Union[Tuple[float, float], List[Tuple[float, float]], None]) – Optional: lower and upper bounds for fuzziness. Each entry in list should be a tuple of two floats representing the lower and upper bounds respectively. Tuple or list should match length of (or scalar) ‘thresholds’ argument. Should not be set if fuzzy_factor is set.
threshold_units (Optional[str]) – Units of the threshold values. If not provided the units are assumed to be the same as those of the input cube.
comparison_operator (str) – Indicates the comparison_operator to use with the threshold. e.g. ‘ge’ or ‘>=’ to evaluate ‘data >= threshold’ or ‘<’ to evaluate ‘data < threshold’. When using fuzzy thresholds, there is no difference between < and <= or > and >=. Valid choices: > >= < <= gt ge lt le.
each_threshold_func (Union[Callable, List[Callable]]) – Callable or sequence of callables to apply after thresholding. Eg vicinity processing or collapse over ensemble realizations.

Raises

ValueError – If using a fuzzy factor with a threshold of 0.0.
ValueError – If the fuzzy_factor is not strictly between 0 and 1.
ValueError – If both fuzzy_factor and fuzzy_bounds are set.

_abc_impl = <_abc_data object>

_add_threshold_coord(cube, threshold)[source]

Add a scalar threshold-type coordinate with correct name and units to a 2D slice containing thresholded data.

The ‘threshold’ coordinate will be float64 to avoid rounding errors during possible unit conversion.

Parameters

cube (Cube) – Cube containing thresholded data (1s and 0s)
threshold (float) – Value at which the data has been thresholded

Return type

None

_check_fuzzy_bounds()[source]

If fuzzy bounds have been set from the command line, check they are consistent with the required thresholds

Return type: None

_decode_comparison_operator_string()[source]

Sets self.comparison_operator based on self.comparison_operator_string. This is a dict containing the keys ‘function’ and ‘spp_string’. Raises errors if invalid options are found.

Raises: ValueError – If self.comparison_operator_string does not match a defined method.
Return type: None

_generate_fuzzy_bounds(fuzzy_factor_loc)[source]

Construct fuzzy bounds from a fuzzy factor. If the fuzzy factor is 1, the fuzzy bounds match the threshold values for basic thresholding.

Return type: List[Tuple[float, float]]

_update_metadata(cube)[source]

Rename the cube and add attributes to the threshold coordinate after merging

Parameters: cube (Cube) – Cube containing thresholded data
Return type: None

process(input_cube)[source]

Convert each point to a truth value based on provided threshold values. The truth value may or may not be fuzzy depending upon if fuzzy_bounds are supplied. If the plugin has a “threshold_units” member, this is used to convert both thresholds and fuzzy bounds into the units of the input cube.

Parameters

input_cube (Cube) – Cube to threshold. The code is dimension-agnostic.

Return type

Cube

Returns

Cube after a threshold has been applied. The data within this cube will contain values between 0 and 1 to indicate whether a given threshold has been exceeded or not.

The cube meta-data will contain: * Input_cube name prepended with probability_of_X_above(or below)_threshold (where X is the diagnostic under consideration) * Threshold dimension coordinate with same units as input_cube * Threshold attribute (“greater_than”, “greater_than_or_equal_to”, “less_than”, or less_than_or_equal_to” depending on the operator) * Cube units set to (1).

Raises

ValueError – if a np.nan value is detected within the input cube.

class LatitudeDependentThreshold(threshold_function, threshold_units=None, comparison_operator='>')[source]

Bases: BasicThreshold

Apply a latitude-dependent threshold truth criterion to a cube.

Calculates the threshold truth values based on the threshold function provided. A cube will be returned with a new threshold dimension auxillary coordinate on the latitude axis.

Can operate on multiple time sequences within a cube.

__init__(threshold_function, threshold_units=None, comparison_operator='>')[source]

Sets up latitude-dependent threshold class

Parameters

threshold_function (callable) – A function which takes a latitude value (in degrees) and returns the desired threshold.
threshold_units (Optional[str]) – Units of the threshold values. If not provided the units are assumed to be the same as those of the input cube.
comparison_operator (str) – Indicates the comparison_operator to use with the threshold. e.g. ‘ge’ or ‘>=’ to evaluate ‘data >= threshold’ or ‘<’ to evaluate ‘data < threshold’. When using fuzzy thresholds, there is no difference between < and <= or > and >=. Valid choices: > >= < <= gt ge lt le.

_abc_impl = <_abc_data object>

_add_latitude_threshold_coord(cube, threshold)[source]

Add a 1D threshold-type coordinate with correct name and units to a 2D slice containing thresholded data. Assumes latitude coordinate is always the penultimate one (which standardise will have enforced)

Parameters

cube (Cube) – Cube containing thresholded data (1s and 0s)
threshold (ndarray) – Values at which the data has been thresholded (matches cube’s y-axis)

Return type

None

process(input_cube)[source]

Convert each point to a truth value based on provided threshold function. If the plugin has a “threshold_units” member, this is used to convert a copy of the input_cube into the units specified.

Parameters

input_cube (Cube) – Cube to threshold. Must have a latitude coordinate.

Return type

Cube

Returns

Cube after a threshold has been applied. The data within this cube will contain values between 0 and 1 to indicate whether a given threshold has been exceeded or not.

The cube meta-data will contain: * Input_cube name prepended with probability_of_X_above(or below)_threshold (where X is the diagnostic under consideration) * Threshold dimension coordinate with same units as input_cube * Threshold attribute (“greater_than”, “greater_than_or_equal_to”, “less_than”, or less_than_or_equal_to” depending on the operator) * Cube units set to (1).

Raises

ValueError – if a np.nan value is detected within the input cube.