de

Diagnostic Efficiency

de.de.calc_de(obs, sim, sort=True)

Calculate Diagnostic-Efficiency (DE).

Parameters

• obs ((N,)array_like) – Observed time series as 1-D array

• sim ((N,)array_like) – Simulated time series

• sort (boolean, optional) – If True, time series are sorted by ascending order. If False, time series are not sorted. The default is to sort.

Returns

eff – Diagnostic efficiency

Return type

float

Notes

\[DE = \sqrt{\overline{B_{rel}}^2 + \vert B_{area}\vert^2 + (r - 1)^2}\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> de.calc_de(obs, sim)
0.18

Constant error term

de.de.calc_brel_mean(obs, sim, sort=True)

Calculate the arithmetic mean of the relative bias.

Parameters

• obs ((N,)array_like) – observed time series as 1-D array

• sim ((N,)array_like) – simulated time series as 1-D array

• sort (boolean, optional) – If True, time series are sorted by ascending order. If False, time series are not sorted. The default is to sort.

Returns

brel_mean – average relative bias

Return type

float

Notes

\[\overline{B_{rel}} = \frac{1}{N}\sum_{i=1}^{N} B_{rel}(i)\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> de.calc_brel_mean(obs, sim)
0.09330065359477124

Dynamic error term

de.de.calc_brel_res(obs, sim, sort=True)

Subtracting arithmetic mean of the relative bias from the relative bias.

Parameters

• obs ((N,)array_like) – observed time series as 1-D array

• sim ((N,)array_like) – simulated time series

• sort (boolean, optional) – If True, time series are sorted by ascending order. If False, time series are not sorted. The default is to sort.

Returns

brel_res – remaining relative bias

Return type

(N,)array_like

Notes

\[B_{res}(i) = B_{rel}(i) - \overline{B_{rel}}\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> de.calc_brel_res(obs, sim)
array([ 0.15669935, -0.02663399, -0.22663399,  0.10669935,  0.08316993,
   -0.09330065])

de.de.calc_bias_area(brel_res)

Calculate the integrated residual bias for the entire flow duration curve.

Parameters

brel_res ((N,)array_like) – remaining relative bias as 1-D array

Returns

b_area – bias area

Return type

float

Notes

\[\vert B_{area}\vert = \int_{0}^{1}\vert B_{res}(i)\vert di\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> b_res = de.calc_brel_res(obs, sim)
>>> de.calc_bias_area(b_res)
0.1112908496732026

See also

de.calc_brel_res

de.de.calc_bias_dir(brel_res)

Calculate the direction of the dynamic error.

Parameters

brel_res ((N,)array_like) – remaining relative bias

Returns

b_dir – direction of bias

Return type

float

Notes

\[\begin{split}B_{dir} = \begin{cases} -1 & \text{if } (B_{res-hf} > 0 & B_{lf} < 0) | (B_{res-hf} = 0 & B_{res-lf} < 0) | (B_{res-hf} > 0 & B_{res-lf} = 0) \\ 1 & \text{if } (B_{res-hf} < 0 & B_{lf} > 0) | (B_{res-hf} = 0 & B_{res-lf} > 0) | (B_{res-hf} < 0 & B_{res-lf} = 0) \\ 0 & \text{if } (B_{res-hf} > 0 & B_{lf} > 0) | (B_{res-hf} < 0 & B_{res-lf} < 0) | (B_{res-hf} = 0 & B_{res-lf} = 0) \end{cases}\end{split}\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> brel_res = de.calc_brel_res(obs, sim)
>>> de.calc_bias_dir(brel_res)
1

de.de.calc_bias_slope(b_area, b_dir)

Calculate the slope of the residual bias.

Parameters

• b_area (float) – absolute area of residual bias

• b_dir (float) – direction of bias

Returns

b_slope – slope of bias

Return type

float

Notes

\[B_{slope} = \vert B_{area}\vert \times B_{dir}\]

See also

de.calc_bias_area

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> brel_res = de.calc_brel(obs, sim)
>>> b_dir = de.calc_bias_dir(brel_res)
>>> b_area = de.calc_bias_area(b_res)
>>> de.calc_bias_slope(b_area, b_dir)
0.11

Timing error term

de.de.calc_temp_cor(obs, sim, r='pearson')

Calculate temporal correlation between observed and simulated time series.

Parameters

• obs ((N,)array_like) – Observed time series as 1-D array

• sim ((N,)array_like) – Simulated time series

• r (str, optional) – Either Spearman correlation coefficient (‘spearman’) or Pearson correlation coefficient (‘pearson’) can be used to describe the temporal correlation. The default is to calculate the Pearson correlation.

Returns

temp_cor – correlation between observed and simulated time series

Return type

float

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> de.calc_temp_cor(obs, sim)
0.89

Error contribution of high flows and low flows

de.de.calc_brel(obs, sim, sort=True)

Calculate relative bias.

Parameters

• obs ((N,)array_like) – observed time series as 1-D array

• sim ((N,)array_like) – simulated time series as 1-D array

• sort (boolean, optional) – If True, time series are sorted by ascending order. If False, time series are not sorted. The default is to sort.

Returns

brel – relative bias

Return type

(N,)array_like

Notes

\[B_{rel} = \frac{Q_{sim}(i) - Q_{obs}(i)}{Q_{obs}(i)}\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> brel = de.calc_brel(obs, sim)

de.de.calc_bias_hf(brel)

Calculate the integrated relative bias for high flows.

Parameters

brel ((N,)array_like) – relative bias as 1-D array

Returns

b_hf – absolute bias area of high flows (i.e. 0th percentile to 50th percentile)

Return type

float

Notes

\[B_{hf} = \int_{0}^{0.5}B_{rel}(i) di\]

See also

de.calc_brel

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> b_rel = de.calc_brel(obs, sim)
>>> de.calc_bias_hf(b_rel)
0.031944444444444456

de.de.calc_bias_lf(brel)

Calculate the integrated relative for low flows.

Parameters

brel ((N,)array_like) – relative bias as 1-D array

Returns

b_lf – absolute bias area of low flows (i.e. 50th percentile to 100th percentile)

Return type

float

Notes

\[B_{lf} = \int_{0.5}^{1}B_{rel}(i) di\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> b_rel = de.calc_brel(obs, sim)
>>> de.calc_bias_lf(b_rel)
0.07549019607843138

de.de.calc_bias_tot(brel)

Calculate the integrated relative bias for the entire flow duration curve.

Parameters

brel ((N,)array_like) – relative bias as 1-D array

Returns

b_tot – bias area of the entire flow domain

Return type

float

Notes

\[\vert B_{area}\vert = \int_{0}^{1}\vert B_{rel}(i)\vert di\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> b_rel = de.calc_brel(obs, sim)
>>> de.calc_bias_tot(b_rel)
0.14017973856209148

See also

de.calc_brel

de.de.calc_err_hf(b_hf, b_tot)

Calculate the error contribution of high flows.

Parameters

• b_hf (float) – absolute bias area of high flows (i.e. 0th percentile to 50th percentile)

• b_tot (float) – bias area of the entire flow domain

Returns

err_hf – contribution of high flows to model error

Return type

float

Notes

\[\epsilon_{hf} = \frac{B_{hf}}{B_{tot}}\]

See also

de.calc_bias_hf

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> b_rel = de.calc_brel(obs, sim)
>>> b_hf = de.calc_bias_hf(b_rel)
>>> b_tot = de.calc_bias_tot(b_rel)
>>> de.calc_err_hf(b_hf, b_tot)
0.2278820375335122

de.de.calc_err_lf(b_lf, b_tot)

Calculate the error contribution of low flows.

Parameters

• b_lf (float) – absolute bias area of low flows (i.e. 50th percentile to 100th percentile)

• b_tot (float) – bias area of the entire flow domain

Returns

err_lf – contribution of low flows to dynamic error

Return type

float

Notes

\[\epsilon_{lf} = \frac{B_{lf}}{B_{tot}}\]

See also

de.calc_bias_hf

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> b_rel = de.calc_brel(obs, sim)
>>> b_lf = de.calc_bias_lf(b_rel)
>>> b_tot = de.calc_bias_tot(b_rel)
>>> de.calc_err_lf(b_lf, b_tot)
0.5385243035318803

Diagnostic Polar Plot

de.de.calc_phi(brel_mean, b_slope)

Calculate trigonometric inverse tangent.

brel_meanfloat

average relative bias

b_slopefloat

slope of bias

phifloat

trigonometric inverse tangent

\[\]

arphi = arctan2(overline{B_{rel}}, B_{slope})

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> brel_mean = de.calc_brel_mean(obs, sim)
>>> brel_res = de.calc_brel(obs, sim)
>>> b_dir = de.calc_bias_dir(brel_res)
>>> b_area = de.calc_bias_area(brel_res)
>>> b_slope = de.calc_bias_slope(b_area, b_dir)
>>> de.calc_phi(brel_mean, b_slope)
1.5707963267948966

de.de.diag_polar_plot(obs, sim, sort=True, limit=0.05, extended=False)

Diagnostic polar plot of Diagnostic efficiency (DE) for a single evaluation.

Parameters

• obs ((N,)array_like) – Observed time series as 1-D array

• sim ((N,)array_like) – Simulated time series as 1-D array

• sort (boolean, optional) – If True, time series are sorted by ascending order. If False, time series are not sorted. The default is to sort.

• limit (float, optional) – Threshold for which diagnosis can be made. The default is 0.05.

• extended (boolean, optional) – If True, extended diagnostic plot is displayed. In addtion, the duration curve of B_rest is plotted besides the polar plot. The default is, that only the diagnostic polar plot is displayed.

Returns

fig – Returns a single figure if extended=False and two figures if extended=True.

Return type

Figure

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> obs = np.array([1.5, 1, 0.8, 0.85, 1.5, 2])
>>> sim = np.array([1.6, 1.3, 1, 0.8, 1.2, 2.5])
>>> de.diag_polar_plot(obs, sim)

Diagnostic Polar Plot for multiple simulations

de.de.diag_polar_plot_multi(brel_mean, temp_cor, eff_de, b_dir, phi, b_hf, b_lf, b_tot, err_hf, err_lf, a0=None, share0=None, limit=0.05, extended=False)

Diagnostic polar plot of Diagnostic efficiency (DE) for multiple evaluations.

Note that points are used rather than arrows. Displaying multiple arrows would deteriorate visual comprehension.

Parameters

• brel_mean ((N,)array_like) – relative mean bias as 1-D array

• temp_cor ((N,)array_like) – temporal correlation as 1-D array

• eff_de ((N,)array_like) – diagnostic efficiency as 1-D array

• b_dir ((N,)array_like) – direction of bias as 1-D array

• phi ((N,)array_like) – angle as 1-D array (in radians)

• b_hf ((N,)array_like) – high flow bias

• b_lf ((N,)array_like) – low flow bias

• b_tot ((N,)array_like) – absolute total relative bias

• err_hf ((N,)array_like) – contribution of high flow errors

• err_lf ((N,)array_like) – contribution of low flow errors

• a0 ((N,)array_like) – agreement of zero values

• share0 (float) – share of zero values in observations

• limit (float, optional) – Deviation of metric terms used to calculate the threshold of DE for which diagnosis is available. The default is 0.05.

• extended (boolean, optional) – If True, density plot is displayed. In addtion, the density plot is displayed besides the polar plot. The default is, that only the diagnostic polar plot is displayed.

Returns

fig – diagnostic polar plot

Return type

Figure

Notes

\[\varphi = arctan2(\overline{B_{rel}}, B_{slope})\]

Examples

Provide arrays with equal length

>>> from de import de
>>> import numpy as np
>>> brel_mean = np.array([0.1, 0.15, 0.2])
>>> temp_cor = np.array([0.9, 0.85, 0.8])
>>> eff_de = np.array([0.21, 0.24, 0.35])
>>> b_dir = np.array([1, 1, 1])
>>> phi = np.array([0.58, 0.98, 0.78)
>>> b_hf = np.array([0.2, 0.15, 0.2])
>>> b_lf = np.array([0.2, 0.05, 0.3])
>>> b_tot = np.array([0.4, 0.2, 0.5])
>>> err_hf = np.array([0.5, 0.75, 0.4])
>>> err_lf = np.array([0.5, 0.25, 0.6])
>>> de.diag_polar_plot_multi(brel_mean, temp_cor, eff_de, b_dir,
                             phi, b_hf, b_lf, b_tot, err_hf, err_lf)