kge

Kling-Gupta Efficiency

de.kge.calc_kge(obs, sim, r='pearson', var='std')[source]

Calculate Kling-Gupta-Efficiency (KGE).

Parameters

  • obs ((N,)array_like) – Observed time series as 1-D array

  • sim ((N,)array_like) – Simulated time series as 1-D array

  • r (str, optional) – Either Spearman correlation coefficient (‘spearman’; Pool et al. 2018) or Pearson correlation coefficient (‘pearson’; Gupta et al. 2009) can be used to describe the temporal correlation. The default is to calculate the Pearson correlation.

  • var (str, optional) – Either coefficient of variation (‘cv’; Kling et al. 2012) or standard deviation (‘std’; Gupta et al. 2009, Pool et al. 2018) to describe the gamma term. The default is to calculate the standard deviation.

Returns

eff – Kling-Gupta-Efficiency

Return type

float

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> kge.calc_kge(obs, sim)
0.683901305466148

Notes

\[ \begin{align}\begin{aligned}KGE = 1 - \sqrt{(\beta - 1)^2 + (\alpha - 1)^2 + (r - 1)^2}\\KGE = 1 - \sqrt{(\frac{\mu_{sim}}{\mu_{obs}} - 1)^2 + (\frac{\sigma_{sim}}{\sigma_{obs}} - 1)^2 + (r - 1)^2}\\KGE = 1 - \sqrt{(\beta - 1)^2 + (\gamma - 1)^2 + (r - 1)^2}\\KGE = 1 - \sqrt{(\frac{\mu_{sim}}{\mu_{obs}} - 1)^2 + (\frac{CV_{sim}}{CV_{obs}} - 1)^2 + (r - 1)^2}\end{aligned}\end{align} \]

References

Gupta, H. V., Kling, H., Yilmaz, K. K., and Martinez, G. F.: Decomposition of the mean squared error and NSE performance criteria: Implications for improving hydrological modelling, Journal of Hydrology, 377, 80-91, 10.1016/j.jhydrol.2009.08.003, 2009.

Kling, H., Fuchs, M., and Paulin, M.: Runoff conditions in the upper Danube basin under an ensemble of climate change scenarios, Journal of Hydrology, 424-425, 264-277, 10.1016/j.jhydrol.2012.01.011, 2012.

Pool, S., Vis, M., and Seibert, J.: Evaluating model performance: towards a non-parametric variant of the Kling-Gupta efficiency, Hydrological Sciences Journal, 63, 1941-1953, 10.1080/02626667.2018.1552002, 2018.

Bias term

de.kge.calc_kge_beta(obs, sim)[source]

Calculate the beta term of Kling-Gupta-Efficiency (KGE).

Parameters

  • obs ((N,)array_like) – Observed time series as 1-D array

  • sim ((N,)array_like) – Simulated time series as 1-D array

Returns

kge_beta – alpha value

Return type

float

Notes

\[\beta = \frac{\mu_{sim}}{\mu_{obs}}\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> de.calc_kge_beta(obs, sim)
1.0980392156862746

References

Gupta, H. V., Kling, H., Yilmaz, K. K., and Martinez, G. F.: Decomposition of the mean squared error and NSE performance criteria: Implications for improving hydrological modelling, Journal of Hydrology, 377, 80-91, 10.1016/j.jhydrol.2009.08.003, 2009.

Kling, H., Fuchs, M., and Paulin, M.: Runoff conditions in the upper Danube basin under an ensemble of climate change scenarios, Journal of Hydrology, 424-425, 264-277, 10.1016/j.jhydrol.2012.01.011, 2012.

Pool, S., Vis, M., and Seibert, J.: Evaluating model performance: towards a non-parametric variant of the Kling-Gupta efficiency, Hydrological Sciences Journal, 63, 1941-1953, 10.1080/02626667.2018.1552002, 2018.

Variability term

de.kge.calc_kge_alpha(obs, sim)[source]

Calculate the alpha term of the Kling-Gupta-Efficiency (KGE).

Parameters

  • obs ((N,)array_like) – Observed time series as 1-D array

  • sim ((N,)array_like) – Simulated time series

Returns

kge_alpha – alpha value

Return type

float

Notes

\[\alpha = \frac{\sigma_{sim}}{\sigma_{obs}}\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> kge.calc_kge_alpha(obs, sim)
1.2812057455166919

References

Gupta, H. V., Kling, H., Yilmaz, K. K., and Martinez, G. F.: Decomposition of the mean squared error and NSE performance criteria: Implications for improving hydrological modelling, Journal of Hydrology, 377, 80-91, 10.1016/j.jhydrol.2009.08.003, 2009.

Kling, H., Fuchs, M., and Paulin, M.: Runoff conditions in the upper Danube basin under an ensemble of climate change scenarios, Journal of Hydrology, 424-425, 264-277, 10.1016/j.jhydrol.2012.01.011, 2012.

Pool, S., Vis, M., and Seibert, J.: Evaluating model performance: towards a non-parametric variant of the Kling-Gupta efficiency, Hydrological Sciences Journal, 63, 1941-1953, 10.1080/02626667.2018.1552002, 2018.

de.kge.calc_kge_gamma(obs, sim)[source]

Calculate the gamma term of Kling-Gupta-Efficiency (KGE).

Parameters

  • obs ((N,)array_like) – Observed time series as 1-D array

  • sim ((N,)array_like) – Simulated time series as 1-D array

Returns

kge_gamma – gamma value

Return type

float

Notes

\[\gamma = \frac{CV_{sim}}{CV_{obs}}\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> kge.calc_kge_gamma(obs, sim)
1.166812375381273

References

Gupta, H. V., Kling, H., Yilmaz, K. K., and Martinez, G. F.: Decomposition of the mean squared error and NSE performance criteria: Implications for improving hydrological modelling, Journal of Hydrology, 377, 80-91, 10.1016/j.jhydrol.2009.08.003, 2009.

Kling, H., Fuchs, M., and Paulin, M.: Runoff conditions in the upper Danube basin under an ensemble of climate change scenarios, Journal of Hydrology, 424-425, 264-277, 10.1016/j.jhydrol.2012.01.011, 2012.

Pool, S., Vis, M., and Seibert, J.: Evaluating model performance: towards a non-parametric variant of the Kling-Gupta efficiency, Hydrological Sciences Journal, 63, 1941-1953, 10.1080/02626667.2018.1552002, 2018.

Correlation term

de.kge.calc_temp_cor(obs, sim, r='pearson')[source]

Calculate temporal correlation between observed and simulated time series.

Parameters

  • obs ((N,)array_like) – Observed time series as 1-D array

  • sim ((N,)array_like) – Simulated time series

  • r (str, optional) – Either Spearman correlation coefficient (‘spearman’) or Pearson correlation coefficient (‘pearson’) can be used to describe the temporalcorrelation. The default is to calculate the Pearson correlation.

Returns

temp_cor – correlation between observed and simulated time series

Return type

float

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> de.calc_temp_cor(obs, sim)
0.8940281850583509

Polar Plot

de.kge.polar_plot(obs, sim, r='pearson', var='std')[source]

Polar plot of Diagnostic efficiency (KGE) for a single evaluation.

Parameters

  • obs ((N,)array_like) – Observed time series as 1-D array

  • sim ((N,)array_like) – Simulated time series as 1-D array

  • r (str, optional) – Either Spearman correlation coefficient (‘spearman’) or Pearson correlation coefficient (‘pearson’) can be used to describe the temporal correlation. The default calculates the Pearson correlation.

  • var (str, optional) – Either coefficient of variation (‘cv’) or standard deviation (‘std’) to describe the gamma term. The default calculates the standard deviation.

Returns

fig – diagnostic polar plot

Return type

Figure

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> kge.diag_polar_plot_kge(obs, sim)