xhydro.indicators package¶

Indicators submodule.

Submodules¶

xhydro.indicators.generic module¶

Module to compute indicators using xclim’s build_indicator_module_from_yaml.

Calculate variables and indicators based on a YAML call to xclim.

The function cuts the output to be the same years as the inputs. Hence, if an indicator creates a timestep outside the original year range (e.g. the first DJF for QS-DEC), it will not appear in the output.

Parameters¶

dsxr.Dataset: Dataset to use for the indicators.
indicatorsstr or os.PathLike or Sequence[Indicator] or Sequence[tuple[str, Indicator]] or ModuleType: Path to a YAML file that instructs on how to calculate missing variables. Can also be only the “stem”, if translations and custom indices are implemented. Can be the indicator module directly, or a sequence of indicators or a sequence of tuples (indicator name, indicator) as returned by iter_indicators().
periodslist of str or list of lists of str, optional: Either [start, end] or list of [start, end] of continuous periods over which to compute the indicators. This is needed when the time axis of ds contains some jumps in time. If None, the dataset will be considered continuous.
restrict_yearsbool: If True, cut the time axis to be within the same years as the input. This is mostly useful for frequencies that do not start in January, such as QS-DEC. In that instance, xclim would start on previous_year-12-01 (DJF), with a NaN. restrict_years will cut that first timestep. This should have no effect on YS and MS indicators.
to_levelstr, optional: The processing level to assign to the output. If None, the processing level of the inputs is preserved.
rechunk_inputbool: If True, the dataset is rechunked with flox.xarray.rechunk_for_blockwise() according to the resampling frequency of the indicator. Each rechunking is done once per frequency with xscen.utils.rechunk_for_resample().

Returns¶

dict: Dictionary (keys = timedeltas) with indicators separated by temporal resolution.

Parameters¶

daxr.DataArray: Streamflow variable.
out_unitsstr: Output units. Defaults to “m3”.
attrsdict, optional: Attributes to add to the output variable. Default attributes for “long_name”, “units”, “cell_methods” and “description” will be added if not provided.

Returns¶

xr.DataArray: Volume of water.

xhydro.indicators.generic.get_yearly_op(ds, op, *, input_var: str = 'q', window: int = 1, timeargs: dict | None = None, missing: str = 'skip', missing_options: dict | None = None, interpolate_na: bool = False) → Dataset[source]¶

Compute yearly operations on a variable.

Parameters¶

dsxr.Dataset: Dataset containing the variable to compute the operation on.
opstr: Operation to compute. One of [“max”, “min”, “mean”, “sum”].
input_varstr: Name of the input variable. Defaults to “q”.
windowint: Size of the rolling window. A “mean” operation is performed on the rolling window before the call to xclim. This parameter cannot be used with the “sum” operation.
timeargsdict, optional: Dictionary of time arguments for the operation. Keys are the name of the period that will be added to the results (e.g. “winter”, “summer”, “annual”). Values are up to two dictionaries, with both being optional. The first is {‘freq’: str}, where str is a frequency supported by xarray (e.g. “YS”, “YS-JAN”, “YS-DEC”). It needs to be a yearly frequency. Defaults to “YS-JAN”. The second is an indexer as supported by xclim.core.calendar.select_time(). Defaults to {}, which means the whole year. See xclim.core.calendar.select_time() for more information. Examples: {“winter”: {“freq”: “YS-DEC”, “date_bounds”: [“12-01”, “02-28”]}}, {“jan”: {“freq”: “YS”, “month”: 1}}, {“annual”: {}}.
missingstr: How to handle missing values. One of “skip”, “any”, “at_least_n”, “pct”, “wmo”. See xclim.core.missing() for more information.
missing_optionsdict, optional: Dictionary of options for the missing values’ method. See xclim.core.missing() for more information.
interpolate_nabool: Whether to interpolate missing values before computing the operation. Only used with the “sum” operation. Defaults to False.

Returns¶

xr.Dataset: Dataset containing the computed operations, with one variable per indexer. The name of the variable follows the pattern {input_var}{window}_{op}_{indexer}.

Notes¶

If you want to perform a frequency analysis on a frequency that is finer than annual, simply use multiple timeargs (e.g. 1 per month) to create multiple distinct variables.

xhydro.indicators.pmp module¶

Module to compute Probable Maximum Precipitation.

xhydro.indicators.pmp.compute_spring_and_summer_mask(snw: DataArray, *, thresh: str = '1 cm', window_wint_start: int = 14, window_wint_end: int = 45, spr_start: int = 60, spr_end: int = 30, freq: str = 'YS-JUL')[source]¶

Create a mask that defines the spring and summer seasons based on the snow water equivalent.

Parameters¶

snwxarray.DataArray: Snow water equivalent. Must be a length (e.g. “mm”) or a mass (e.g. “kg m-2”).
threshQuantified: Threshold snow thickness to define the start and end of winter.
window_wint_startint: Minimum number of days with snow depth above or equal to threshold to define the start of winter.
window_wint_endint: Maximum number of days with snow depth below or equal to threshold to define the end of winter.
spr_startint: Number of days before the end of winter to define the start of spring.
spr_endint: Number of days after the end of winter to define the end of spring.
freqstr: Frequency of the time axis (annual frequency). Defaults to “YS-JUL”.

Returns¶

xr.Dataset: Dataset with two DataArrays (mask_spring and mask_summer), with values of 1 where the spring and summer criteria are met and 0 where they are not.

xhydro.indicators.pmp.major_precipitation_events(da: DataArray, *, windows: list[int], quantile: float | None = None, min_prec: str = '0 mm')[source]¶

Get precipitation events that exceed a given quantile for a given time step accumulation. Based on Clavet-Gaumont et al. (2017).

Parameters¶

daxr.DataArray: DataArray containing the precipitation values.
windowslist of int: List of the number of time steps to accumulate precipitation.
quantilefloat, optional: Threshold that limits the events to those that exceed this quantile. If quantile is None, the function returns all the accumulated values.
min_precQuantified: Minimum precipitation value to consider an event. Values equal to min_prec are excluded. Defaults to 0 mm.

Returns¶

xr.DataArray: Masked DataArray containing the major precipitation events.

Notes¶

https://doi.org/10.1016/j.ejrh.2017.07.003

xhydro.indicators.pmp.precipitable_water(*, hus: DataArray, zg: DataArray, orog: DataArray, windows: list[int] | None = None, beta_func: bool = True, add_pre_lay: bool = False)[source]¶

Compute precipitable water based on Clavet-Gaumont et al. (2017) and Rousseau et al (2014).

Parameters¶

husxr.DataArray: Specific humidity. Must have a pressure level (plev) dimension.
zgxr.DataArray: Geopotential height. Must have a pressure level (plev) dimension.
orogxr.DataArray: Surface altitude.
windowslist of int, optional: Duration of the event in time steps. Defaults to [1]. Note that an additional time step will be added to the window size to account for antecedent conditions.
beta_funcbool, optional: If True, use the beta function proposed by Boer (1982) to get the pressure layers above the topography. If False, the surface altitude is used as the lower boundary of the atmosphere assuming that the surface altitude and the geopotential height are virtually identical at low altitudes.
add_pre_laybool, optional: If True, add the pressure layer between the surface and the lowest pressure level (e.g., at sea level). If False, only the pressure layers between the lowest and highest pressure level are considered.

Returns¶

xr.DataArray: Precipitable water.

Notes¶

1) The precipitable water of an event is defined as the maximum precipitable water found during the entire duration of the event, extending up to one time step before the start of the event. Thus, the rolling operation made using windows is a maximum, not a sum.

beta_func = True and add_pre_lay = False follow Clavet-Gaumont et al. (2017) and Rousseau et al (2014).
https://doi.org/10.1016/j.ejrh.2017.07.003 https://doi.org/10.1016/j.jhydrol.2014.10.053 https://doi.org/10.1175/1520-0493(1982)110<1801:DEIIC>2.0.CO;2

xhydro.indicators.pmp.precipitable_water_100y(pw: DataArray, *, dist: str, method: str, mf: float | None = None, n: int | None = None, rebuild_time: bool = True)[source]¶

Compute the 100-year return period of precipitable water for each month. Based on Clavet-Gaumont et al. (2017).

Parameters¶

pwxr.DataArray: DataArray containing the precipitable water.
diststr: Probability distributions.
method{“ML” or “MLE”, “MM”, “PWM”, “APP”}: Fitting method, either maximum likelihood (ML or MLE), method of moments (MM) or approximate method (APP). Can also be the probability weighted moments (PWM), also called L-Moments, if a compatible dist object is passed.
mffloat, optional: Maximum majoration factor of the 100-year event compared to the maximum of the timeseries. Used as an upper limit for the frequency analysis.
nint, optional: Minimum number of data points for each month required to fit the statistical distribution. If a given month contains fewer data points than this value, pw100 is set to the maximum value of pw for that month.
rebuild_timebool: Whether or not to reconstruct a timeseries with the same time dimensions as pw.

Returns¶

xr.DataArray: Precipitable water for a 100-year return period.

Notes¶

https://doi.org/10.1016/j.ejrh.2017.07.003

xhydro.indicators.pmp.pw_snowfall(pw: DataArray, *, method: Literal['m1', 'm2', 'm3'], prsn_events: DataArray, prsn_threshold: Quantified, prra_events: DataArray | None = None, prra_threshold: Quantified | None = None, pr_events: DataArray | None = None)[source]¶

Estimate precipitable water associated with snowfall events using various filtering methods, based on Klein et al. (2017).

Parameters¶

pwxr.DataArray: DataArray containing the precipitable water.
method{“m1”, “m2”, “m3”}: Method used to identify snowfall-associated precipitable water: - m1:Selects time steps with at least snw_threshold snowfall and less than or equal to prra_threshold rainfall. - m1:Selects time steps with snowfall greater than snw_threshold, regardless of rainfall. - m3:Starts from m2 selection, but if rainfall exceeds prra_threshold, the precipitable water is scaled by the ratio of snowfall to total precipitation (prsn_events / pr_events).
prsn_eventsxr.DataArray: DataArray containing snowfall event amounts.
prsn_thresholdQuantified, optional: Minimum snowfall threshold used to filter events.
prra_eventsxr.DataArray, optional: Required for methods “m1” and “m3”. DataArray containing rainfall event amounts.
prra_thresholdQuantified, optional: Required for methods “m1” and “m3”. - For “m1”: maximum rainfall allowed. - For “m3”: minimum rainfall required for scaling.
pr_eventsxr.DataArray, optional: Required for method “m3”. DataArray containing total precipitation used to compute the snowfall ratio.

Returns¶

xr.DataArray: DataArray containing filtered precipitable water values corresponding to snowfall events.

Notes¶

https://doi.org/10.1016/j.jhydrol.2016.03.031

xhydro.indicators.pmp.spatial_average_storm_configurations(da, *, radius)[source]¶

Compute the spatial average for different storm configurations proposed by Clavet-Gaumont et al. (2017).

Parameters¶

daxr.DataArray: DataArray containing the precipitation values.
radiusfloat: Maximum radius of the storm.

Returns¶

xr.DataSet: DataSet containing the spatial averages for all the storm configurations. The y and x coordinates indicate the location of the storm. This location is determined by n//2, where n is the total number of cells for both the rows and columns in the configuration, and // represents floor division.

Notes¶

https://doi.org/10.1016/j.ejrh.2017.07.003.

xhydro.indicators.signatures module¶

Aggregated hydrological signature package for xhydro, for model evaluation.

This signature package is useful for watershed comparisons. For temporal analysis see xclim.indices._hydrology library

xhydro.indicators.signatures.elasticity_index(q: DataArray, pr: DataArray, periods: list[str] | list[list[str]] | None = None, missing: str = 'skip', missing_options: dict | None = None) → DataArray[source]¶

Elasticity index.

Compute the median of yearly streamflow elasticity index for given catchments, where elasticity (εₚ) is defined as the relative change in streamflow (ΔQ/Q) divided by the relative change in precipitation (ΔP/P).

Parameters¶

qxr.DataArray: Daily discharge data.
prxr.DataArray: Daily precipitation data.
periodslist of str or list of list of str, optional: Either [start, end] or list of [start, end] of periods to be considered. If multiple periods are given, the output will have a horizon dimension. If None, all data is used.
missingstr: How to handle missing values. One of “skip”, “any”, “at_least_n”, “pct”, “wmo”. See xclim.core.missing() for more information.
missing_optionsdict, optional: Dictionary of options for the missing values’ method. See xclim.core.missing() for more information.

Returns¶

xr.DataArray: Nonparametric estimator for streamflow elasticity index (dimensionless).

Notes¶

A value of εp greater than 1 indicates that streamflow is highly sensitive to precipitation changes, meaning a 1% change in precipitation will lead to a greater than 1% change in streamflow. A value less than 1 suggests a less sensitive relationship. It is recommended to use yearly frequency in order to have more robust elasticity_index

References¶

Sankarasubramanian, A., Vogel, R. M., & Limbrunner, J. F. (2001). Climate elasticity of streamflow in the United States. Water Resources Research, 37(6), 1771–1781. https://doi.org/10.1029/2000WR900330

xhydro.indicators.signatures.flow_duration_curve_slope(q: DataArray, periods: list[str] | list[list[str]] | None = None, missing: str = 'skip', missing_options: dict | None = None) → DataArray[source]¶

Calculate the slope of the flow duration curve mid-section between the 33% and 66% exceedance probabilities.

Aggregated analysis : Single value as a long-term benchmark.

Parameters¶

qxarray.DataArray: Daily streamflow data, expected to have a discharge unit.
periodslist of str or list of list of str, optional: Either [start, end] or list of [start, end] of periods to be considered. If multiple periods are given, the output will have a horizon dimension. If None, all data is used.
missingstr: How to handle missing values. One of “skip”, “any”, “at_least_n”, “pct”, “wmo”. See xclim.core.missing() for more information.
missing_optionsdict, optional: Dictionary of options for the missing values’ method. See xclim.core.missing() for more information.

Returns¶

xarray.DataArray: Slope of the FDC between the 33% and 66% exceedance probabilities, unitless.

Notes¶

Single Returned numeric values are positive.

High slope value : Steep slopes of the midsegment FDC are typically a characteristic behavior for watersheds having ‘flashy’ responses (for example due to small soil storage capacity and hence larger percentage of overland flow).

Lower slope value : Flatter slopes of the midsegment FDC are associated with watersheds having slower and more sustained groundwater low response.

References¶

Vogel, R. M., & Fennessey, N. M. (1994). Flow-duration curves. I: New interpretation and confidence intervals. Journal of Water Resources Planning and Management, 120(4), 485-504. DOI:10.1061/(ASCE)0733-9496(1994)120:4(485)

Yilmaz, K. K., Gupta, H. V., & Wagener, T. (2008). A process‐based diagnostic approach to model evaluation: Application to the NWS distributed hydrologic model. Water resources research, 44(9). DOI:10.1029/2007WR006716

xhydro.indicators.signatures.hurst_exp(q: DataArray, selected_low_frequecy: int = 0.01, periods: list[str] | list[list[str]] | None = None, missing: str = 'skip', missing_options: dict | None = None) → DataArray[source]¶

Hurst Exponent.

Compute the Hurst Exponent (H) of time-series obtained from the slope of the power spectral density (estimated by periodogram) of the streamflow time series at near-zero frequency.

Parameters¶

qxarray.DataArray: Streamflow in [discharge] units.
selected_low_frequecyint: Near-zero frequency, can be adjusted to best represent the persistency of observed streamflow. Default is 0.01.
periodslist of str or list of list of str, optional: Either [start, end] or list of [start, end] of periods to be considered. If multiple periods are given, the output will have a horizon dimension. If None, all data is used.
missingstr: How to handle missing values. One of “skip”, “any”, “at_least_n”, “pct”, “wmo”. See xclim.core.missing() for more information.
missing_optionsdict, optional: Dictionary of options for the missing values’ method. See xclim.core.missing() for more information.

Returns¶

xarray.DataArray: Single value Hurst Exponent (H).

Notes¶

In order to compute Hurst Exponent, missing values (if any) will be linearly interpolated along the time dimension. Leading and trailing NaNs will be filled using nearest valid neighbor method. Remaining single NaNs (if any) will be filled using linear interpolation.

Hurst Exponent serves as a statistical health check for observed and simulated streamflows;
H>0.5: persistence (long-term memory, common in hydrology) acceptable range: 0.5 to 1.
H<0.5: noise and anti-persistence.

References¶

Gupta, A., Hantush, M. M., Govindaraju, R. S., & Beven, K. (2024). Evaluation of hydrological models at gauged and ungauged basins using machine learning-based limits-of-acceptability and hydrological signatures. Journal of Hydrology, 641, 131774. https://doi.org/10.1016/j.jhydrol.2024.131774.

Koutsoyiannis, D., and A. Montanari (2007), Statistical analysis of hydroclimatic time series: Uncertainty and insights, Water Resour. Res., 43, W05429, doi:10.1029/2006WR005592.

xhydro.indicators.signatures.total_runoff_ratio(q: DataArray, drainage_area: DataArray, pr: DataArray, periods: list[str] | list[list[str]] | None = None, missing: str = 'skip', missing_options: dict | None = None) → DataArray[source]¶

Total runoff ratio.

Compute the ratio of streamflow measured at a stream gauge station to the total precipitation over the watershed. Also known as the runoff coefficient, it is higher in watersheds with steep slopes, impervious surfaces or high evapotranspiration.

Parameters¶

qxarray.DataArray: Streamflow.
drainage_areaxarray.DataArray: Watershed.
prxarray.DataArray: Mean daily Precipitation.
periodslist of str or list of list of str, optional: Either [start, end] or list of [start, end] of periods to be considered. If multiple periods are given, the output will have a horizon dimension. If None, all data is used.
missingstr: How to handle missing values. One of “skip”, “any”, “at_least_n”, “pct”, “wmo”. See xclim.core.missing() for more information.
missing_optionsdict, optional: Dictionary of options for the missing values’ method. See xclim.core.missing() for more information.

Returns¶

xarray.DataArray: Single value rainfall-runoff ratio (RRR) as long-term benchmark.

Notes¶

Total Runoff ratio values are comparable to Runoff coefficients,
Values near 0 mean most precipitation infiltrates watershed soil or is lost to evapotranspiration.
Values near 1 mean most precipitation leaves the watershed as runoff; possible causes are impervious surfaces from urban sprawl, thin soils, steep slopes, etc.
Long-term averages are typically ≤ 1.

References¶

HydroBM https://hydrobm.readthedocs.io/en/latest/usage.html#benchmarks

xhydro.indicators package¶

Submodules¶

xhydro.indicators.generic module¶

Parameters¶

Returns¶

See Also¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Notes¶

xhydro.indicators.pmp module¶

Parameters¶

Returns¶

Parameters¶

Returns¶

Notes¶

Parameters¶

Returns¶

Notes¶

Parameters¶

Returns¶

Notes¶

Parameters¶

Returns¶

Notes¶

Parameters¶

Returns¶

Notes¶

xhydro.indicators.signatures module¶

Parameters¶

Returns¶

Notes¶

References¶

Parameters¶

Returns¶

Notes¶

References¶

Parameters¶

Returns¶

Notes¶

References¶

Parameters¶

Returns¶

Notes¶

References¶