Add COE, COP, and volumetric efficiency to metrics

[jarq6c]

This PR implements a generic mean_error_skill_score method and adds three new metrics: coefficient_of_persistence, coefficient_of_extrapolation, and volumetric_efficiency. These three metrics are computed in a fashion similar to the Nash-Sutcliffe Model Efficiency, except instead of using the mean baseline they use a persistence, an extrapolation, and zero baseline. A "persistence" baseline uses the observed value given a lag. An extrapolation baseline uses the last two observed values to extrapolate a linear approximation.

Added @hellkite500 and @aaraney may be interested.

Additions

• mean_error
• mean_squared_error
• root_mean_squared_error
• mean_error_skill_score
• coefficient_of_persistence
• coefficient_of_extrapolation
• volumetric_efficiency

Removals

• None

Changes

• nash_sutcliffe_efficiency is now based on the generic mean_error_skill_score
• Options were added to change the power/exponent of the nash_sutcliffe_efficiency
• Expanded docstrings with more helpful descriptions of metrics

Testing

1. Passed existing tests with updates.
2. New methods tested.

Notes

• Citations and equations may not play well with documentation engine.
• Closes hydrotools.metrics Add coefficient of persistence and coefficient of extrapolation #147
• Requested @christophertubbs given background with similar metrics.

Todos

• None

Checklist

• PR has an informative and human-readable title
• PR is well outlined and documented. See #12 for an example
• Changes are limited to a single goal (no scope creep)
• Code can be automatically merged (no conflicts)
• Code follows project standards (see CONTRIBUTING.md)
• Passes all existing automated tests
• Any change in functionality is tested
• New functions are documented (with a description, list of inputs, and expected output) using numpy docstring formatting
• Placeholder code is flagged / future todos are captured in comments
• Reviewers requested with the Reviewers tool ➡️

[christophertubbs]

The only 'problems' I found were stylistic preferences, which is purely subjective.

I would like to eventually see quick documentation on what the metrics actually measure, instead of just directions to the papers, but that's just because I'm not a scientific user.

[jarq6c]

The only 'problems' I found were stylistic preferences, which is purely subjective.

I would like to eventually see quick documentation on what the metrics actually measure, instead of just directions to the papers, but that's just because I'm not a scientific user.

Thanks for the feedback! I decided to significantly expand the descriptions of all the metrics. Hopefully these new descriptions will help users unfamiliar with some of these.

[jarq6c]

Published: https://pypi.org/project/hydrotools.metrics/1.3.3/