Threshold#

Functions

build_threshold([query, operator, value, ...])

Factory for thresholds.

Classes

Threshold()

Abstract super class for all thresholds.

BasicThreshold(operator, value[, unit, ...])

Pint ready simple threshold (e.g. "> 300 K").

PercentileThreshold(operator, value[, unit, ...])

Percentile based threshold (e.g. "<= 10 doy_per").

BoundedThreshold(thresholds, logical_link, ...)

Threshold that binds two other thresholds (e.g. "> 95 doy_per AND >= 30 deg_C").
class icclim.generic_indices.threshold.BasicThreshold(operator: Operator | str, value: ThresholdValueType, unit: str | None = None, initial_query: str | None = None, threshold_min_value: pint.Quantity | None = None, threshold_var_name: str | None = None, **kwargs)[source]#

Pint ready simple threshold (e.g. “> 300 K”).

When built, value is always turned into a xarray.DataArray. The unit property as a setter that will attempt a unit conversion using units found in xclim’s pint registry.

The actual unit can be overridden by modify value.attrs["units"] directly.

compute(comparison_data: xr.DataArray, override_op: Callable[[DataArray, DataArray], DataArray] | None = None, **kwargs) → DataArray[source]#

Compute the exceedance of comparison_data over/below self threshold depending on self operator. The operator can be overridden by override_op. This is needed when self.operator is REACH.

Parameters:

  • comparison_data (xr.DataArray) – Data that must be compared to self threshold

  • override_op (Callable[[DataArray, DataArray], DataArray] | None) – Operator to override self.operator compute function. Optional.

  • kwargs – Keyword arguments passed to the concrete compute implementations This makes the compute interface contract not always reliable. So we assume to not really respected LSP here.

format_metadata(jinja_scope: dict[str, Any], jinja_env: Environment, **kwargs) → ThresholdMetadata[source]#

Get a dictionary of standardized threshold metadata.

class icclim.generic_indices.threshold.BoundedThreshold(thresholds: Sequence[Threshold | str | ThresholdBuilderInput], logical_link: LogicalLink, initial_query: str | None, **kwargs)[source]#

Threshold that binds two other thresholds (e.g. “> 95 doy_per AND >= 30 deg_C”).

The logical link must be either “and” or “or”.

compute(comparison_data: xr.DataArray, override_op: Callable[[DataArray, DataArray], DataArray] | None = None, **kwargs) → DataArray[source]#

Compute the exceedance of comparison_data over/below self threshold depending on self operator. The operator can be overridden by override_op. This is needed when self.operator is REACH.

Parameters:

  • comparison_data (xr.DataArray) – Data that must be compared to self threshold

  • override_op (Callable[[DataArray, DataArray], DataArray] | None) – Operator to override self.operator compute function. Optional.

  • kwargs – Keyword arguments passed to the concrete compute implementations This makes the compute interface contract not always reliable. So we assume to not really respected LSP here.

format_metadata(*, jinja_scope: dict[str, Any], jinja_env: Environment, **kwargs) → ThresholdMetadata[source]#

Get a dictionary of standardized threshold metadata.

class icclim.generic_indices.threshold.PercentileThreshold(operator: str | Operator, value: DataArray | float | int | Sequence[float], unit: str | None = None, doy_window_width: int = 5, only_leap_years: bool = False, interpolation: QuantileInterpolation | str = QuantileInterpolation(name='median_unbiased', alpha=0.3333333333333333, beta=0.3333333333333333), reference_period: Sequence[datetime | str] | None = None, threshold_min_value: pint.Quantity | None = None, initial_query: str | None = None, threshold_var_name: str | None = None, **kwargs)[source]#

Percentile based threshold (e.g. “<= 10 doy_per”).

The percentiles to be computed are expected to be either:

  • “doy percentiles” (unit: “doy_per”). They are usually used for temperatures indices such as the ECAD tx90p. These percentiles are computed per day of year (doy) and by aggregating values on the time axis ranged by reference_period, using the doy_window_width parameter to control the time axis window of aggregation. The resulting value is a DataArray with a “dayofyear” dimension ranging from 0 to 365 with one value per day of the year.

  • “period percentiles” (unit: “period_per”). They are usually used for liquide precipitation indices such as the ECAD r75p or even r75ptot. These percentiles are computed per grid cell on the period ranged by reference_period. The resulting value is a DataArray with per grid cell values and no time axis.

is_ready becomes True when prepare method has been called, the actual percentiles are then computed and accessible in value property. Once is_ready is True, unit property can be set and will attempt a pint unit conversion similar to what is done on BasicThreshold. Before that, setting unit has no effect.

compute(comparison_data: xr.DataArray, override_op: Callable[[DataArray, DataArray], DataArray] | None = None, **kwargs) → DataArray[source]#

Compute the exceedance of comparison_data over/below self threshold depending on self operator. The operator can be overridden by override_op. This is needed when self.operator is REACH.

Parameters:

  • comparison_data (xr.DataArray) – Data that must be compared to self threshold

  • override_op (Callable[[DataArray, DataArray], DataArray] | None) – Operator to override self.operator compute function. Optional.

  • kwargs – Keyword arguments passed to the concrete compute implementations This makes the compute interface contract not always reliable. So we assume to not really respected LSP here.

format_metadata(*, jinja_scope: dict[str, Any], jinja_env: Environment, src_freq: Frequency, must_run_bootstrap: bool = False, **kwargs) → ThresholdMetadata[source]#

Get a dictionary of standardized threshold metadata.

class icclim.generic_indices.threshold.Threshold[source]#

Abstract super class for all thresholds.

abstract compute(comparison_data: xr.DataArray, override_op: Callable[[DataArray, DataArray], DataArray] | None = None, **kwargs) → DataArray[source]#

Compute the exceedance of comparison_data over/below self threshold depending on self operator. The operator can be overridden by override_op. This is needed when self.operator is REACH.

Parameters:

  • comparison_data (xr.DataArray) – Data that must be compared to self threshold

  • override_op (Callable[[DataArray, DataArray], DataArray] | None) – Operator to override self.operator compute function. Optional.

  • kwargs – Keyword arguments passed to the concrete compute implementations This makes the compute interface contract not always reliable. So we assume to not really respected LSP here.

abstract format_metadata(*, jinja_scope: dict[str, Any], jinja_env: Environment, **kwargs) → ThresholdMetadata[source]#

Get a dictionary of standardized threshold metadata.

class icclim.generic_indices.threshold.ThresholdBuilderInput[source]#

Data transfert object mapping all possible configuration to build any threshold.

icclim.generic_indices.threshold.build_threshold(query: str | None = None, *, operator: Operator | str = None, value: ThresholdValueType = None, unit: str | None = None, threshold_min_value: str | float | None | pint.Quantity = None, thresholds: Sequence[Threshold | str, Threshold | str] | None = None, logical_link: str | LogicalLink | None = None, **kwargs) → BoundedThreshold | PercentileThreshold | BasicThreshold[source]#

Factory for thresholds.

Parameters:

  • query (str | None = None) – string query describing a threshold. It must include: an operator, a threshold value and optionally a unit such as “> 10 degC”. It acts as a shorthand for operator, value and unit parameters for simple threshold. Don’t use query when value is a DataArray, a Dataset or a path to a netcdf/zarr storage, instead use operator, value and unit. query supersede operator, value and unit parameters.

  • operator (Operator | str = None) – keyword argument only. The operator either as an instance of Operator or as a compatible string. See OperatorRegistry for the list of all operators. When query is None and operator is None, the default Operator.REACH is used.

  • value (str | float | int | Dataset | DataArray | Sequence[float | int | str] | None) – keyword argument only. The threshold value(s), default to None. It can be: * a simple scalar threshold * a percentile that will be computed per-grid cell (in combinaison with unit) * per-grid cell thresholds defined by a DataArray, a Dataset or a string path to a netcdf/zarr. * a sequence of scalars, the indicator will then be computed for each value and a specific dimension will be created (also work with percentiles).

  • unit (str | None = None) – Keyword argument only. The threshold unit. When unit is None, if value is a dataset and a “units” can be read from its attrs, this unit will be used. If value is a scalar or a sequence of scalar, the exceedance will be computed by assuming threshold has the same unit as the studied value is it compared to. When unit is a string it must be a valid unit of our shared pint registry with xclim or a special percentile unit: * “doy_per” for day of year percentiles (in ECAD, used for temperature indices such as TX90p) * “period_per” for per period percentiles (in ECAD, used for rain indices such as R75p)

  • threshold_min_value (str | float | pint.Quantity) – A minimum value used to pre-filter computed threshold values. This is particularly useful to compute a percentile threshold for rain where dry days are usually ignored. In that case threshold_min_value would be set to “1 mm/day”. If threshold_min_value is a number, unit is used to quantify threshold_min_value.

  • kwargs – Additional arguments to build a PercentileThreshold. See PercentileThreshold constructor for the complete list of possible arguments.

Examples

# -- Scalar threshold
scalar_t = build_threshold(">= 30 degC")
assert isinstance(scalar_t, BasicThreshold)

# -- Daily percentile threshold
doy_t = build_threshold(">= 30 doy_per")
assert isinstance(doy_t, PercentileThreshold)

# -- Per grid-cell threshold
grided_t = build_threshold(
    operator=">=", value="path/to/tasmax_thresholds.nc", unit="K"
)
assert isinstance(grided_t, BasicThreshold)

# -- Daily percentile threshold, from a file
tasmax = xarray.open_dataset("path/to/tasmax_thresholds.nc").tasmax
doys = xclim.core.calendar.percentile_doy(tasmax)
doy_file_t = build_threshold(operator=">=", value=doys)
assert isinstance(doy_file_t, PercentileThreshold)

# -- Bounded threshold
bounded_t = build_threshold(">= -20 degree AND <= 20 degree ")
# equivalent to:
x = build_threshold(">= -20 degree")
y = build_threshold("<= 20 degree")
bounded_t2 = x & y
assert bounded_t == bounded_t2
# equivalent to:
bounded_t3 = build_threshold(thresholds=[x, y], logical_link="AND")
assert bounded_t == bounded_t3
assert isinstance(bounded_t, BoundedThreshold)