spei.si module

class spei.si.SI(series: Series, dist: Any | rv_continuous, timescale: int = 0, fit_freq: str | None = None, fit_window: int = 0, prob_zero: bool = False, normal_scores_transform: bool = False, agg_func: Literal['sum', 'mean'] = 'sum')

Bases: object

Standardized Index Class.

Parameters:

  • series (Series) – The input time series data.

  • dist (ContinuousDist) – The SciPy continuous distribution associated with the data.

  • timescale (int, optional, default=0) – Size of the moving window over which the series is summed. If zero, no summation is performed over the time series. If the time series frequency is daily, then one would provide timescale=30 for SI1, timescale=90 for SI3, timescale=180 for SI6 etc.

  • fit_freq (str, optional, default=None) – Frequency for fitting the distribution. Default is None in which case the frequency of the series is inferred. If this fails a monthly frequency is used.

  • fit_window (int, optional, default=0) – Window size for fitting data in fit_freq frequency’s unit. Default is zero in which case only data within the fit_freq is considered. If larger than zero data data within the window is used to fit the distribution for the series. fit_window must be a odd number larger than 3 when used.

  • prob_zero (bool, default=False) – Flag indicating whether the probability of zero values in the series is calculated by the occurence.

  • normal_scores_transform (bool, default=False) – Flag to use the normal scores transformation for calculating the cumulative density function.

  • agg_func (Literal['sum', 'mean'], default='sum') – String of the function to use for aggregating the time series if the timescale is larger than 0. Can either be ‘sum’ or ‘mean’.

_grouped_year

Dataframe with all data grouped in a one-year (2000) DataFrame with the original years as columns

Type:

DataFrame

_dist_dict

Dictionary of distributions used to fit the data.

Type:

Dict[int, Dist]

agg_func: Literal['sum', 'mean'] = 'sum'
cdf() → Series

Compute the cumulative density function

cdf_nsf() → Series

Compute the cumulative density function using the Normal Scores Transform

Return type:

Series

dist: Any | rv_continuous
fit_distribution() → None

Fit distribution on the time series per fit_frequency and/or fit_window

fit_freq: str | None = None
fit_window: int = 0
get_dist(date: Timestamp) → Dist
norm_ppf() → Series

Method to calculate propability point function of normal distribution based on a cumulative density function of a fitted distribution

Return type:

Series

normal_scores_transform: bool = False
pdf() → Series

Compute the probability density function

ppf(q: float) → Series

Method to calculate the percentile point function (inverse of cdf — percentiles) of a fitted distribution.

Parameters:

q (float) – The quantile value (between 0 and 1) for which to calculate the percentile point function.

Return type:

Series

prob_zero: bool = False
series: Series
timescale: int = 0
spei.si.sgi(series: Series, timescale: int = 0, fit_freq: str | None = None) → Series

Method to compute the Standardized Groundwater Index. Uses the normal scores transform to calculate the cumulative density function.

Parameters:

  • series (pandas.Series) – Pandas time series of the groundwater levels. Time series index should be a pandas DatetimeIndex.

  • fit_freq (str, optional, default=None) – Frequency for fitting the distribution. Default is None in which case the frequency of the series is inferred. If this fails a monthly frequency is used.

Return type:

pandas.Series

References

Bloomfield, J. P. and Marchant, B. P.: Analysis of groundwater drought building on the standardised precipitation index approach. Hydrol. Earth Syst. Sci., 17, 4769-4787, 2013.

spei.si.spei(series: ~pandas.core.series.Series, dist: ~typing.Any | ~scipy.stats._distn_infrastructure.rv_continuous = <scipy.stats._continuous_distns.fisk_gen object>, timescale: int = 0, fit_freq: str | None = None, fit_window: int = 0, prob_zero: bool = False) → Series

Method to compute the Standardized Precipitation Evaporation Index.

Parameters:

  • series (pandas.Series) – Pandas time series of the precipitation. Time series index should be a pandas DatetimeIndex.

  • dist (scipy.stats.rv_continuous) – Can be any continuous distribution from the scipy.stats library. However, for the SPEI generally the log-logistic (fisk) probability density function is recommended. Other appropriate choices could be the lognormal or PearsonIII distribution.

  • timescale (int, optional, default=0) – Size of the moving window over which the series is summed. If zero, no summation is performed over the time series. If the time series frequency is daily, then one would provide timescale=30 for SI1, timescale=90 for SI3, timescale=180 for SI6 etc.

  • fit_freq (str, optional, default=None) – Frequency for fitting the distribution. Default is None in which case the frequency of the series is inferred. If this fails a monthly frequency is used.

  • fit_window (int, optional, default=0) – Window size for fitting data in fit_freq frequency’s unit. Default is zero in which case only data within the fit_freq is considered. If larger than zero data data within the window is used to fit the distribution for the series. fit_window must be a odd number larger than 3 when used.

  • prob_zero (bool, default=False) – Flag indicating whether the probability of zero values in the series is calculated by the occurence.

Return type:

pandas.Series

References

Vicente-Serrano S.M., Beguería S., López-Moreno J.I.: A Multi-scalar drought index sensitive to global warming: The Standardized Precipitation Evapotranspiration Index. Journal of Climate, 23, 1696-1718, 2010.

spei.si.spi(series: ~pandas.core.series.Series, dist: ~typing.Any | ~scipy.stats._distn_infrastructure.rv_continuous = <scipy.stats._continuous_distns.gamma_gen object>, timescale: int = 0, fit_freq: str | None = None, fit_window: int = 0, prob_zero: bool = True) → Series

Method to compute the Standardized Precipitation Index.

Parameters:

  • series (pandas.Series) – Pandas time series of the precipitation. Time series index should be a pandas DatetimeIndex.

  • dist (scipy.stats.rv_continuous) – Can be any continuous distribution from the scipy.stats library. However, for the SPI generally the Gamma probability density function is recommended. Other appropriate choices could be the lognormal, log-logistic (fisk) or PearsonIII distribution.

  • timescale (int, optional, default=0) – Size of the moving window over which the series is summed. If zero, no summation is performed over the time series. If the time series frequency is daily, then one would provide timescale=30 for SI1, timescale=90 for SI3, timescale=180 for SI6 etc.

  • fit_freq (str, optional, default=None) – Frequency for fitting the distribution. Default is None in which case the frequency of the series is inferred. If this fails a monthly frequency is used.

  • fit_window (int, optional, default=0) – Window size for fitting data in fit_freq frequency’s unit. Default is zero in which case only data within the fit_freq is considered. If larger than zero data data within the window is used to fit the distribution for the series. fit_window must be a odd number larger than 3 when used.

  • prob_zero (bool, default=True) – Option to correct the distribution if x=0 is not in probability density function. E.g. the case with the Gamma distriubtion. If True, the probability of zero values in the series is calculated by the occurence.

Return type:

pandas.Series

References

LLoyd-Hughes, B. and Saunders, M.A.: A drought climatology for Europe. International Journal of Climatology, 22, 1571-1592, 2002.

spei.si.ssfi(series: ~pandas.core.series.Series, dist: ~typing.Any | ~scipy.stats._distn_infrastructure.rv_continuous = <scipy.stats._continuous_distns.genextreme_gen object>, timescale: int = 0, fit_freq: str | None = None, fit_window: int = 0, prob_zero: bool = True) → Series

Method to compute the Standardized StreamFlow Index.

Parameters:

  • series (pandas.Series) – Pandas time series of the precipitation. Time series index should be a pandas DatetimeIndex.

  • dist (scipy.stats.rv_continuous) – Can be any continuous distribution from the scipy.stats library. However, for the SSFI generally the gamma probability density function is recommended. Other choices could be the normal, lognormal, pearsonIII, GEV or Gen-Logistic distribution or any distribution deemed appropriate.

  • timescale (int, optional, default=0) – Size of the moving window over which the series is summed. If zero, no summation is performed over the time series. If the time series frequency is daily, then one would provide timescale=30 for SI1, timescale=90 for SI3, timescale=180 for SI6 etc.

  • fit_freq (str, optional, default=None) – Frequency for fitting the distribution. Default is None in which case the frequency of the series is inferred. If this fails a monthly frequency is used.

  • fit_window (int, optional, default=0) – Window size for fitting data in fit_freq frequency’s unit. Default is zero in which case only data within the fit_freq is considered. If larger than zero data data within the window is used to fit the distribution for the series. fit_window must be a odd number larger than 3 when used.

  • prob_zero (bool, default=False) – Flag indicating whether the probability of zero values in the series is calculated by the occurence.

Return type:

pandas.Series

References

Vicente-Serrano, S. M., J. I. López-Moreno, S. Beguería, J. Lorenzo-Lacruz, C. Azorin-Molina, and E. Morán-Tejeda. Accurate Computation of a Streamflow Drought Index. Journal of Hydrologic Engineering 17 (2): 318-332. 2012.

spei.si.ssmi(series: ~pandas.core.series.Series, dist: ~typing.Any | ~scipy.stats._distn_infrastructure.rv_continuous = <scipy.stats._continuous_distns.beta_gen object>, timescale: int = 0, fit_freq: str | None = None, fit_window: int = 0, prob_zero: bool = True) → Series

Method to compute the Standardized Soil Moisture Index.

Parameters:

  • series (pandas.Series) – Pandas time series of the precipitation. Time series index should be a pandas DatetimeIndex.

  • dist (scipy.stats.rv_continuous) – Can be any continuous distribution from the scipy.stats library. However, for the SSMI generally the beta probability density function is recommended. Other choices could be the normal or ECDF distribution or any distribution deemed appropriate.

  • timescale (int, optional, default=0) – Size of the moving window over which the series is summed. If zero, no summation is performed over the time series. If the time series frequency is daily, then one would provide timescale=30 for SI1, timescale=90 for SI3, timescale=180 for SI6 etc.

  • fit_freq (str, optional, default=None) – Frequency for fitting the distribution. Default is None in which case the frequency of the series is inferred. If this fails a monthly frequency is used.

  • fit_window (int, optional, default=0) – Window size for fitting data in fit_freq frequency’s unit. Default is zero in which case only data within the fit_freq is considered. If larger than zero data data within the window is used to fit the distribution for the series. fit_window must be a odd number larger than 3 when used.

  • prob_zero (bool, default=False) – Flag indicating whether the probability of zero values in the series is calculated by the occurence.

Return type:

pandas.Series

References

Carrão. H., Russo, S., Sepulcre-Canto, G., Barbosa, P.: An empirical standardized soil moisture index for agricultural drought assessment from remotely sensed data. International Journal of Applied Earth Observation and Geoinformation, 48, 2016.