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 2-dimensional container class storing numeric elements /// (e.g. xt::xtensor<double, 2>, xt::pytensor<double, 2>, /// xt::rtensor<double, 2>, etc.). /// /// XB3: Any 3-dimensional container class storing boolean elements /// (e.g. xt::xtensor<bool, 3>, xt::pytensor<bool, 3>, /// xt::rtensor<bool, 3>, etc.). /// /// XS2: Any 2-dimensional 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. /// /// .. seealso:: Deterministic metrics /// /// q_thr: XD2, optional /// Streamflow exceedance threshold(s). If provided, events* must /// also be provided. /// shape: (series, thresholds) /// /// events: std::string, optional /// The type of streamflow events to consider for threshold /// exceedance-based 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*. /// /// .. seealso:: Transformation /// /// 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 the whole streamflow time series /// (where True/False is used for the time steps to include/discard in /// the subset). /// shape: (series, subsets, time) /// /// .. seealso:: Temporal masking /// /// 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) /// /// .. seealso:: Conditional masking /// /// 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. /// /// .. seealso:: Bootstrapping /// /// 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 8601-1:2019 standard, i.e. “YYYY-MM-DD hh:mm:ss” (e.g. the /// 21st of May 2007 at 4 in the afternoon is “2007-05-21 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. /// /// .. seealso:: Diagnostics /// /// :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: /// /// .. code-block:: c++ /// /// #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”}); /// /// .. code-block:: c++ /// /// evalhyd::evald(obs, prd, {“NSE”}, “sqrt”); /// /// .. code-block:: c++ /// /// evalhyd::evald(obs, prd, {“NSE”}, “pow”, 0.2); /// /// .. code-block:: c++ /// /// evalhyd::evald(obs, prd, {“NSE”}, “log”, 1, 0.05); /// /// .. code-block:: c++ /// /// xt::xtensor<double, 3> msk = {{{ 1, 1, 0, 1, 0 }}}; /// /// evalhyd::evald(obs, prd, {“NSE”}, “none”, 1, -9, msk); /// ///