Calculate the modified Kling-Gupta Efficiency (Kling et al., 2012) on log-transformed data as proposed in Mai (2023), namely \(KGE_{log}\), \(KGE_{logQ_{low}}\) and \(KGE_{logQ_{hi}}\). All are dimensionless (from \(-\infty\) to 1).
This metric is recommended for emphasising low flows. By transforming the discharge data logarithmically, it gives more weight to smaller flow values, which is important for understanding drought conditions or baseflow behaviour (see Mai 2023; Mizukami et al., 2019).
Usage
kgelog(data, ...)
# S3 method for class 'data.frame'
kgelog(data, truth, estimate, na_rm = TRUE, ...)
kgelog_vec(truth, estimate, na_rm = TRUE, ...)
kgelog_low(data, ...)
# S3 method for class 'data.frame'
kgelog_low(data, truth, estimate, na_rm = TRUE, ...)
kgelog_low_vec(truth, estimate, na_rm = TRUE, ...)
kgelog_hi(data, ...)
# S3 method for class 'data.frame'
kgelog_hi(data, truth, estimate, na_rm = TRUE, ...)
kgelog_hi_vec(truth, estimate, na_rm = TRUE, ...)Arguments
- data
A
data.framecontaining the columns specified by thetruthandestimatearguments.- ...
Not currently used.
- truth
The column identifier for the true results (that is
numeric). This should be an unquoted column name although this argument is passed by expression and supports quasiquotation (you can unquote column names). For_vec()functions, anumericvector.- estimate
The column identifier for the predicted results (that is also
numeric). As withtruththis can be specified different ways but the primary method is to use an unquoted variable name. For_vec()functions, anumericvector.- na_rm
A
logicalvalue indicating whetherNAvalues should be stripped before the computation proceeds.
Value
A tibble with columns .metric, .estimator,
and .estimate and 1 row of values.
For grouped data frames, the number of rows returned will be the same as the number of groups.
For kgelog_vec(), a single numeric value (or NA).
Details
While the kgelog() function proposes the log-transformed version of the
kge2012, functions such as kgelog_low() and kgelog_hi()
also perform data subsetting according to conditions specified in
Mai (2023).
The metrics kgelog_low() and kgelog_hi() are then the \(KGE'\)
of the log-transformed observed and simulated streamflow considering
only low-flow and high-flow time steps, respectively.
A data point is considered in the derivation of kgelog_low() if the
observed streamflow (\(\text{obs}\)) for that time step satisfies
the following conditions:
$$ 0.0 < \text{obs} \le min(\text{obs}) + 0.05 \times (max(\text{obs}) - min(\text{obs})) $$
A data point is considered in the derivation of kgelog_hi() if the
observed streamflow (\(\text{obs}\)) for that time step satisfies
the following conditions:
$$ \text{obs} > min(\text{obs}) + 0.05 \times (max(\text{obs}) - min(\text{obs})) $$
Note
Please note that the decision if a time step is a low-flow or high-flow time step is solely based on the observations which means it is always the same time steps for a given basin and time period while being independent of the simulation (Mai, 2023).
Unlike the Nash–Sutcliffe Efficiency (nse), the KGE does not have an inherent benchmark such as "mean flow", and \(KGE' = 0\) does not correspond to a baseline performance. Therefore, \(KGE_{log}\) values should not be interpreted as "good" or "bad" based solely on their sign or magnitude. Instead, users are encouraged to examine the individual components (\(r\), \(\beta\), \(\gamma\)) to understand the nature of model performance and consider defining explicit benchmarks based on the study context.
For further discussion, see Knoben et al. (2019), who caution against directly translating NSE-based interpretation thresholds to KGE.
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–425, 264–277. doi:10.1016/j.jhydrol.2012.01.011
Knoben, W. J. M., Freer, J. E., & Woods, R. A. (2019). Technical note: Inherent benchmark or not? Comparing Nash–Sutcliffe and Kling–Gupta efficiency scores. Hydrology and Earth System Sciences, 23, 4323–4331. doi:10.5194/hess-23-4323-2019
Mai, J. (2023). Ten strategies towards successful calibration of environmental models. Journal of Hydrology, 620, 129414. doi:10.1016/j.jhydrol.2023.129414
Mizukami, N., Rakovec, O., Newman, A. J., Clark, M. P., Wood, A. W., Gupta, H. V., & Kumar, R. (2019). On the choice of calibration metrics for “high-flow” estimation using hydrologic models. Hydrology and Earth System Sciences, 23(6), 2601–2614. doi:10.5194/hess-23-2601-2019