evalhyd::evalp

template<class XD2, class XD4, class XB4 = xt::xtensor<bool, 4>, class XS2 = xt::xtensor<std::array<char, 32>, 2>>
std::vector<xt::xarray<double>> evalhyd::evalp(const xt::xexpression<XD2> &q_obs, const xt::xexpression<XD4> &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>(), const std::vector<double> &c_lvl = {}, const std::vector<double> &q_lvl = {}, const xt::xexpression<XB4> &t_msk = XB4({}), 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 probabilistic 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.). /// /// XD4: Any 4-dimensional container class storing numeric elements /// (e.g. xt::xtensor<double, 4>, xt::pytensor<double, 4>, /// xt::rtensor<double, 4>, etc.). /// /// XB4: Any 4-dimensional container class storing boolean elements /// (e.g. xt::xtensor<bool, 4>, xt::pytensor<bool, 4>, /// xt::rtensor<bool, 4>, 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: (sites, time) /// /// q_prd: XD4 /// 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: (sites, lead times, members, time) or /// (sites, lead times, quantiles, time) if q_lvl* is provided /// /// metrics: std::vector<std::string> /// The sequence of evaluation metrics to be computed. /// /// .. seealso:: Probabilistic metrics /// /// 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 /// 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. /// /// c_lvl: std::vector<double>, optional /// Confidence level(s). /// /// q_lvl: std::vector<double>, optional /// Quantile level(s). /// /// t_msk: XB4, optional /// Mask(s) used to generate temporal subsets of the whole streamflow /// time series (where True/False is used for the time steps to /// include/discard in a given subset). If not provided and neither /// is m_cdt*, no subset is performed and only one set of metrics is /// returned corresponding to the whole time series. If provided, as /// many sets of metrics are returned as they are masks provided. /// shape: (sites, lead times, 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/predicted 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 and only one set of metrics is /// returned corresponding to the whole time series. /// shape: (sites, 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,)<(sites, lead times, subsets, samples, /// {quantiles,} {thresholds,} {components,} {ranks,} {intervals})> /// /// :Examples: /// /// .. code-block:: c++ /// /// #include <xtensor/xtensor.hpp> /// #include <evalhyd/evalp.hpp> /// /// xt::xtensor<double, 2> obs = {{ 4.7, 4.3, 5.5, 2.7, 4.1 }}; /// xt::xtensor<double, 4> 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 }}}}; /// xt::xtensor<double, 2> thr = {{ 4.7, 4.3, 5.5, 2.7, 4.1 }}; /// /// evalhyd::evalp(obs, prd, {“BS”}, thr); /// /// .. code-block:: c++ /// /// xt::xtensor<bool, 3> msk = {{{ false, true, true, false, true }}}; /// /// evalhyd::evalp(obs, prd, {“BS”}, thr, msk); /// /// .. code-block:: c++ /// /// evalhyd::evalp(obs, prd, {“CRPS_FROM_QS”}); /// ///