icclim._core.generic.threshold.percentile

Percentile based threshold module.

Module Contents

class icclim._core.generic.threshold.percentile.PercentileThreshold(operator: str | icclim._core.model.operator.Operator, value: xarray.DataArray | float | collections.abc.Sequence[float], unit: str | None = None, doy_window_width: int = DEFAULT_DOY_WINDOW, only_leap_years: bool = False, interpolation: icclim._core.model.quantile_interpolation.QuantileInterpolation | str = QuantileInterpolationRegistry.MEDIAN_UNBIASED, reference_period: collections.abc.Sequence[datetime.datetime | str] | None = None, threshold_min_value: pint.Quantity | None = None, initial_query: str | None = None, threshold_var_name: str | None = None, **kwargs)

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.

property unit: str | None

The unit of the threshold.

property value: icclim._core.input_parsing.PercentileDataArray

The computed percentile threshold.

Raises:

RuntimeError – If the threshold is not ready (prepare has not been called).

prepare(studied_data: xarray.DataArray) → None

Prepare the data for calculating percentiles.

Parameters:

studied_data (DataArray) – The input data to be prepared.

Raises:

NotImplementedError – If the percentile unit is unknown.

Return type:

None

format_metadata(*, jinja_scope: dict[str, Any], jinja_env: jinja2.Environment, src_freq: icclim._core.frequency.Frequency, must_run_bootstrap: bool = False, **kwargs) → icclim._core.generic.threshold.threshold_templates.ThresholdMetadata

Generate the metadata for the threshold.

These metadata are used to fill the generic template.

Parameters:

• jinja_scope (dict) – The jinja scope, it contains the variables to be used in the jinja template.

• jinja_env (jinja2.Environment) – The jinja environment, it contains the jinja rendering engine.

• src_freq (Frequency) – The frequency of the source data.

• must_run_bootstrap (bool, optional) – Whether to run bootstrap, by default False.

Returns:

The metadata for the threshold.

Return type:

ThresholdMetadata

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

Compute the percentile threshold.

Parameters:

• comparison_data (xr.DataArray) – The data array to compare with the threshold.

• override_op (Callable[[DataArray, DataArray], DataArray] | None, optional) – An optional override operator to use instead of the default operator.

• **kwargs – Additional keyword arguments. The freq parameter is used to specify the frequency of the data. The bootstrap parameter is used to specify whether to run bootstrap.

Returns:

The computed percentile threshold.

Return type:

DataArray

Raises:

RuntimeError – If the PercentileThreshold is not ready. You must first call .prepare with a studied_data parameter in order to prepare the threshold for computation.