improver.threshold module

Module containing thresholding classes.

class improver.threshold.BasicThreshold(thresholds, fuzzy_factor=None, fuzzy_bounds=None, threshold_units=None, comparison_operator='>')[source]

Bases: improver.BasePlugin

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='>')[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
------------|-------------
    4.5     |   0
    5.0     |   0.167
    5.5     |   0.333
    6.0     |   0.5
    6.5     |   0.667
    7.0     |   0.833
    7.5     |   1.0
Parameters

  • thresholds (list of float or float) – The threshold points for ‘significant’ datapoints.

  • fuzzy_factor (float) – Specifies lower bound for fuzzy membership value when multiplied by each threshold. Upper bound is equivalent linear distance above threshold. If None, no fuzzy_factor is applied.

  • fuzzy_bounds (list of tuple) – Lower and upper bounds for fuzziness. List should be of same length as thresholds. Each entry in list should be a tuple of two floats representing the lower and upper bounds respectively. If None, no fuzzy_bounds are applied.

  • threshold_units (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.

Raises

  • ValueError – If a threshold of 0.0 is requested when using a fuzzy factor.

  • ValueError – If the fuzzy_factor is not greater than 0 and less than 1.

  • ValueError – If both fuzzy_factor and fuzzy_bounds are set as this is ambiguous.

_abc_cache = <_weakrefset.WeakSet object>
_abc_negative_cache = <_weakrefset.WeakSet object>
_abc_negative_cache_version = 213
_abc_registry = <_weakrefset.WeakSet object>
_add_threshold_coord(cube, threshold)[source]

Add a scalar threshold-type coordinate to a cube containing thresholded data and promote the new coordinate to be the leading dimension of the cube.

Parameters

  • cube (iris.cube.Cube) – Cube containing thresholded data (1s and 0s)

  • threshold (float) – Value at which the data has been thresholded

Returns

With new “threshold” axis

Return type

iris.cube.Cube

_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.

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 (iris.cube.Cube) – Cube to threshold. The code is dimension-agnostic.

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 (above or below threshold) * Cube units set to (1).

Return type

iris.cube.Cube

Raises

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