tools.indicators

tools.indicators.aridity(df, hist_starty=1986, hist_endy=2015)

Calculates aridity indexes from precipitation, and potential and actual evaporation respectively. Aridity is defined as the mean annual ratio of potential/actual evapotranspiration and precipitation. The indexes are defined as the relative change of a 30-year period compared to a given historical period. Uses hydrological years (Oct–Sep). Inspired by climateinformation.org (https://doi.org/10.5194/egusphere-egu23-16216).

Parameters:

• df (pandas.DataFrame) – Input DataFrame containing columns ‘evap_off_glaciers’, ‘actual_evaporation’, and ‘prec_off_glaciers’.

• hist_starty (int, optional) – Start year of the historical period in YYYY format. Default is 1986.

• hist_endy (int, optional) – End year of the historical period in YYYY format. Default is 2015.

Returns:

DataFrame containing the relative change in aridity over time.

Columns: - ‘actual_aridity’: Relative change in actual aridity. - ‘potential_aridity’: Relative change in potential aridity.

Return type:

pandas.DataFrame

tools.indicators.calculate_indicators(dic, **kwargs)

Calculate climate change indicators for all scenarios and models. :param dic: Dictionary containing MATILDA outputs for all scenarios and models. :type dic: dict :param **kwargs: Optional keyword arguments to be passed to the cc_indicators() function. :type **kwargs: optional

Returns:

Dictionary with the same structure as the input but containing climate change indicators in annual resolution.

Return type:

dict

tools.indicators.cc_indicators(df, **kwargs)

Apply a list of climate change indicator functions to the output DataFrame of MATILDA and concatenate the output columns into a single DataFrame.

Parameters:

• df (pandas.DataFrame) – Input DataFrame.

• **kwargs (optional) – Optional arguments to be passed to the functions in the list. Possible arguments are ‘smoothing_window_peakdoy’, ‘smoothing_window_meltseas’, ‘min_weeks’, and ‘dry_spell_length’.

Returns:

DataFrame containing the output columns of all functions applied to the input DataFrame.

Return type:

pandas.DataFrame

Notes

The list of functions to apply is hard-coded into the function and cannot be modified from outside. The optional arguments are passed to the respective functions only if they are relevant. If no optional arguments are passed, the function is applied to the input DataFrame with default arguments.

tools.indicators.custom_df_indicators(dic, scenario, var)

Takes a dictionary of climate change indicators and returns a combined dataframe of a specific variable for a given scenario. :param dic: Dictionary containing the outputs of calculate_indicators() for different scenarios and models. :type dic: dict :param scenario: Name of the selected scenario. :type scenario: str :param var: Name of the variable to extract from the DataFrame. :type var: str

Returns:

A DataFrame containing the selected variable from different models within the specified scenario.

Return type:

pandas.DataFrame

Raises:

ValueError – If the provided variable is not one of the function outputs.

tools.indicators.drought_indicators(df, freq='ME', dist='gamma')

Calculate the climatic water balance, SPI (Standardized Precipitation Index), and SPEI (Standardized Precipitation Evapotranspiration Index) for 1, 3, 6, 12, and 24 months.

Parameters:

• df (pandas.DataFrame) – Input DataFrame containing columns ‘prec_off_glaciers’ and ‘evap_off_glaciers’.

• freq (str, optional) – Resampling frequency for precipitation and evaporation data. Default is ‘M’ for monthly.

• dist (str, optional) – Distribution for SPI and SPEI calculation. Either Pearson-Type III (‘pearson’) or Gamma distribution (‘gamma’). Default is ‘gamma’.

Returns:

DataFrame containing the calculated indicators: ‘clim_water_balance’, ‘spi’, and ‘spei’. Index is based on the resampled frequency of the input DataFrame.

Return type:

pandas.DataFrame

Raises:

ValueError – If ‘freq’ is not ‘D’ or ‘ME’. If ‘dist’ is not ‘pearson’ or ‘gamma’.

Notes

SPI (Standardized Precipitation Index) and SPEI (Standardized Precipitation Evapotranspiration Index) are drought indicators that are used to quantify drought severity and duration.

‘clim_water_balance’ is the difference between total precipitation and total evapotranspiration.

If ‘freq’ is ‘D’, the input data is transformed from Gregorian to a 366-day format for SPI and SPEI calculation, and then transformed back to Gregorian format for output.

The default distribution for SPI and SPEI calculation is Gamma.

The calibration period for SPI and SPEI calculation is from 1981 to 2020.

tools.indicators.dry_spells(df, dry_spell_length=5)

Compute the total length of dry spells in days per year. A dry spell is defined as a period for which the rolling mean of evaporation in a given window exceeds precipitation. Uses hydrological years (Oct - Sep).

Parameters:

• df (pandas.DataFrame) – Input DataFrame containing columns ‘evap_off_glaciers’ and ‘prec_off_glaciers’ with daily evaporation and precipitation data, respectively.

• dry_spell_length (int, optional) – Length of the rolling window in days. Default is 30.

Returns:

DataFrame containing the number of days for which the rolling mean of evaporation exceeds precipitation for each year in the input DataFrame.

Return type:

pandas.DataFrame

tools.indicators.get_qhf(data, global_median, measurements_per_day=1)

Variation of spotpy.hydrology.signatures.get_qhf() that allows definition of a global median to investigate long-term trends. Calculates the frequency of high flow events defined as \(Q > 9 \cdot Q_{50}\) cf. [CLBGS2000], [WESMCM2015]. The frequency is given as :math: \(yr^{-1}\) :param data: the timeseries :param measurements_per_day: the measurements_per_day of the timeseries :return: Q_{HF}, Q_{HD}

tools.indicators.get_qlf(data, global_mean, measurements_per_day=1)

Variation of spotpy.hydrology.signatures.get_qlf() that allows comparison of individual years with a global mean to investigate long-term trends. Calculates the frequency of low flow events defined as \(Q < 0.2 \cdot \overline{Q_{mean}}\) cf. [CLBGS2000], [WESMCM2015]. The frequency is given in \(yr^{-1}\) and for the whole timeseries :param data: the timeseries :param measurements_per_day: the measurements_per_day of the timeseries :return: Q_{LF}, Q_{LD}

tools.indicators.hydrological_signatures(df)

Calculate hydrological signatures for a given input dataframe.

Parameters:

df (pandas.DataFrame) – Input DataFrame containing a column ‘total_runoff’ and a DatetimeIndex.

Returns:

A DataFrame containing the calculated hydrological signatures for each year in the input dataframe. The columns of the output dataframe are as follows: - ‘q5’: the 5th percentile of total runoff for each year - ‘q50’: the 50th percentile of total runoff for each year - ‘q95’: the 95th percentile of total runoff for each year - ‘qlf_freq’: the frequency of low flow events (Q < 2 × Qmean_global) for each year, in yr⁻¹ - ‘qlf_dur’: the mean duration of low flow events (Q < 2 × Qmean_global) for each year, in days - ‘qhf_freq’: the frequency of high flow events (Q > 9 × Q50_global) for each year, in yr⁻¹ - ‘qhf_dur’: the mean duration of high flow events (Q > 9 × Q50_global) for each year, in days

Return type:

pandas.DataFrame

tools.indicators.melting_season(df, smoothing_window_meltseas=14, min_weeks=10)

Compute the start, end, and length of the melting season for each calendar year based on the daily the rolling mean of the temperature. :param df: A DataFrame of daily mean temperature data with a datetime index. :type df: pandas.DataFrame :param smoothing_window_meltseas: The size of the rolling window in days used to smooth the temperature data. Default is 14. :type smoothing_window_meltseas: int, optional :param min_weeks: The minimum number of weeks that the melting season must last for it to be considered valid. Default is 10. :type min_weeks: int, optional

Returns:

A DataFrame with the start, end, and length of the melting season for each calendar year, with a DatetimeIndex.

Return type:

pandas.DataFrame

tools.indicators.peak_doy(df, smoothing_window_peakdoy=7)

Compute the day of the calendar year with the peak value for each hydrological year.

Parameters:

• df (pandas.DataFrame) – A DataFrame of daily data with a datetime index.

• smoothing_window_peakdoy (int, optional) – The window size of the rolling mean used for smoothing the data. Default is 7.

Returns:

A DataFrame with the day of the year with the peak value for each hydrological year.

Return type:

pandas.DataFrame

tools.indicators.prec_minmax(df)

Compute the months of extreme precipitation for each year. :param df: A DataFrame of daily precipitation data with a datetime index and a ‘total_precipitation’ column. :type df: pandas.DataFrame

Returns:

A DataFrame with the months of extreme precipitation as a number for every calendar year.

Return type:

pandas.DataFrame

References

[WESMCM2015] (1,2)

Uncertainty in hydrological hydrology by I. K. Westerberg and H. K. McMillan, 2015 DOI: 10.5194/hess-19-3951-2015

[CLBGS2000] (1,2)

Flow variables for ecological studies in temperate streams: groupings based on covariance, B Clausen, BJF Biggs 2000 DOI:10.1016/S0022-1694(00)00306-1

Adapted from spotpy/hydrology/signatures.py.