kge_2009

HydroErr.HydroErr.kge_2009(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 (2009).

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

Range: -inf < KGE (2009) < 1, larger is better.

Notes: Gupta et al. (2009) created this metric to demonstrate the relative importance of the three components of the NSE, which are correlation, bias and variability. This was done with hydrologic modeling as the context. This metric is meant to address issues with the NSE.

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), Alpha, 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, alpha, and beta, respectively.

Returns:

  • The Kling-Gupta (2009) 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_2009(sim, obs)
0.912223072345668

>>> he.kge_2009(sim, obs, return_all=True)  # Returns (r, alpha, beta, kge)
(0.9615951377405804, 0.927910707932087, 1.0058823529411764, 0.9181073779138655)

References

  • Gupta, H. V., Kling, H., Yilmaz, K. K., & Martinez, G. F. (2009). Decomposition of the mean squared error and NSE performance criteria: Implications for improving hydrological modelling. Journal of Hydrology, 377(1-2), 80-91.