Add Kling-Gupta Efficiency #172
Conversation
| @@ -1 +1 @@ | |||
| __version__ = "1.1.3" | |||
| __version__ = "1.2.3" | |||
There was a problem hiding this comment.
shouldnt the version bump be to 1.2.0?
Thanks for the review! |
| a_scale: float = 1.0, | ||
| b_scale: float = 1.0 | ||
| ) -> float: | ||
| """Compute the Kling-Gupta model efficiency coefficient (KGE). |
There was a problem hiding this comment.
Should any software assumptions be stated here? Something like: "This function assumes two sorted arrays of equal length." I would also want to add something that conveys that y_true[0] "lines up with" y_pred[0]. I cant find an appropriate phrase though.
There was a problem hiding this comment.
It might be worth mentioning what the shape of the array's are assumed to be. i.e. this method should only be applied to 1 dimensional arrays.
There was a problem hiding this comment.
This made this realize, the docstring description for these doesn't make any sense. I copied these from sklearn and forgot to update them for this case.
There was a problem hiding this comment.
Updated docstrings and added new input array validation methods for NSE and KGE. These could certainly be way more rigorous and exhaustive, but it's a start.
There was a problem hiding this comment.
Note: the parameters descriptions explicitly state the expected shape ((n_samples,)).
|
|
||
| References | ||
| ---------- | ||
| Gupta, H. V., Kling, H., Yilmaz, K. K., & Martinez, G. F. (2009). Decomposition of |
There was a problem hiding this comment.
There was a problem hiding this comment.
on a side note, it would be "cool" if you could get the citation for the paper in bibtex or some other format. I am thinking a decorator that wraps each metric function and contains the bibtex formatted citation. You could access it like:
from hydrotools.metrics import metrics
print(metrics.kling_gupta_efficiency.citation(format="bibtex"))
@article{Gupta2009,
doi = {10.1016/j.jhydrol.2009.08.003},
url = {https://doi.org/10.1016/j.jhydrol.2009.08.003},
year = {2009},
month = oct,
publisher = {Elsevier {BV}},
volume = {377},
number = {1-2},
pages = {80--91},
author = {Hoshin V. Gupta and Harald Kling and Koray K. Yilmaz and Guillermo F. Martinez},
title = {Decomposition of the mean squared error and {NSE} performance criteria: Implications for improving hydrological modelling},
journal = {Journal of Hydrology}
}There was a problem hiding this comment.
That would be cool. Let's discuss that at next hydrotools meeting!
| for x in arrays: | ||
| if len(np.array(x).shape) != 1: | ||
| message = "all input arrays must be 1-dimensional" | ||
| raise ValueError(message) |
There was a problem hiding this comment.
In both these validation functions, the exception may be too generic. It would be quite valuable to a developer if your messaging could indicate which array's fail validation -- or at the very least indicate what the differences are...
There was a problem hiding this comment.
I'll note that these general _validation functions don't need to have this functionality, you can customize your ValueError exception so you can handle that higher up:
try:
validate(...)
catch ShapeValueError:
throw ValueError("Shape of y_true != y_pred: y_pred shape is {}, y_true shape is {}".format(y_pred.shape, y_true.shape)There was a problem hiding this comment.
Updated with new NonVectorError and InconsistentShapesError derived from Exception that report the offending arrays.
This PR adds the Kling-Gupta Efficiency hydrological model calibration/evaluation metric.
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.
Additions
hydrotools.metrics.metrics.kling_gupta_efficiencyhydrotools.metrics._validationRemovals
Changes
Testing
test_kling_gupta_efficiencytotest_metricstest_validationto check input validation methodsNotes
Todos
Checklist