add standardized soil moisture index

README.md

@@ -29,8 +29,9 @@ If you happen to use this package, please cite: Vonk, M. A. (2024). SPEI: A simp
 | Standardized Precipitation Evaporation Index | SPEI         | 2          |
 | Standardized Groundwater Index               | SGI          | 3,4        |
 | Standardized Streamflow Index                | SSFI         | 5          |
+| Standardized Soil Moisture Index             | SSMI         | 6          |
 
-The package is not limited to only these four drought indices. If any of the distributions in the Scipy library is valid, the drought index can be calculated.
+The package is not limited to only these five drought indices. If any of the distributions in the Scipy library is valid on the observed hydrological series, the drought index can be calculated.
 
 ## Installation
 
@@ -49,6 +50,7 @@ To get the development version download or clone the GitHub repository to your l
 3. J.P. Bloomfield and B.P. Marchant, B. P. (2013) - Analysis of groundwater drought building on the standardised precipitation index approach. DOI: 10.5194/hess-17-4769-2013
 4. A. Babre, A. Kalvāns, Z. Avotniece, I. Retiķe, J. Bikše, K.P.M. Jemeljanova, A. Zelenkevičs and A. Dēliņa (2022) - The use of predefined drought indices for the assessment of groundwater drought episodes in the Baltic States over the period 1989–2018. DOI: 10.1016/j.ejrh.2022.101049
 5. E. Tijdeman, K. Stahl and L.M. Tallaksen (2020) - Drought characteristics derived based on the Standardized Streamflow Index: A large sample comparison for parametric and nonparametric methods. DOI: 10.1029/2019WR026315
+6. Carrão. H., Russo, S., Sepulcre-Canto, G., Barbosa, P.: An empirical standardized soil moisture index for agricultural drought assessment from remotely sensed data. DOI: 10.1016/j.jag.2015.06.011s
 
 Note that the method for calculating the drought indices does not come from these articles and SciPy is used for deriving the distribution. However the literature is helpful as a reference to understand the context and application of drought indices.
 

src/spei/si.py

@@ -4,7 +4,7 @@
 
 from numpy import ceil, linspace, nan
 from pandas import DataFrame, Grouper, Series, Timedelta, Timestamp
-from scipy.stats import fisk, gamma, genextreme, norm
+from scipy.stats import beta, fisk, gamma, genextreme, norm
 
 from ._typing import ContinuousDist
 from .dist import Dist
@@ -206,9 +206,10 @@ def ssfi(
         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 appropriate choices could be the
-        normal, lognormal, pearsonIII, GEV or  Gen-Logistic distribution.
+        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
@@ -252,6 +253,70 @@ def ssfi(
     return ssfi.norm_ppf()
 
 
+def ssmsi(
+    series: Series,
+    dist: ContinuousDist = beta,
+    timescale: int = 0,
+    fit_freq: Optional[str] = None,
+    fit_window: int = 0,
+    prob_zero: bool = True,
+) -> Series:
+    """Method to compute the Standardized Soil Moisture Index [ssmi_2016]_.
+
+    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.
+
+    Returns
+    -------
+    pandas.Series
+
+    References
+    ----------
+    .. [ssmi_2016] 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.
+    """
+
+    ssmi = SI(
+        series=series,
+        dist=dist,
+        timescale=timescale,
+        fit_freq=fit_freq,
+        fit_window=fit_window,
+        prob_zero=prob_zero,
+        normal_scores_transform=False,
+    )
+    ssmi.fit_distribution()
+    return ssmi.norm_ppf()
+
+
 @dataclass
 class SI:
     """