improver.threshold module

Module containing thresholding classes.

class improver.threshold.BasicThreshold(thresholds, fuzzy_factor=None, fuzzy_bounds=None, threshold_units=None, below_thresh_ok=False)[source]

Bases: object

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, below_thresh_ok=False)[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 floats or float) – The threshold points for ‘significant’ datapoints.
Keyword Arguments:
 
  • 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 tuples) – 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 (string) – Units of the threshold values. If not provided the units are assumed to be the same as those of the input cube.
  • below_thresh_ok (boolean) – True to count points as significant if below the threshold, False to count points as significant if above the threshold.
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.
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:cube (iris.cube.Cube)
Raises:ValueError – if a np.nan value is detected within the input cube.