From 02064b8bb6769e50014d3c85396652f5fa4b8334 Mon Sep 17 00:00:00 2001 From: Thibault Hallouin <thibault.hallouin@inrae.fr> Date: Mon, 1 Aug 2022 10:36:20 +0200 Subject: [PATCH] add docstrings for deterministic elements/metrics --- src/determinist/evaluator.hpp | 167 +++++++++++++++++++++++++++++++--- 1 file changed, 154 insertions(+), 13 deletions(-) diff --git a/src/determinist/evaluator.hpp b/src/determinist/evaluator.hpp index 7af6357..23a0b88 100644 --- a/src/determinist/evaluator.hpp +++ b/src/determinist/evaluator.hpp @@ -60,36 +60,108 @@ namespace evalhyd void calc_KGEPRIME(); }; + // Compute the mean of the observations. + // + // \require q_obs: + // Streamflow observations. + // shape: ({1, ...}, time) + // \assign mean_obs: + // Mean observed streamflow. + // shape: ({1, ...}, 1) template <class A> void Evaluator<A>::calc_mean_obs() { mean_obs = xt::mean(q_obs, -1, xt::keep_dims); } + // Compute the mean of the predictions. + // + // \require q_prd: + // Streamflow predictions. + // shape: ({1+, ...}, time) + // \assign mean_prd: + // Mean predicted streamflow. + // shape: ({1+, ...}, 1) template <class A> void Evaluator<A>::calc_mean_prd() { mean_prd = xt::mean(q_prd, -1, xt::keep_dims); } + // Compute the quadratic error between observations and predictions. + // + // \require q_obs: + // Streamflow observations. + // shape: ({1, ...}, time) + // \require q_prd: + // Streamflow predictions. + // shape: ({1+, ...}, time) + // \assign quad_err: + // Quadratic errors between observations and predictions. + // shape: ({1+, ...}, time) template <class A> void Evaluator<A>::calc_quad_err() { quad_err = xt::square(q_obs - q_prd); } + // Compute the quadratic error between observations and mean observation. + // + // \require q_obs: + // Streamflow observations. + // shape: ({1, ...}, time) + // \require mean_obs: + // Mean observed streamflow. + // shape: ({1, ...}, 1) + // \assign quad_obs: + // Quadratic errors between observations and mean observation. + // shape: ({1, ...}, time) template <class A> void Evaluator<A>::calc_quad_obs() { quad_obs = xt::square(q_obs - mean_obs); } + // Compute the quadratic error between predictions and mean prediction. + // + // \require q_prd: + // Streamflow predictions. + // shape: ({1+, ...}, time) + // \require mean_prd: + // Mean predicted streamflow. + // shape: ({1+, ...}, 1) + // \assign quad_prd: + // Quadratic errors between predictions and mean prediction. + // shape: ({1+, ...}, time) template <class A> void Evaluator<A>::calc_quad_prd() { quad_prd = xt::square(q_prd - mean_prd); } + // Compute the Pearson correlation coefficient. + // + // \require q_obs: + // Streamflow observations. + // shape: ({1, ...}, time) + // \require mean_obs: + // Mean observed streamflow. + // shape: ({1, ...}, 1) + // \require q_prd: + // Streamflow predictions. + // shape: ({1+, ...}, time) + // \require mean_prd: + // Mean predicted streamflow. + // shape: ({1+, ...}, 1) + // \require quad_obs: + // Quadratic errors between observations and mean observation. + // shape: ({1+, ...}, time) + // \require quad_prd: + // Quadratic errors between predictions and mean prediction. + // shape: ({1+, ...}, time) + // \assign r_pearson: + // Pearson correlation coefficients. + // shape: ({1+, ...}, time) template <class A> void Evaluator<A>::calc_r_pearson() { @@ -106,6 +178,17 @@ namespace evalhyd r_pearson = r_num / r_den; } + // Compute the bias. + // + // \require q_obs: + // Streamflow observations. + // shape: ({1, ...}, time) + // \require q_prd: + // Streamflow predictions. + // shape: ({1+, ...}, time) + // \assign bias: + // Biases. + // shape: ({1+, ...}, 1) template <class A> void Evaluator<A>::calc_bias() { @@ -114,6 +197,14 @@ namespace evalhyd / xt::sum(q_obs, -1, xt::keep_dims); } + // Compute the root-mean-square error (RMSE). + // + // \require quad_err: + // Quadratic errors between observations and predictions. + // shape: ({1+, ...}, time) + // \assign RMSE: + // Root-mean-square errors. + // shape: ({1+, ...}, 1) template <class A> void Evaluator<A>::calc_RMSE() { @@ -124,19 +215,19 @@ namespace evalhyd // Compute the Nash-Sutcliffe Efficiency (NSE). // // If multi-dimensional arrays are provided, the arrays of predictions - // and observations must feature the same number of dimensions, they must - // be broadcastable, and their temporal dimensions must be along their - // last axis. + // and observations must feature the same number of dimensions, they + // must be broadcastable, and their temporal dimensions must be along + // their last axis. // - // \require q_obs: - // Array of streamflow observations. - // shape: (1, time) - // \require q_prd: - // Array of streamflow predictions. - // shape: (..., time) - // \assign nse: - // Array of computed Nash-Sutcliffe efficiencies. - // shape: (..., 1) + // \require quad_err: + // Quadratic errors between observations and predictions. + // shape: ({1+, ...}, time) + // \require quad_obs: + // Quadratic errors between observations and mean observation. + // shape: ({1, ...}, time) + // \assign NSE: + // Nash-Sutcliffe efficiencies. + // shape: ({1+, ...}, 1) template <class A> void Evaluator<A>::calc_NSE() { @@ -148,6 +239,28 @@ namespace evalhyd NSE = 1 - (f_num / f_den); } + // Compute the Kling-Gupta Efficiency (KGE). + // + // If multi-dimensional arrays are provided, the arrays of predictions + // and observations must feature the same number of dimensions, they + // must be broadcastable, and their temporal dimensions must be along + // their last axis. + // + // \require q_obs: + // Streamflow observations. + // shape: ({1, ...}, time) + // \require q_prd: + // Streamflow predictions. + // shape: ({1+, ...}, time) + // \require r_pearson: + // Pearson correlation coefficients. + // shape: ({1+, ...}, time) + // \require bias: + // Biases. + // shape: ({1+, ...}, 1) + // \assign KGE: + // Kling-Gupta efficiencies. + // shape: ({1+, ...}, 1) template <class A> void Evaluator<A>::calc_KGE() { @@ -164,10 +277,38 @@ namespace evalhyd ); } + // Compute the modified Kling-Gupta Efficiency (KGEPRIME). + // + // If multi-dimensional arrays are provided, the arrays of predictions + // and observations must feature the same number of dimensions, they + // must be broadcastable, and their temporal dimensions must be along + // their last axis. + // + // \require q_obs: + // Streamflow observations. + // shape: ({1, ...}, time) + // \require mean_obs: + // Mean observed streamflow. + // shape: ({1, ...}, 1) + // \require q_prd: + // Streamflow predictions. + // shape: ({1+, ...}, time) + // \require mean_prd: + // Mean predicted streamflow. + // shape: ({1+, ...}, 1) + // \require r_pearson: + // Pearson correlation coefficients. + // shape: ({1+, ...}, time) + // \require bias: + // Biases. + // shape: ({1+, ...}, 1) + // \assign KGEPRIME: + // Modified Kling-Gupta efficiencies. + // shape: ({1+, ...}, 1) template <class A> void Evaluator<A>::calc_KGEPRIME() { - // calculate error in spread of flow $alpha$ + // calculate error in spread of flow $gamma$ auto gamma = (xt::stddev(q_prd, {q_prd.dimension() - 1}, xt::keep_dims) / mean_prd) / (xt::stddev(q_obs, {q_obs.dimension() - 1}, xt::keep_dims) / mean_obs); -- GitLab