Merge pull request #1712 from avehtari/R2_doc_improvements

R2 doc improvements

R/bayes_R2.R

@@ -13,12 +13,12 @@
 #'  If \code{summary = FALSE}, the posterior draws of the Bayesian
 #'  R-squared values are returned in an S x M matrix (S is the number of draws).
 #'
-#' @details For an introduction to the approach, see Gelman et al. (2018)
+#' @details For an introduction to the approach, see Gelman et al. (2019)
 #'  and \url{https://github.com/jgabry/bayes_R2/}.
 #'
-#' @references Andrew Gelman, Ben Goodrich, Jonah Gabry & Aki Vehtari. (2018).
-#'   R-squared for Bayesian regression models, \emph{The American Statistician}.
-#'   \code{10.1080/00031305.2018.1549100} (Preprint available at
+#' @references Andrew Gelman, Ben Goodrich, Jonah Gabry & Aki Vehtari. (2019).
+#'   R-squared for Bayesian regression models, \emph{The American Statistician},
+#'   73(3):307-309. \code{10.1080/00031305.2018.1549100} (Preprint available at
 #'   \url{https://stat.columbia.edu/~gelman/research/published/bayes_R2_v3.pdf})
 #'
 #' @examples

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{