`icclim.threshold.factory`#

Factory to build a Threshold from a query or from its components.

Module Contents#

Build a Threshold.

This function is a factory for Threshold instances. It can build a BasicThreshold, a PercentileThreshold or a BoundedThreshold. See Generic indices recipes for how to combine thresholds with generic indices.

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.
offset (float | None) – Optional. An offset applied to the threshold. This is particularly useful when the threshold is an existing dataset (netcdf file or zarr store) and the data should be compared to this dataset + an offset (e.g. to compute days when T > 5 degC above normal)
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, with offset
grided_t = build_threshold(
    operator=">=", value="path/to/tasmax_thresholds.nc", unit="K", offset=5
)
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)

icclim.threshold.factory#

Module Contents#

`icclim.threshold.factory`#