Standardized Streamflow Index and Standardized Groundwater level Index (#1877)

<!--Please ensure the PR fulfills the following requirements! -->
<!-- If this is your first PR, make sure to add your details to the
AUTHORS.rst! -->
### Pull Request Checklist:
- [x] This PR addresses an already opened issue (for bug fixes /
features)
    - This PR fixes #1444
- [x] Tests for the changes have been added (for bug fixes / features)
- [x] (If applicable) Documentation has been added / updated (for bug
fixes / features)
- [x] CHANGELOG.rst has been updated (with summary of main changes)
- [x] Link to issue (:issue:`number`) and pull request (:pull:`number`)
has been added

### What kind of change does this PR introduce?

* 2 new indices/indicators : SSI and SGI

### Does this PR introduce a breaking change?
No

### Other information:
* SSI will use GEV or log-logistic (scipy does not support tweedie)
* SGI will use log-normal, gamma or GEV

Author: coxipi

.github/workflows/main.yml

@@ -19,7 +19,7 @@ on:
       - submitted
 
 env:
-  XCLIM_TESTDATA_BRANCH: v2025.1.8
+  XCLIM_TESTDATA_BRANCH: v2025.3.11
 
 concurrency:
   # For a given workflow, if we push to the same branch, cancel all previous builds on that branch except on main.

CHANGELOG.rst

@@ -4,7 +4,7 @@ Changelog
 
 v0.56.0 (unreleased)
 --------------------
-Contributors to this version: Trevor James Smith (:user:`Zeitsperre`), Hui-Min Wang (:user:`Hem-W`), Jack Kit-tai Wong(:user:`jack-ktw`), Éric Dupuis (:user:`coxipi`).
+Contributors to this version: Trevor James Smith (:user:`Zeitsperre`), Hui-Min Wang (:user:`Hem-W`), Jack Kit-tai Wong(:user:`jack-ktw`), Adrien Lamarche (:user:`LamAdr`), Éric Dupuis (:user:`coxipi`).
 
 Bug fixes
 ^^^^^^^^^
@@ -28,6 +28,11 @@ Internal changes
 * The `xclim` documentation now has a ``support`` page for detailing the project's usage and version support policies. (:pull:`2100`).
 * The indicator `heat_wave_index` now uses `hot_spell_total_length` index. The `heat_wave_index` index is identitical to `hot_spell_total_length` and will be dropped in future versions. (:issue:`2031`, :pull:`2102`).
 
+New indicators
+^^^^^^^^^^^^^^
+* Added standardized indicators for hydrology: ``xclim.land.standardized_streamflow_index`` and ``xclim.landstandardized_groundwater_index``.  (:issue:`1444`, :pull:`1877`).
+
+
 v0.55.1 (2025-02-26)
 --------------------
 Contributors to this version: Éric Dupuis (:user:`coxipi`).

docs/references.bib

@@ -2236,6 +2236,32 @@ @article{knol_1989
 	number = "1",
 }
 
+@article{vicente-serrano_2012,
+	author = {Sergio M. Vicente-Serrano  and Juan I. López-Moreno  and Santiago Beguería  and Jorge Lorenzo-Lacruz  and Cesar Azorin-Molina  and Enrique Morán-Tejeda},
+	title = {Accurate Computation of a Streamflow Drought Index},
+	journal = {Journal of Hydrologic Engineering},
+	volume = {17},
+	number = {2},
+	pages = {318-332},
+	year = {2012},
+	doi = {10.1061/(ASCE)HE.1943-5584.0000433},
+	URL = {https://ascelibrary.org/doi/abs/10.1061/%28ASCE%29HE.1943-5584.0000433},
+	eprint = {https://ascelibrary.org/doi/pdf/10.1061/%28ASCE%29HE.1943-5584.0000433},
+    abstract = "In this study, the authors investigated an approach to calculate the standardized streamflow index (SSI), which allows accurate spatial and temporal comparison of the hydrological conditions of a stream or set of streams. For this purpose, the capability of six three-parameter distributions (lognormal, Pearson Type III, log-logistic, general extreme value, generalized Pareto, and Weibull) and two different approaches to select the most suitable distribution the best monthly fit (BMF) and the minimum orthogonal distance (MD), were tested by using a monthly streamflow data set for the Ebro Basin (Spain). This large Mediterranean basin is characterized by high variability in the magnitude of streamflows and in seasonal regimes. The results show that the most commonly used probability distributions for flow frequency analysis provided good fits to the streamflow series. Thus, the visual inspection of the L-moment diagrams and the results of the Kolmogorov-Smirnov test did not enable the selection of a single optimum probability distribution. However, no single probability distribution for all the series was suitable for obtaining a robust standardized streamflow series because each of the distributions had one or more limitations. The BMF and MD approaches improved the results in the expected average, standard deviation, and the frequencies of extreme events of the SSI series in relation to the selection of a unique distribution for each station. The BMF and MD approaches involved using different probability distributions for each gauging station and month of the year to calculate the SSI. Both approaches are easy to apply and they provide very similar results in the quality of the obtained hydrological drought indexes. The proposed procedures are very flexible for analyses involving contrasting hydrological regimes and flow characteristics."
+}
+
+@article{bloomfield_2013,
+	AUTHOR = {Bloomfield, J. P. and Marchant, B. P.},
+	TITLE = {Analysis of groundwater drought building on the standardised precipitation index approach},
+	JOURNAL = {Hydrology and Earth System Sciences},
+	VOLUME = {17},
+	YEAR = {2013},
+	NUMBER = {12},
+	PAGES = {4769--4787},
+	URL = {https://hess.copernicus.org/articles/17/4769/2013/},
+	DOI = {10.5194/hess-17-4769-2013}
+}
+
 @article{luedeling_chill_2009,
 	title = {Climate change impacts on winter chill for temperate fruit and nut production: A review},
 	journal = {Scientia Horticulturae},

src/xclim/core/indicator.py

@@ -1939,3 +1939,10 @@ def _merge_attrs(dbase, dextra, attr, sep):
             load_locale(loc_dict, locale)
 
     return mod
+
+
+class StandardizedIndexes(ResamplingIndicator):
+    """Resampling but flexible inputs indicators."""
+
+    src_freq = ["D", "MS"]
+    context = "hydro"

src/xclim/data/fr.json

@@ -269,6 +269,12 @@
     "title": "Précipitation liquide accumulée totale",
     "abstract": "Précipitation liquide accumulée totale. Les précipitations sont considérées liquides lorsque la température quotidienne moyenne est au-dessus de 0°C."
   },
+  "SGI": {
+    "long_name": "Indice d'eau souterraine standardisé (SGI)",
+    "description": "Niveau de l'eau souterraine sur une fenêtre mobile de {window} {freq:nom}, normalisé telle que la moyenne du SGI est 0 pour les données de calibration. L'unité de la fenêtre 'X' est l'unité de temps déterminée par la fréquence de rééchantillonage,",
+    "title": "Indice d'eau souterraine standardisé (SGI)",
+    "abstract": "Niveau de l'eau souterraine sur une fenêtre mobile, normalisée telle que la moyenne du SGI est 0 pour les données de calibration. L'unité de la fenêtre est l'unité de temps déterminée par la fréquence de rééchantillonnage."
+  },
   "SOLIDPRCPTOT": {
     "long_name": "Précipitation totale lorsque la température moyenne est en dessous ou égale à {thresh}",
     "description": "Précipitation solide totale {freq:f}, estimée comme la précipitation lorsque la température moyenne est en dessous ou égale à {thresh}.",
@@ -287,6 +293,12 @@
     "title": "Indice de précipitation évapotranspiration standardisé (SPEI)",
     "abstract": "Budget d'eau (précipitation - évapotranspiration) sur une fenêtre mobile, normalisé tel que la moyenne du SPEI est 0 pour les données de calibration. L'unité de la fenêtre est l'unité de temps déterminée par la fréquence de rééchantillonnage."
   },
+  "SSI": {
+    "long_name": "Indice d'écoulement standardisé (SSI)",
+    "description": "Écoulement sur une fenêtre mobile de {window} {freq:nom}, normalisée telle que la moyenne du SSI est 0 pour les données de calibration. L'unité de la fenêtre 'X' est l'unité de temps déterminée par la fréquence de rééchantillonage,",
+    "title": "Indice d'écoulement standardisé (SSI)",
+    "abstract": "Écoulement sur une fenêtre mobile, normalisée telle que la moyenne du SSI est 0 pour les données de calibration. L'unité de la fenêtre est l'unité de temps déterminée par la fréquence de rééchantillonnage."
+  },
   "DC": {
     "long_name": "Indice de sécheresse",
     "description": "Code numérique estimant la teneur en humidité moyenne des couches organiques.",

src/xclim/data/variables.yml

@@ -30,6 +30,10 @@ variables:
     standard_name: water_potential_evapotranspiration_flux
     data_flags:
       - negative_accumulation_values:
+  gwl:
+    canonical_units: m
+    description: Groundwater level.
+    dimensions: "[length]"
   hurs:
     canonical_units: '%'
     cell_methods: "time: mean"

src/xclim/indicators/atmos/_precip.py

@@ -10,8 +10,8 @@
     Daily,
     Hourly,
     Indicator,
-    ResamplingIndicator,
     ResamplingIndicatorWithIndexing,
+    StandardizedIndexes,
 )
 from xclim.core.utils import InputKind
 
@@ -115,13 +115,6 @@ def cfcheck(pr: DataArray, tas: DataArray):
         cfchecks.check_valid(tas, "standard_name", "air_temperature")
 
 
-class StandardizedIndexes(ResamplingIndicator):
-    """Resampling but flexible inputs indicators."""
-
-    src_freq = ["D", "MS"]
-    context = "hydro"
-
-
 class HrPrecip(Hourly):
     """Indicator involving hourly pr series."""
 
@@ -372,6 +365,7 @@ class HrPrecip(Hourly):
 )
 
 standardized_precipitation_index = StandardizedIndexes(
+    realm="atmos",
     title="Standardized Precipitation Index (SPI)",
     identifier="spi",
     units="",
@@ -387,6 +381,7 @@ class HrPrecip(Hourly):
 )
 
 standardized_precipitation_evapotranspiration_index = StandardizedIndexes(
+    realm="atmos",
     title="Standardized Precipitation Evapotranspiration Index (SPEI)",
     identifier="spei",
     units="",

src/xclim/indicators/land/_streamflow.py

@@ -8,6 +8,7 @@
 from xclim.core.indicator import (
     ReducingIndicator,
     ResamplingIndicator,
+    StandardizedIndexes,
 )
 from xclim.core.units import declare_units
 from xclim.indices import (
@@ -17,6 +18,8 @@
     high_flow_frequency,
     low_flow_frequency,
     rb_flashiness_index,
+    standardized_groundwater_index,
+    standardized_streamflow_index,
 )
 
 __all__ = [
@@ -27,6 +30,8 @@
     "high_flow_frequency",
     "low_flow_frequency",
     "rb_flashiness_index",
+    "standardized_groundwater_index",
+    "standardized_streamflow_index",
 ]
 
 
@@ -97,6 +102,7 @@ def cfcheck(q: DataArray):
     parameters={"op": generic.doymin, "out_units": None},
 )
 
+
 flow_index = ReducingIndicator(
     realm="land",
     context="hydro",
@@ -130,3 +136,36 @@ def cfcheck(q: DataArray):
     units="days",
     compute=low_flow_frequency,
 )
+
+standardized_streamflow_index = StandardizedIndexes(
+    realm="land",
+    title="Standardized Streamflow Index (SSI)",
+    identifier="ssi",
+    units="",
+    standard_name="ssi",
+    long_name="Standardized Streamflow Index (SSI)",
+    description="Streamflow over a moving {window}-X window, normalized such that SSI averages to 0 for "
+    "calibration data. The window unit `X` is the minimal time period defined by resampling frequency {freq}.",
+    abstract="Streamflow over a moving window, normalized such that SSI averages to 0 for the calibration data. "
+    "The window unit `X` is the minimal time period defined by the resampling frequency.",
+    cell_methods="",
+    keywords="streamflow",
+    compute=standardized_streamflow_index,
+)
+
+
+standardized_groundwater_index = StandardizedIndexes(
+    realm="land",
+    title="Standardized Groundwater Index (SGI)",
+    identifier="sgi",
+    units="",
+    standard_name="sgi",
+    long_name="Standardized Groundwater Index (SGI)",
+    description="Groundwater over a moving {window}-X window, normalized such that SGI averages to 0 for "
+    "calibration data. The window unit `X` is the minimal time period defined by resampling frequency {freq}.",
+    abstract="Groundwater over a moving window, normalized such that SGI averages to 0 for the calibration data. "
+    "The window unit `X` is the minimal time period defined by the resampling frequency.",
+    cell_methods="",
+    keywords="groundwater",
+    compute=standardized_groundwater_index,
+)

src/xclim/indices/_agro.py

@@ -1113,8 +1113,8 @@ def standardized_precipitation_index(
     pr : xarray.DataArray
         Daily precipitation.
     freq : str, optional
-        Resampling frequency. A monthly or daily frequency is expected. Option `None` assumes that desired resampling
-        has already been applied input dataset and will skip the resampling step.
+        Resampling frequency. A monthly or daily frequency is expected. Option `None` assumes
+        that the desired resampling has already been applied input dataset and will skip the resampling step.
     window : int
         Averaging window length relative to the resampling frequency. For example, if `freq="MS"`,
         i.e. a monthly resampling, the window is an integer number of months.
@@ -1254,8 +1254,8 @@ def standardized_precipitation_evapotranspiration_index(
     wb : xarray.DataArray
         Daily water budget (pr - pet).
     freq : str, optional
-        Resampling frequency. A monthly or daily frequency is expected. Option `None` assumes that desired resampling
-        has already been applied input dataset and will skip the resampling step.
+        Resampling frequency. A monthly or daily frequency is expected. Option `None` assumes
+        that the desired resampling has already been applied input dataset and will skip the resampling step.
     window : int
         Averaging window length relative to the resampling frequency. For example, if `freq="MS"`, i.e. a monthly
         resampling, the window is an integer number of months.