add docstrings for deterministic elements/metrics

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);