de¶
Diagnostic Efficiency¶
-
de.de.calc_de(obs, sim, sort=True)[source]¶ 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: 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)[source]¶ 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: 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Calculate the slope of the residual bias.
Parameters: Returns: b_slope – slope of bias
Return type: 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')[source]¶ 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: 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Calculate the error contribution of high flows.
Parameters: Returns: err_hf – contribution of high flows to model error
Return type: 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)[source]¶ Calculate the error contribution of low flows.
Parameters: Returns: err_lf – contribution of low flows to dynamic error
Return type: 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)[source]¶ Calculate trigonometric inverse tangent.
- brel_mean : float
- average relative bias
- b_slope : float
- slope of bias
- phi : float
- 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, l=0.05, extended=False)[source]¶ 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.
- l (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, l=0.05, extended=False)[source]¶ 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
- l (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)
