diff --git a/NAMESPACE b/NAMESPACE index 4d1a9118..d8d24d61 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -153,6 +153,7 @@ export(psislw) export(relative_eff) export(scrps) export(sis) +export(srs_diff_est) export(stacking_weights) export(tis) export(waic) diff --git a/NEWS.md b/NEWS.md index 6f182376..30903c38 100644 --- a/NEWS.md +++ b/NEWS.md @@ -17,6 +17,7 @@ * Added contribution section. by @VisruthSK in #286 * Update LOO uncertainty paper to use BA doi by @avehtari in #311 * Update documentation for `E_loo()` function by @avehtari in #312 +* Export `srs_diff_est()` function by @vinniott in #340 # loo 2.8.0 diff --git a/R/loo_subsample.R b/R/loo_subsample.R index bcac4b17..24e042a9 100644 --- a/R/loo_subsample.R +++ b/R/loo_subsample.R @@ -24,7 +24,7 @@ #' same length containing the posterior density and the approximation density #' for the individual draws. #' -#' @seealso [loo()], [psis()], [loo_compare()] +#' @seealso [loo()], [psis()], [loo_compare()], [srs_diff_est()] #' @template loo-large-data-references #' #' @export loo_subsample loo_subsample.function @@ -1166,12 +1166,40 @@ loo_subsample_estimation_diff_srs <- function(x) { update_psis_loo_ss_estimates(x) } -#' Difference estimation using SRS-WOR sampling (Magnusson et al., 2020) -#' @noRd -#' @param y_approx Approximated values of all observations. -#' @param y The values observed. -#' @param y_idx The index of `y` in `y_approx`. -#' @return A list with estimates. +#' Difference estimator with simple random sampling without replacement. +#' +#' The difference estimator `srs_diff()` estimates +#' the expectation \eqn{n E[y]} when we have \eqn{n} approximate values \eqn{\tilde{y}_i}, +#' \eqn{i = 1, \ldots, n} and \eqn{m < n} accurate values \eqn{y_j}, \eqn{j \in \mathcal{S}}, +#' where \eqn{m} is the subsample size and \eqn{\mathcal{S}} is +#' a simple random subsample without replacement. The original +#' approach is by Cochran (1977) and we follow the equations 7--9 by +#' Magnusson et al. (2020). +#' +#' @details In Magnusson et al. (2020) Eq (9) first row, the second `+` should +#' be a `-`; Supplementary Material Eq (6) has this correct. +#' As `srs_diff_est()` in the `loo` package is used for \eqn{n E[y]}, there is +#' a proportional difference of \eqn{1/n} compared to the paper. +#' +#' @param y_approx (numeric) `n` approximated values. +#' @param y (numeric) `m