improved loo_R2 documentation

R/loo_predict.R

@@ -177,9 +177,25 @@ E_loo_value <- function(x, psis_object, type = "mean", probs = 0.5) {
 #'
 #' @return If \code{summary = TRUE}, an M x C matrix is returned
 #'  (M = number of response variables and c = \code{length(probs) + 2})
-#'  containing summary statistics of the LOO-adjusted R-squared values.
-#'  If \code{summary = FALSE}, the posterior draws of the LOO-adjusted
-#'  R-squared values are returned in an S x M matrix (S is the number of draws).
+#'  containing Bayesian bootstrap based summary statistics of the
+#'  LOO-adjusted R-squared values. If \code{summary = FALSE}, the
+#'  Bayesian bootstrap draws of the LOO-adjusted R-squared values 
+#'  are returned in an S x M matrix (S is the number of draws).
+#'
+#'  @details LOO-R2 uses LOO residuals and is defined as
+#' \eqn{1-Var_{loo-res} / Var_y},
+#' with
+#' \deqn{
+#' Var_y = V_{n=1}^N y_n, and
+#' Var_{loo-res} = V_{n=1}^N \hat{e}_{loo,n},
+#' }
+#' where \eqn{\hat{e}_{loo,n}=y_n-\hat{y}_{loo,n}}.
+#' Bayesian bootstrap is used to draw from the approximated uncertainty
+#' distribution as described by Vehtari and Lampinen (2002).
+#'
+#' @references Vehtari and Lampinen (2002). Bayesian model assessment
+#' and comparison using cross-validation predictive densities. Neural
+#' Computation, 14(10):2439-2468. 
 #'
 #' @examples
 #' \dontrun{