Add Kling-Gupta Efficiency

python/metrics/src/hydrotools/metrics/_version.py

@@ -1 +1 @@
-__version__ = "1.1.3"
+__version__ = "1.2.0"

python/metrics/src/hydrotools/metrics/metrics.py

@@ -22,6 +22,7 @@
  - equitable_threat_score
  - mean_squared_error
  - nash_sutcliffe_efficiency
+ - kling_gupta_efficiency
 
 """
 
@@ -66,7 +67,7 @@ def nash_sutcliffe_efficiency(
     log: bool = False,
     normalized: bool = False
     ) -> float:
-    """Compute the Nash–Sutcliffe model efficiency coefficient (NSE), also called the 
+    """Compute the Nash-Sutcliffe model efficiency coefficient (NSE), also called the 
     mean squared error skill score or the R^2 (coefficient of determination) regression score.
 
     Parameters
@@ -112,6 +113,62 @@ def nash_sutcliffe_efficiency(
         return 1.0 / (1.0 + numerator/denominator)
     return 1.0 - numerator/denominator
 
+def kling_gupta_efficiency(
+    y_true: npt.ArrayLike,
+    y_pred: npt.ArrayLike,
+    r_scale: float = 1.0,
+    a_scale: float = 1.0,
+    b_scale: float = 1.0
+    ) -> float:
+    """Compute the Kling-Gupta model efficiency coefficient (KGE).
+
+    Parameters
+    ----------
+    y_true: array-like of shape (n_samples,) or (n_samples, n_outputs)
+        Ground truth (correct) target values, also called observations, measurements, or observed values.
+    y_pred: pandas.Series, required
+        Estimated target values, also called simulations or modeled values.
+    r_scale: float, optional, default 1.0
+        Linear correlation (r) scaling factor. Used to re-scale the Euclidean space by 
+        emphasizing different KGE components.
+    a_scale: float, optional, default 1.0
+        Relative variability (alpha) scaling factor. Used to re-scale the Euclidean space by 
+        emphasizing different KGE components.
+    b_scale: float, optional, default 1.0
+        Relative mean (beta) scaling factor. Used to re-scale the Euclidean space by 
+        emphasizing different KGE components.
+
+    Returns
+    -------
+    score: float
+        Kling-Gupta efficiency.
+
+    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.
+
+    """
+    # Pearson correlation coefficient
+    r = np.corrcoef(y_pred, y_true)[0,1]
+
+    # Relative variability
+    a = np.std(y_pred) / np.std(y_true)
+
+    # Relative mean
+    b = np.mean(y_pred) / np.mean(y_true)
+
+    # Scaled Euclidean distance
+    EDs = np.sqrt(
+        (r_scale * (r - 1.0)) ** 2.0 + 
+        (a_scale * (a - 1.0)) ** 2.0 + 
+        (b_scale * (b - 1.0)) ** 2.0
+        )
+
+    # Return KGE
+    return 1.0 - EDs
+
 def compute_contingency_table(
     observed: pd.Series,
     simulated: pd.Series,

python/metrics/tests/test_metrics.py

@@ -316,4 +316,30 @@ def test_convert_mapping_values():
     converted = metrics.convert_mapping_values(char_series)
 
     assert converted.dtype == np.float64
-
+
+def test_kling_gupta_efficiency():
+    # Default (inverse case)
+    KGE = metrics.kling_gupta_efficiency(y_true, y_pred)
+    expected = -1.0
+    assert np.isclose(KGE, expected)
+
+    # Half-scale
+    KGE = metrics.kling_gupta_efficiency(y_true, np.array(y_true) * 0.5)
+    expected = (1.0 - np.sqrt(0.5))
+    assert np.isclose(KGE, expected)
+
+    # Double-scale
+    KGE = metrics.kling_gupta_efficiency(y_true, np.array(y_true) * 2.0)
+    expected = (1.0 - np.sqrt(2.0))
+    assert np.isclose(KGE, expected)
+
+    # Identity
+    KGE = metrics.kling_gupta_efficiency(y_true, np.array(y_true) * 1.0)
+    expected = 1.0
+    assert np.isclose(KGE, expected)
+
+    # Scaling parameters
+    KGE = metrics.kling_gupta_efficiency(y_true, np.array(y_true) * 0.25,
+        r_scale=0.5, a_scale=0.25, b_scale=0.25)
+    expected = (1.0 - np.sqrt(9.0/128.0))
+    assert np.isclose(KGE, expected)