icclim._core.generic.functions

Implementations of the generic indices computation methods.

These functions are not meant to be called directly, they are used by the GenericIndicatorRegistry class to create the generic indices. Each function is a reducer that takes a list of ClimateVariable instances and returns a DataArray instance. The ClimateVariable instances are used to extract the data and the thresholds needed to compute the generic index. The DataArray instance is the result of the computation of the generic index.

Note

You can call the respective generic index from icclim module, for example: icclim.count_occurrences(…).

Module Contents

icclim._core.generic.functions.count_occurrences(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, logical_link: icclim._core.model.logical_link.LogicalLink, date_event: bool, to_percent: bool, **kwargs) → xarray.DataArray

Count the occurrences of exceedances of the threshold(s).

Parameters:

• climate_vars (list[ClimateVariable]) – The list of climate variables containing the data and the threshold(s).

• resample_freq (Frequency) – The time frequency of the output.

• logical_link (LogicalLink) – The logical link to apply to the exceedances if multiple thresholds are provided.

• date_event (bool) – Whether to return the date of the event.

• to_percent (bool) – Whether to return the result in percent.

• **kwargs (dict) – Ignored keyword arguments (for compatibility).

Returns:

The count of occurrences of exceedances.

Return type:

DataArray

icclim._core.generic.functions.max_consecutive_occurrence(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, logical_link: icclim._core.model.logical_link.LogicalLink, date_event: bool, source_freq_delta: datetime.timedelta, **kwargs) → xarray.DataArray

Calculate the maximum number of consecutive occurrences of exceedances for a given set of climate variables.

Parameters:

• climate_vars (list[ClimateVariable]) – The list of climate variables containing the data and the threshold(s).

• resample_freq (Frequency) – The time frequency of the output.

• logical_link (LogicalLink) – The logical link to apply when merging the exceedances.

• date_event (bool) – Whether to include the dates of the exceedances in the result.

• source_freq_delta (timedelta) – The time difference between consecutive data points in the source data.

• **kwargs (dict) – Ignored keyword arguments (for compatibility).

Returns:

The maximum number of consecutive occurrences of exceedances.

Return type:

DataArray

icclim._core.generic.functions.sum_of_spell_lengths(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, logical_link: icclim._core.model.logical_link.LogicalLink, min_spell_length: int, **kwargs) → xarray.DataArray

Calculate the sum of the lengths of all spells in the data.

This function calculates the sum of the lengths of all spells in the data, where a spell is defined as a consecutive occurrence of exceedances.

Parameters:

• climate_vars (list[ClimateVariable]) – The list of climate variables containing the data and the threshold(s).

• resample_freq (Frequency) – The time frequency of the output.

• logical_link (LogicalLink) – The logical link to apply when merging the exceedances.

• min_spell_length (int) – The minimum length of a spell to consider.

• **kwargs (dict) – Ignored keyword arguments (for compatibility).

Returns:

The sum of the lengths of all spells in the data.

Return type:

DataArray

icclim._core.generic.functions.excess(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, **kwargs) → xarray.DataArray

Compute the excess of a climate variable above a threshold using the ‘reach’ operator.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables. Only the first variable is used.

• resample_freq (Frequency) – The time frequency of the output.

• **kwargs (dict) – Ignored keyword arguments (for compatibility).

Returns:

DataArray containing the computed excess values.

Return type:

DataArray

Raises:

InvalidIcclimArgumentError – If the threshold operator is not ‘reach’.

Notes

The excess is computed by subtracting the threshold from the climate variable data. Only the values above the threshold are considered, and negative values are set to zero. The resulting excess values are then summed over the specified resample frequency.

icclim._core.generic.functions.deficit(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, **kwargs) → xarray.DataArray

Compute the deficit of a climate variable below a threshold using the ‘reach’ operator.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables. Only the first variable is used.

• resample_freq (Frequency) – The time frequency of the output.

• **kwargs (dict) – Ignored keyword arguments (for compatibility).

Returns:

DataArray containing the computed deficit values.

Return type:

DataArray

Notes

The deficit is computed by subtracting the climate variable data from the threshold. Only the values below the threshold are considered, and negative values are set to zero. The resulting deficit values are then summed over the specified resample frequency.

icclim._core.generic.functions.fraction_of_total(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, to_percent: bool, **kwargs) → xarray.DataArray

Calculate the fraction of total for a given set of climate variables.

Parameters:

• climate_vars (list[ClimateVariable]) – The list of climate variables containing the data and the threshold(s). Only one variable is expected in the list.

• resample_freq (Frequency) – The resampling frequency.

• to_percent (bool) – Flag indicating whether to convert the result to percentage.

• **kwargs (dict) – Ignored keyword arguments (for compatibility).

Returns:

The fraction of total as a DataArray.

Return type:

DataArray

Notes

This function calculates the fraction of total for a given set of climate variables. The fraction of total is calculated by dividing the sum of values exceeding a threshold by the total sum of values.

If the to_percent flag is set to True, the result will be multiplied by 100 and the units will be set to “%”. Otherwise, the units will be set to the value of PART_OF_A_WHOLE_UNIT, which is 1.

icclim._core.generic.functions.maximum(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, date_event: bool, **kwargs) → xarray.DataArray

Calculate the maximum value of the given climate variables.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables to calculate the maximum value for.

• resample_freq (Frequency) – The frequency at which to resample the data.

• date_event (bool) – Flag indicating whether the output should include the date of the events.

• **kwargs (dict) – Ignored keyword arguments (for compatibility).

Returns:

The maximum value of the climate variables.

Return type:

DataArray

icclim._core.generic.functions.minimum(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, date_event: bool, **kwargs) → xarray.DataArray

Calculate the minimum value of the given climate variables.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables to calculate the minimum value for.

• resample_freq (Frequency) – The frequency at which to resample the data.

• date_event (bool) – Flag indicating whether the output should include the date of the events.

• **kwargs (dict) – Ignored keyword arguments (for compatibility).

Returns:

The minimum value of the climate variables.

Return type:

DataArray

icclim._core.generic.functions.average(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, **kwargs) → xarray.DataArray

Compute the average of the given climate variables.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables to compute the average for.

• resample_freq (Frequency) – The frequency at which to resample the data.

• **kwargs – Ignored keyword arguments (for compatibility).

Returns:

The computed average as a DataArray.

Return type:

DataArray

icclim._core.generic.functions.generic_sum(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, **kwargs) → xarray.DataArray

Compute the sum of the given climate variables.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables to compute the sum for.

• resample_freq (Frequency) – The frequency at which to resample the data.

• **kwargs – Ignored keyword arguments (for compatibility).

Returns:

The computed sum as a DataArray.

Return type:

DataArray

icclim._core.generic.functions.standard_deviation(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, **kwargs) → xarray.DataArray

Compute the standard deviation of the given climate variables.

This function calculates the standard deviation of the provided climate variables. The standard deviation is a measure of the amount of variation or dispersion in the data. It quantifies the amount of variation or spread in the values of the climate variables.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables to compute the standard deviation for.

• resample_freq (Frequency) – The frequency at which to resample the data.

• **kwargs – Ignored keyword arguments (for compatibility).

Returns:

The computed standard deviation as a DataArray.

Return type:

DataArray

icclim._core.generic.functions.max_of_rolling_sum(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, rolling_window_width: int, date_event: bool, source_freq_delta: datetime.timedelta, **kwargs) → xarray.DataArray

Compute the maximum value of the rolling sum of the given climate variables.

The rolling sum is the sum of values over a specified rolling window width. The maximum value is the highest value obtained from the rolling sum.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables to compute the maximum value of the rolling sum for.

• resample_freq (Frequency) – The frequency at which to resample the data.

• rolling_window_width (int) – The width of the rolling window, i.e., the number of values to include in each rolling sum.

• date_event (bool) – A flag indicating whether the date of the events should be included in the output.

• source_freq_delta (timedelta) – The time difference between consecutive data points in the source data. For daily data this is 1 day, for monthly data this is 1 month, etc.

• **kwargs – Ignored keyword arguments (for compatibility).

Returns:

The computed maximum value of the rolling sum as a DataArray.

Return type:

DataArray

icclim._core.generic.functions.min_of_rolling_sum(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, rolling_window_width: int, date_event: bool, source_freq_delta: datetime.timedelta, **kwargs) → xarray.DataArray

Compute the minimum value of the rolling sum of the given climate variables.

The rolling sum is the sum of values over a specified rolling window width. The minimum value is the lowest value obtained from the rolling sum.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables to compute the minimum value of the rolling sum for.

• resample_freq (Frequency) – The frequency at which to resample the data.

• rolling_window_width (int) – The width of the rolling window, i.e., the number of values to include in each rolling sum.

• date_event (bool) – A flag indicating whether the date of the events should be included in the output.

• source_freq_delta (timedelta) – The time difference between consecutive data points in the source data. For daily data this is 1 day, for monthly data this is 1 month, etc.

• **kwargs – Ignored keyword arguments (for compatibility).

Returns:

The computed minimum value of the rolling sum as a DataArray.

Return type:

DataArray

icclim._core.generic.functions.min_of_rolling_average(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, rolling_window_width: int, date_event: bool, source_freq_delta: datetime.timedelta, **kwargs) → xarray.DataArray

Compute the minimum value of the rolling average of the given climate variables.

The rolling average is the average of values over a specified rolling window width. The minimum value is the lowest value obtained from the rolling average.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables to compute the minimum value of the rolling average for.

• resample_freq (Frequency) – The frequency at which to resample the data.

• rolling_window_width (int) – The width of the rolling window, i.e., the number of values to include in each rolling average.

• date_event (bool) – A flag indicating whether the date of the events should be included in the output.

• source_freq_delta (timedelta) – The time difference between consecutive data points in the source data. For daily data this is 1 day, for monthly data this is 1 month, etc.

• **kwargs – Ignored keyword arguments (for compatibility).

Returns:

The computed minimum value of the rolling average as a DataArray.

Return type:

DataArray

icclim._core.generic.functions.max_of_rolling_average(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, rolling_window_width: int, date_event: bool, source_freq_delta: datetime.timedelta, **kwargs) → xarray.DataArray

Compute the minimum value of the rolling average of the given climate variables.

The rolling average is the average of values over a specified rolling window width. The minimum value is the lowest value obtained from the rolling average.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables to compute the minimum value of the rolling average for.

• resample_freq (Frequency) – The frequency at which to resample the data.

• rolling_window_width (int) – The width of the rolling window, i.e., the number of values to include in each rolling average.

• date_event (bool) – A flag indicating whether the date of the events should be included in the output.

• source_freq_delta (timedelta) – The time difference between consecutive data points in the source data. For daily data this is 1 day, for monthly data this is 1 month, etc.

• **kwargs – Ignored keyword arguments (for compatibility).

Returns:

The computed minimum value of the rolling average as a DataArray.

Return type:

DataArray

icclim._core.generic.functions.mean_of_difference(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, **kwargs) → xarray.DataArray

Calculate the mean of the difference between two climate variables.

This function calculates the mean of the difference between two climate variables for each time step, and then resamples the resulting data based on the specified frequency. The resulting data array will have the same units as the study variable.

Parameters:

• climate_vars (list[ClimateVariable]) – The two climate variables necessary to compute the indicator.

• resample_freq (Frequency) – Resampling frequency of the output.

• **kwargs (dict) – Ignored keyword arguments (for compatibility).

Returns:

The mean of the difference as a xarray.DataArray.

Return type:

DataArray

Notes

This is a generification of ECAD’s DTR climate index.

icclim._core.generic.functions.difference_of_extremes(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, **kwargs) → xarray.DataArray

Calculate the difference of extremes between two climate variables.

Parameters:

• climate_vars (list[ClimateVariable]) – A list of climate variables.

• resample_freq (Frequency) – The frequency at which to resample the data.

• **kwargs – Ignored keyword arguments (for compatibility).

Returns:

The difference of extremes between the two climate variables.

Return type:

DataArray

Notes

This function calculates the difference of extremes between two climate variables. It first resamples the study variable to the specified frequency and take the maximum per resampled chunk. Then it resamples the reference variable to the same frequency and take the minimum per resampled chunk. Finally, for each chunk, it calculates the differences of theses maximum and minimum values. This is a generification of ECAD’s ETR climate index.

icclim._core.generic.functions.mean_of_absolute_one_time_step_difference(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, **kwargs) → xarray.DataArray

Mean of the absolute one-time-step difference between two climate variables.

This function calculates the mean of the absolute difference between two climate variables for each time step, and then resamples the resulting data based on the specified frequency. The resulting data array will have the same units as the study variable.

Parameters:

• climate_vars (list[ClimateVariable]) – The two climate variables necessary to compute the indicator.

• resample_freq (Frequency) – Resampling frequency of the output.

• **kwargs (dict) – Ignored keyword arguments (for compatibility).

Returns:

The mean of the absolute one-time-step difference as a xarray.DataArray.

Return type:

DataArray

Notes

This is a generification of ECAD’s vDTR climate index.

icclim._core.generic.functions.difference_of_means(climate_vars: list[icclim._core.climate_variable.ClimateVariable], to_percent: bool, resample_freq: icclim._core.frequency.Frequency, sampling_method: str, is_compared_to_reference: bool, **kwargs) → xarray.DataArray

Calculate the difference of means between two climate variables.

Parameters:

• climate_vars (list[ClimateVariable]) – A studied climate variable and a reference climate variable.

• to_percent (bool) – If True, the result will be converted to percentage.

• resample_freq (Frequency) – Resampling frequency of the output.

• sampling_method (str) – The method used for resampling. It can be either ‘group_by’, ‘resample’, or ‘group_by_ref_and_resample_study’. ‘group_by’ will group the data by the specified frequency, for example every data of every January together. ‘resample’ will resample the data to the specified frequency, for example every days of each month independently together. ‘group_by_ref_and_resample_study’ will group the reference data by the specified frequency and resample the study data to the same frequency. This last method allows for example to compare each January, independently, of the study period to every January of the reference period. This is typically used to compare the each month of the studied period to a normal (the reference) of many aggregated years.

• is_compared_to_reference (bool) – If True, check if the sampling method is ‘resample’ and raise an error if it is. It does not make sense to resample the reference variable if it is already a subsample of the studied variable.

• **kwargs – Ignored keyword arguments (for compatibility).

Returns:

The difference of means between the two climate variables.

Return type:

DataArray

Notes

This is a generification of the anomaly climate index.

icclim._core.generic.functions.percentile(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, **kwargs) → xarray.DataArray

Calculate the percentile of the given climate variable.

Parameters:

• climate_vars (list[ClimateVariable]) – A single climate variable within a list.

• resample_freq (Frequency) – Resampling frequency of the output.

• **kwargs – Ignored keyword arguments (for compatibility).

Returns:

The calculated percentile as a DataArray.

Return type:

DataArray

Notes

This function calculates the percentile of the given climate variables by resampling the data based on the provided frequency and then calculating the corresponding quantile using the specified interpolation method.

The resulting DataArray contains the percentiles as the ‘percentiles’ coordinate variable.

icclim._core.generic.functions.get_couple_of_var(climate_vars: list[icclim._core.climate_variable.ClimateVariable], indicator: str) → tuple[xarray.DataArray, xarray.DataArray]

Get exactly two climate variables to compute a climate indicator.

Parameters:

• climate_vars (list[ClimateVariable]) – A list of climate variables.

• indicator (str) – The name of the indicator to be computed.

Returns:

A tuple containing two DataArray objects representing the study variable and the reference variable.

Return type:

tuple[DataArray, DataArray]

Raises:

InvalidIcclimArgumentError – If the number of climate variables is not equal to 2. If any of the two variable has a threshold.

Notes

This function is used to extract a couple of climate variables needed for computing an indicator. The function checks the number of climate variables and raises an error if it is not equal to 2 or if thresholds are present.

icclim._core.generic.functions._run_simple_reducer(climate_vars: list[icclim._core.climate_variable.ClimateVariable], resample_freq: icclim._core.frequency.Frequency, reducer_op: Callable[Ellipsis, xarray.DataArray], date_event: bool, must_convert_rate: bool = False) → xarray.DataArray

Apply a simple reducer operation on climate variables.

Parameters:

• climate_vars (list[ClimateVariable]) – List of climate variables to be processed.

• resample_freq (Frequency) – Frequency at which the data should be resampled.

• reducer_op (Callable[..., DataArray]) – Reducer operation to be applied on the data.

• date_event (bool) – Flag indicating whether the date when the event occurred should be added as a coordinate variable. Only works for max and min reducers. Defaults to False.

• must_convert_rate (bool, optional) – Flag indicating whether the data should be converted from rate to amount. Defaults to False.

Returns:

Result of the reducer operation applied on the climate variables.

Return type:

DataArray

icclim._core.generic.functions.get_single_var(climate_vars: list[icclim._core.climate_variable.ClimateVariable]) → tuple[xarray.DataArray, icclim._core.model.threshold.Threshold | None]

Get the single variable and its threshold (if available).

Parameters:

climate_vars (list[ClimateVariable]) – A list of ClimateVariable objects.

Returns:

A tuple containing the single variable’s data array and its threshold (if available).

Return type:

tuple[DataArray, Threshold | None]