evalhyd::evald

template<class XD2, class XB3 = xt::xtensor<bool, 3>, class XS2 = xt::xtensor<std::array<char, 32>, 2>>
std::vector<xt::xarray<double>> evalhyd::evald(const xt::xexpression<XD2> &q_obs, const xt::xexpression<XD2> &q_prd, const std::vector<std::string> &metrics, const xt::xexpression<XD2> &q_thr = XD2({}), xtl::xoptional<const std::string, bool> events = xtl::missing<const std::string>(), xtl::xoptional<const std::string, bool> transform = xtl::missing<const std::string>(), xtl::xoptional<double, bool> exponent = xtl::missing<double>(), xtl::xoptional<double, bool> epsilon = xtl::missing<double>(), const xt::xexpression<XB3> &t_msk = XB3({}), const xt::xexpression<XS2> &m_cdt = XS2({}), xtl::xoptional<const std::unordered_map<std::string, int>, bool> bootstrap = xtl::missing<const std::unordered_map<std::string, int>>(), const std::vector<std::string> &dts = {}, xtl::xoptional<const int, bool> seed = xtl::missing<const int>(), xtl::xoptional<const std::vector<std::string>, bool> diagnostics = xtl::missing<const std::vector<std::string>>()) Function to evaluate deterministic streamflow predictions.
 Template Parameters
 XD2: Any 2dimensional container class storing numeric elements
(e.g.
xt::xtensor<double, 2>
,xt::pytensor<double, 2>
,xt::rtensor<double, 2>
, etc.). XB3: Any 3dimensional container class storing boolean elements
(e.g.
xt::xtensor<bool, 3>
,xt::pytensor<bool, 3>
,xt::rtensor<bool, 3>
, etc.). XS2: Any 2dimensional container class storing string elements
(e.g.
xt::xtensor<std::array<char, 32>, 2>
,xt::pytensor<std::array<char, 32>, 2>
,xt::rtensor<std::array<char, 32>, 2>
, etc.).
 Parameters
 q_obs:
XD2
Streamflow observations. Time steps with missing observations must be assigned
NAN
values. Those time steps will be ignored both in the observations and the predictions before the metrics are computed. shape: (1, time) q_prd:
XD2
Streamflow predictions. Time steps with missing predictions must be assigned
NAN
values. Those time steps will be ignored both in the observations and the predictions before the metrics are computed. shape: (series, time) metrics:
std::vector<std::string>
The sequence of evaluation metrics to be computed.
See also
 q_thr:
XD2
, optional Streamflow exceedance threshold(s). If provided, events must also be provided. shape: (sites, thresholds)
 events:
std::string
, optional The type of streamflow events to consider for threshold exceedancebased metrics. It can either be set as “high” when flooding conditions/high flow events are evaluated (i.e. event occurring when streamflow goes above threshold) or as “low” when drought conditions/low flow events are evaluated (i.e. event occurring when streamflow goes below threshold). It must be provided if q_thr is provided.
 transform:
std::string
, optional The transformation to apply to both streamflow observations and predictions prior to the calculation of the metrics.
See also
 exponent:
double
, optional The value of the exponent n to use when the transform is the power function. If not provided, the streamflow observations and predictions remain untransformed.
 epsilon:
double
, optional The value of the small constant ε to add to both the streamflow observations and predictions prior to the calculation of the metrics when the transform is the reciprocal function, the natural logarithm, or the power function with a negative exponent (since none are defined for 0). If not provided, one hundredth of the mean of the streamflow observations is used as value for epsilon, as recommended by Pushpalatha et al. (2012).
 t_msk:
XB3
, optional Mask used to temporally subset of the whole streamflow time series (where True/False is used for the time steps to include/discard in the subset). shape: (series, subsets, time)
See also
 m_cdt:
XS2
, optional Masking conditions to use to generate temporal subsets. Each condition consists in a string and can be specified on observed streamflow values/statistics (mean, median, quantile), or on time indices. If provided in combination with t_msk, the latter takes precedence. If not provided and neither is t_msk, no subset is performed. shape: (series, subsets)
See also
 bootstrap:
std::unordered_map<std::string, int>
, optional Parameters for the bootstrapping method used to estimate the sampling uncertainty in the evaluation of the predictions. The parameters are: ‘n_samples’ the number of random samples, ‘len_sample’ the length of one sample in number of years, and ‘summary’ the statistics to return to characterise the sampling distribution). If not provided, no bootstrapping is performed. If provided, dts must also be provided.
See also
 dts:
std::vector<std::string>
, optional Datetimes. The corresponding date and time for the temporal dimension of the streamflow observations and predictions. The date and time must be specified in a string following the ISO 86011:2019 standard, i.e. “YYYYMMDD hh:mm:ss” (e.g. the 21st of May 2007 at 4 in the afternoon is “20070521 16:00:00”). The time series must feature complete years. Only minute, hourly, and daily time steps are supported. If provided, it is only used if bootstrap is also provided.
 seed:
int
, optional A value for the seed used by random generators. This parameter guarantees the reproducibility of the metric values between calls.
 diagnostics:
std::vector<std::string>
, optional The sequence of evaluation diagnostics to be computed.
See also
 q_obs:
 Returns
std::vector<xt::xarray<double>>
The sequence of evaluation metrics computed in the same order as given in metrics, followed by the sequence of evaluation diagnostics computed in the same order as given in diagnostics. shape: (metrics+diagnostics,)<(series, subsets, samples, {components})>
 Examples
#include <xtensor/xtensor.hpp> #include <evalhyd/evald.hpp> xt::xtensor<double, 2> obs = {{ 4.7, 4.3, 5.5, 2.7, 4.1 }}; xt::xtensor<double, 2> prd = {{ 5.3, 4.2, 5.7, 2.3, 3.1 }, { 4.3, 4.2, 4.7, 4.3, 3.3 }, { 5.3, 5.2, 5.7, 2.3, 3.9 }}; evalhyd::evald(obs, prd, {"NSE"});
evalhyd::evald(obs, prd, {"NSE"}, "sqrt");
evalhyd::evald(obs, prd, {"NSE"}, "pow", 0.2);
evalhyd::evald(obs, prd, {"NSE"}, "log", 1, 0.05);
xt::xtensor<double, 3> msk = {{{ 1, 1, 0, 1, 0 }}}; evalhyd::evald(obs, prd, {"NSE"}, "none", 1, 9, msk);