Create _streamflow_flow_indices.py

AUTHORS.rst

@@ -44,3 +44,4 @@ Contributors
 * Dante Castro <[email protected]> `@profesorpaiche <https://github.com/profesorpaiche>`_
 * Sascha Hofmann <[email protected]> `@saschahofmann <https://github.com/saschahofmann>`_
 * Javier Diez-Sierra <[email protected]> `@JavierDiezSierra <https://github.com/JavierDiezSierra>`_
+* Faisal Mahmood <[email protected]> <[email protected]> `@faimahsho <https://github.com/faimahsho>`_

docs/references.bib

@@ -2152,3 +2152,35 @@ @article{droogers2002
 	url = {https://www.scopus.com/inward/record.uri?eid=2-s2.0-0036464359&doi=10.1023%2fA%3a1015508322413&partnerID=40&md5=7322aaa4c6874878f5b1dab3c73c1718},
 	type = {Article}
 }
+
+@article{article,
+    author = {Addor, Nans and Nearing, Grey and Prieto, Cristina and Newman, A. and Le Vine, Nataliya and Clark, Martyn},
+    year = {2018},
+    month = {11},
+    pages = {},
+    title = {A Ranking of Hydrological Signatures Based on Their Predictability in Space},
+    journal = {Water Resources Research},
+    doi = {10.1029/2018WR022606}
+}
+
+@article{article,
+    author = {Clausen, B and Biggs, Barry},
+    year = {2000},
+    month = {11},
+    pages = {184-197},
+    title = {Flow variables for ecological studies in temperate streams: Groupings based on covariance},
+    volume = {237},
+    journal = {Journal of Hydrology},
+    doi = {10.1016/S0022-1694(00)00306-1}
+}
+
+@article{article,
+    author = {Olden, Julian and Poff, N.},
+    year = {2003},
+    month = {03},
+    pages = {101 - 121},
+    title = {Redundancy and the Choice of Hydrologic Indices for Characterizing Stream Flow Regimes},
+    volume = {19},
+    journal = {River Research and Applications},
+    doi = {10.1002/rra.700}
+}

xclim/indices/_streamflow_flow_indices.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from xclim.core.units import declare_units
+
+
+@declare_units(q="[discharge]")
+def flow_index(q: xr.DataArray, p: float = 0.95) -> xr.DataArray:
+    """
+    Calculate the Qp  (pth percentile of daily streamflow) normalized by the mean flow.
+
+    Reference:
+    1. Addor, Nans & Nearing, Grey & Prieto, Cristina & Newman, A. & Le Vine, Nataliya & Clark, Martyn. (2018). A Ranking of Hydrological Signatures Based on Their Predictability in Space. Water Resources Research. 10.1029/2018WR022606.
+    2. Clausen, B., & Biggs, B. J. F. (2000). Flow variables for ecological studies in temperate streams: Groupings based on covariance. Journal of Hydrology, 237(3–4), 184–197. https://doi.org/10.1016/S0022-1694(00)00306-1
+
+    Parameters
+    ----------
+    q : xarray.DataArray
+        Daily streamflow data.
+    p : float
+        Percentile for calculating the flow index, between 0 and 1. Default of 0.95 is for high flows.
+
+    Returns
+    -------
+    xarray.DataArray
+        out = Normalized Qp, which is the p th percentile of daily streamflow normalized by the median flow.
+
+    """
+    qp = q.quantile(p, dim="time")
+    q_median = q.median(dim="time")
+    out = qp / q_median
+    out.attrs["units"] = " "
+    return out.rename("flow_index")
+
+
+@declare_units(q="[discharge]")
+def high_flow_frequency(
+    q: xr.DataArray,
+    threshold_factor: int = 9
+    freq: str = "A-SEP",
+    statistic: str = "mean",
+) -> xr.DataArray:
+    """
+    Calculate the mean number of days in a given period with flows greater than a specified threshold. By default, the period is the water year starting on 1st October and ending on 30th September, as commonly defined in North America.
+
+    Reference:
+    1. Addor, Nans & Nearing, Grey & Prieto, Cristina & Newman, A. & Le Vine, Nataliya & Clark, Martyn. (2018). A Ranking of Hydrological Signatures Based on Their Predictability in Space. Water Resources Research. 10.1029/2018WR022606.
+    2. Clausen, B., & Biggs, B. J. F. (2000). Flow variables for ecological studies in temperate streams: Groupings based on covariance. Journal of Hydrology, 237(3–4), 184–197. https://doi.org/10.1016/S0022-1694(00)00306-1
+
+    Parameters
+    ----------
+    q : xarray.DataArray
+        Daily streamflow data.
+    threshold_factor : float, optional
+        Factor by which the median flow is multiplied to set the high flow threshold, default is 9.0.
+    freq : str, optional
+        Resampling frequency, default is 'A-SEP' for water year ending in September.
+    statistic : str, optional
+        Type of statistic to return ('mean', 'sum', 'max', median etc.), default is 'mean'.
+
+    Returns
+    -------
+    xarray.DataArray
+        Calculated statistic of high flow days per water year, by default it is set as mean
+    """
+    median_flow = q.median(dim="time")
+    threshold = threshold_factor * median_flow
+
+    # Resample data to the given frequency and count days above threshold
+    high_flow_days = (q > threshold).resample(time=freq).sum(dim="time")
+
+    # Dynamically apply the chosen statistic using getattr
+    out = getattr(high_flow_days, statistic)(dim="time")
+
+    # Assign units to the result based on the statistic
+    out.attrs["units"] = "days/year" if statistic == "mean" else "days"
+
+    # Rename the result for clarity
+    return out.rename(f"high flow frequency({statistic})")
+
+
+@declare_units(q="[discharge]")
+def low_flow_frequency(
+    q: xr.DataArray,
+    threshold_factor: float = 0.2,
+    freq: str = "A-SEP",
+    statistic: str = "mean",
+) -> xr.DataArray:
+    """
+    Calculate the specified statistic of the number of days in a given period with flows lower than a specified threshold.
+    By default, the period is the water year starting on 1st October and ending on 30th September, as commonly defined in North America.
+
+    Reference:
+    Olden, J. D., & Poff, N. L. (2003). Redundancy and the choice of hydrologic indices for characterizing streamflow regimes. River Research and Applications, 19(2), 101–121. https://doi.org/10.1002/rra.700
+
+    Parameters
+    ----------
+    q : xarray.DataArray
+        Daily streamflow data.
+    threshold_factor : float, optional
+        Factor by which the mean flow is multiplied to set the low flow threshold, default is 0.2.
+    freq : str, optional
+        Resampling frequency, default is 'A-SEP' for water year ending in September.
+    statistic : str, optional
+        Type of statistic to return ('mean', 'sum', 'max', median etc.), default is 'mean'.
+
+    Returns
+    -------
+    xarray.DataArray
+        Calculated statistic of low flow days per water year, by default it is set as mean
+    """
+    mean_flow = q.mean(dim="time")
+    threshold = threshold_factor * mean_flow
+
+    # Resample data to the given frequency and count days below threshold
+    low_flow_days = (q < threshold).resample(time=freq).sum(dim="time")
+
+    # Dynamically apply the chosen statistic using getattr
+    out = getattr(low_flow_days, statistic)(dim="time")
+
+    # Assign units to the result based on the statistic
+    out.attrs["units"] = "days/year" if statistic == "mean" else "days"
+
+    # Rename the result for clarity
+    return out.rename(f"low flow frequency({statistic})")