Metrics of Hydrological Skill (hydrostats.metrics)

HydroErr

The metrics in Hydrostats are available through the HydroErr package. Below is a link to the HydroErr documentation page that lists all of the metrics contained in the package.

Link - https://hydroerr.readthedocs.io/en/stable/

The metrics can be imported into your scripts as part of the metrics module. An example is provided below showing how to use the metrics included in the package from HydroErr (if you would prefer to only use the Hydrostats package and not just import the HydroErr package).

import hydrostats.metrics as hm
import numpy as np

sim = np.array([5, 7, 9, 2, 4.5, 6.7])
obs = np.array([4.7, 6, 10, 2.5, 4, 6.8])

mean_error = hm.me(sim, obs)
print(mean_error)

Functions

hydrostats.metrics.list_of_metrics(metrics: Sequence[str], sim_array: ndarray[tuple[Any, ...], dtype[floating | integer]] | Sequence[int | float], obs_array: ndarray[tuple[Any, ...], dtype[floating | integer]] | Sequence[int | float], abbr: bool = False, mase_m: int = 1, dmod_j: float = 1, nse_mod_j: float = 1, h6_mhe_k: float = 1, h6_ahe_k: float = 1, h6_rmshe_k: float = 1, d1_p_obs_bar_p: float | None = None, lm_x_obs_bar_p: float | None = None, kge2009_s: tuple[float, float, float] = (1, 1, 1), kge2012_s: tuple[float, float, float] = (1, 1, 1), replace_nan: float | None = None, replace_inf: float | None = None, remove_neg: bool = False, remove_zero: bool = False) → list[float]

Compute multiple hydrologic skill metrics for paired simulated and observed series.

Given a list of metric names or abbreviations, this function computes each metric for the provided simulated and observed arrays, applying optional preprocessing to handle NaN/Inf values and to remove zeros or negatives. It supports passing parameters for specific metrics (e.g., m for MASE, j for modified metrics, s tuples for KGE variants).

Parameters:

  • metrics – A sequence of metric identifiers to compute. These must correspond to either the full metric names in HydroErr.HydroErr.metric_names or their abbreviations in HydroErr.HydroErr.metric_abbr depending on the value of the abbr parameter.

  • sim_array – 1-D array of simulated values.

  • obs_array – 1-D array of observed values. Must be the same size as sim_array.

  • abbr – If True, interpret metrics as abbreviations (e.g., "MASE", "KGE (2012)"). If False (default), interpret metrics as full names (e.g. "Mean Absolute Scaled Error", "Kling-Gupta Efficiency (2012)").

  • mase_m – If given, indicates the seasonal period m for MASE. If not given, the default is 1.

  • dmod_j (float, optional) – Exponent parameter for Modified Index of Agreement (dmod). Default is 1. A higher j gives more emphasis to outliers

  • nse_mod_j (float, optional) – Exponent parameter for Modified Nash-Sutcliffe Efficiency (nse_mod). Default is 1. A higher j gives more emphasis to outliers.

  • h6_mhe_k (float, optional) – Parameter k for Mean H6 Error (h6_mhe). Default is 1.

  • h6_ahe_k (float, optional) – Parameter k for Mean Absolute H6 Error (h6_mahe). Default is 1.

  • h6_rmshe_k (float, optional) – Parameter k for Root Mean Square H6 Error (h6_rmshe). Default is 1.

  • d1_p_obs_bar_p (float or None, optional) – Seasonal or other selected average for Legate-McCabe Index of Agreement (d1_p). If None (default), the mean of the observed array will be used.

  • lm_x_obs_bar_p (float or None, optional) – Seasonal or other selected average for Legate-McCabe Efficiency Index (lm_index). If None (default), the mean of the observed array will be used.

  • kge2009_s (tuple[float, float, float], optional) – Weights s tuple for KGE (2009) in order of (r, alpha, beta). Default is (1, 1, 1).

  • kge2012_s (tuple[float, float, float], optional) – Weights s tuple for KGE (2012) in order of (r, gamma, beta). Default is (1, 1, 1).

  • replace_nan (float or None, optional) – If given, indicates which value to replace NaN values with in the two arrays. If None, when a NaN value is found at the i-th position in the observed OR simulated array, the i-th value of the observed and simulated array are removed before the computation.

  • replace_inf (float or None, optional) – If given, indicates which value to replace Inf values with in the two arrays. If None, when an inf value is found at the i-th position in the observed OR simulated array, the i-th value of the observed and simulated array are removed before the computation.

  • remove_neg (bool, optional) – If True, when a negative value is found at the i-th position in the observed OR simulated array, the i-th value of the observed AND simulated array are removed before the computation.

  • remove_zero (bool, optional) – If true, when a zero value is found at the i-th position in the observed OR simulated array, the i-th value of the observed AND simulated array are removed before the computation.

Return type:

A list of metric values in the same order as provided in metrics.

Raises:

  • ValueError – If either sim_array or obs_array is not one-dimensional.

  • ValueError – If sim_array and obs_array do not have the same size.

Examples

>>> import numpy as np
>>> import hydrostats.metrics as he
>>> sim = np.array([5, 7, 9, 2, 4.5, 6.7])
>>> obs = np.array([4.7, 6, 10, 2.5, 4, 6.8])
>>> he.list_of_metrics(["Mean Absolute Scaled Error", "Modified Index of Agreement"], sim, obs)
[he.mase(sim, obs, m=1), he.dmod(sim, obs, j=1)]

You can also use abbreviations by setting abbr=True and pass parameters for certain metrics:

>>> he.list_of_metrics(
...     ["MASE", "KGE (2009)", "KGE (2012)"],
...     sim,
...     obs,
...     abbr=True,
...     mase_m=3,
...     kge2009_s=(1.2, 0.8, 0.6),
...     kge2012_s=(1.4, 0.7, 0.9),
... )
[
    he.mase(sim, obs, m=3),
    he.kge_2009(sim, obs, s=(1.2, 0.8, 0.6)),
    he.kge_2012(sim, obs, s=(1.4, 0.7, 0.9))
]