kge_2012

HydroErr.HydroErr.kge_2012(simulated_array: ndarray[tuple[Any, ...], dtype[floating | integer]] | Sequence[int | float], observed_array: ndarray[tuple[Any, ...], dtype[floating | integer]] | Sequence[int | float], 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, return_all: bool = False) → floating[Any] | tuple[floating[Any], floating[Any], floating[Any], floating[Any]]

Compute the Kling-Gupta efficiency (2012).

\[KGE_{2012}=1-ED\]
\[ED = \sqrt{(s[1]*(r-1))^2+(s[2]*(\gamma-1))^2+(s[3]*(\beta-1))^2}\]
\[r = \text{Pearson Correlation Coefficient}\]
\[\beta=\mu_s / \mu_o\]
\[\gamma = \frac{CV_s}{CV_o} = \frac{\sigma_s/\mu_s}{\sigma_o/\mu_o}\]

Range: -inf < KGE (2012) < 1, does not indicate bias, larger is better.

Notes: The modified version of the KGE (2009). Kling proposed this version to avoid cross-correlation between bias and variability ratios.

Parameters:

  • simulated_array – An array of simulated data from the time series.

  • observed_array – An array of observed data from the time series.

  • s – Represents the scaling factors to be used for re-scaling the Pearson product-moment correlation coefficient (r), gamma, and Beta, respectively.

  • replace_nan – 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 – 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 – 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 – 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_all – If True, returns all of the components of the KGE metric, which are r, gamma, and beta, respectively.

Returns:

  • The Kling-Gupta (2012) efficiency value, unless the return_all parameter is True. Returns np.nan

  • if the observed mean or standard deviation is zero.

Examples

>>> import HydroErr as he
>>> 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])
>>> he.kge_2012(sim, obs)
0.9122230723456678

>>> he.kge_2012(sim, obs, return_all=True)  # Returns (r, alpha, beta, kge)
(0.9615951377405804, 0.9224843295231272, 1.0058823529411764, 0.9132923608280753)

References

  • Kling, H., Fuchs, M., & Paulin, M. (2012). Runoff conditions in the upper Danube basin under an ensemble of climate change scenarios. Journal of Hydrology, 424, 264-277.