Add Kling-Gupta Efficiency and differentiate between modified an unmodified

[martinvonk]

Short Description

See title.

Also deprecates kge_2012 in version 2.0

Checklist before PR can be merged:

• closes issue [ENHANCEMENT] Kling-Gupta Efficiency improved usecase #606
• is documented
• Format code with Black formatting
• type hints for functions and methods
• tests added / passed

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ +0.63% (target: +0.00%)	✅ 96.49%

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (92c7b8a)	6031	4511	74.80%
Head commit (a736028)	6108 (+77)	4607 (+96)	75.43% (+0.63%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#700)	57	55	96.49%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

_{You may notice some variations in coverage metrics with the latest Coverage engine update. For more details, visit the documentation}

[raoulcollenteur]

Add references, otherwise fine with me

[raoulcollenteur]

Hi @martinvonk, can you add the reference? Otherwise I think this is fine, i like the change to kge.

Cheers,
Raoul

[martinvonk]

Reference was in the notes but is now also present in the parametes list:

modified: bool, optional
    Use the modified KGE as proposed by :cite:t:`kling_runoff_2012`.
    According to the article this ensures that the bias and variability
    ratios are not cross-correlated, which otherwise may occur when inputs
    are biased.

Notes
-----
The (weighted) Kling-Gupta Efficiency :cite:t:`kling_runoff_2012` is
computed as follows:

.. math:: \\text{KGE} = 1 - \\sqrt{(r-1)^2 + (\\beta-1)^2 - (\\gamma-1)^2}

where :math:`\\beta = \\bar{x} / \\bar{y}` and :math:`\\gamma =
\\frac{\\bar{\\sigma}_x}{\\bar{\\sigma}_y}}`. If modified equals True,
:math:`\\gamma = \\frac{\\bar{\\sigma}_x / \\bar{x}}{\\bar{\\sigma}_y /
\\bar{y}}`. If weighted equals True, the weighted mean, variance and
pearson correlation are used.

[martinvonk]

Do we have a list somewhere where everything is listed which we intend to deprecate for Pastas 2.0?