diff --git a/R/importance_sampling.R b/R/importance_sampling.R index 6b6a4648..c763fe75 100644 --- a/R/importance_sampling.R +++ b/R/importance_sampling.R @@ -1,5 +1,5 @@ #' A parent class for different importance sampling methods. -#' @keywords internal +#' #' @inheritParams psis #' @param method The importance sampling method to use. The following methods #' are implemented: @@ -8,27 +8,13 @@ #' `sqrt(S)`, where `S` is the number of posterior draws. #' * [`"sis"`][sis]: Standard Importance Sampling (SIS). #' -importance_sampling <- function(log_ratios, method, ...) UseMethod("importance_sampling") - -#' @noRd -#' @keywords internal -#' @description -#' Currently implemented importance sampling methods -assert_importance_sampling_method_is_implemented <- function(x){ - if (!x %in% implemented_is_methods()) { - stop("Importance sampling method '", - x, - "' is not implemented. Implemented methods: '", - paste0(implemented_is_methods, collapse = "', '"), - "'") - } +importance_sampling <- function(log_ratios, method, ...) { + UseMethod("importance_sampling") } -implemented_is_methods <- function() c("psis", "tis", "sis") -#' Importance sampling of array + +#' @rdname importance_sampling #' @inheritParams psis -#' @template is_method -#' @keywords internal #' @export importance_sampling.array <- function(log_ratios, method, @@ -44,10 +30,8 @@ importance_sampling.array <- do_importance_sampling(log_ratios, r_eff = r_eff, cores = cores, method = method) } -#' Importance sampling of matrices +#' @rdname importance_sampling #' @inheritParams psis -#' @template is_method -#' @keywords internal #' @export importance_sampling.matrix <- function(log_ratios, method, @@ -61,10 +45,8 @@ importance_sampling.matrix <- do_importance_sampling(log_ratios, r_eff = r_eff, cores = cores, method = method) } -#' Importance sampling (default) +#' @rdname importance_sampling #' @inheritParams psis -#' @template is_method -#' @keywords internal #' @export importance_sampling.default <- function(log_ratios, method, ..., r_eff = NULL) { @@ -122,6 +104,23 @@ weights.importance_sampling <- # internal ---------------------------------------------------------------- +#' Validate selected importance sampling method +#' @noRd +#' @keywords internal +#' @description +#' Currently implemented importance sampling methods +assert_importance_sampling_method_is_implemented <- function(x){ + if (!x %in% implemented_is_methods()) { + stop("Importance sampling method '", + x, + "' is not implemented. Implemented methods: '", + paste0(implemented_is_methods, collapse = "', '"), + "'") + } +} +implemented_is_methods <- function() c("psis", "tis", "sis") + + #' Structure the object returned by the importance_sampling methods #' #' @noRd diff --git a/man/importance_sampling.Rd b/man/importance_sampling.Rd index f5295e35..06d4e89a 100644 --- a/man/importance_sampling.Rd +++ b/man/importance_sampling.Rd @@ -2,9 +2,30 @@ % Please edit documentation in R/importance_sampling.R \name{importance_sampling} \alias{importance_sampling} +\alias{importance_sampling.array} +\alias{importance_sampling.matrix} +\alias{importance_sampling.default} \title{A parent class for different importance sampling methods.} \usage{ importance_sampling(log_ratios, method, ...) + +\method{importance_sampling}{array}( + log_ratios, + method, + ..., + r_eff = NULL, + cores = getOption("mc.cores", 1) +) + +\method{importance_sampling}{matrix}( + log_ratios, + method, + ..., + r_eff = NULL, + cores = getOption("mc.cores", 1) +) + +\method{importance_sampling}{default}(log_ratios, method, ..., r_eff = NULL) } \arguments{ \item{log_ratios}{An array, matrix, or vector of importance ratios on the log @@ -22,8 +43,33 @@ are implemented: }} \item{...}{Arguments passed on to the various methods.} + +\item{r_eff}{Vector of relative effective sample size estimates containing +one element per observation. The values provided should be the relative +effective sample sizes of \code{1/exp(log_ratios)} (i.e., \code{1/ratios}). +This is related to the relative efficiency of estimating the normalizing +term in self-normalizing importance sampling. If \code{r_eff} is not +provided then the reported PSIS effective sample sizes and Monte Carlo +error estimates will be over-optimistic. See the \code{\link[=relative_eff]{relative_eff()}} +helper function for computing \code{r_eff}. If using \code{psis} with +draws of the \code{log_ratios} not obtained from MCMC then the warning +message thrown when not specifying \code{r_eff} can be disabled by +setting \code{r_eff} to \code{NA}.} + +\item{cores}{The number of cores to use for parallelization. This defaults to +the option \code{mc.cores} which can be set for an entire R session by +\code{options(mc.cores = NUMBER)}. The old option \code{loo.cores} is now +deprecated but will be given precedence over \code{mc.cores} until +\code{loo.cores} is removed in a future release. \strong{As of version +2.0.0 the default is now 1 core if \code{mc.cores} is not set}, but we +recommend using as many (or close to as many) cores as possible. +\itemize{ +\item Note for Windows 10 users: it is \strong{strongly} +\href{https://github.com/stan-dev/loo/issues/94}{recommended} to avoid using +the \code{.Rprofile} file to set \code{mc.cores} (using the \code{cores} argument or +setting \code{mc.cores} interactively or in a script is fine). +}} } \description{ A parent class for different importance sampling methods. } -\keyword{internal} diff --git a/man/importance_sampling.array.Rd b/man/importance_sampling.array.Rd deleted file mode 100644 index ea96bb65..00000000 --- a/man/importance_sampling.array.Rd +++ /dev/null @@ -1,61 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/importance_sampling.R -\name{importance_sampling.array} -\alias{importance_sampling.array} -\title{Importance sampling of array} -\usage{ -\method{importance_sampling}{array}( - log_ratios, - method, - ..., - r_eff = NULL, - cores = getOption("mc.cores", 1) -) -} -\arguments{ -\item{log_ratios}{An array, matrix, or vector of importance ratios on the log -scale (for PSIS-LOO these are \emph{negative} log-likelihood values). See the -\strong{Methods (by class)} section below for a detailed description of how -to specify the inputs for each method.} - -\item{...}{Arguments passed on to the various methods.} - -\item{r_eff}{Vector of relative effective sample size estimates containing -one element per observation. The values provided should be the relative -effective sample sizes of \code{1/exp(log_ratios)} (i.e., \code{1/ratios}). -This is related to the relative efficiency of estimating the normalizing -term in self-normalizing importance sampling. If \code{r_eff} is not -provided then the reported PSIS effective sample sizes and Monte Carlo -error estimates will be over-optimistic. See the \code{\link[=relative_eff]{relative_eff()}} -helper function for computing \code{r_eff}. If using \code{psis} with -draws of the \code{log_ratios} not obtained from MCMC then the warning -message thrown when not specifying \code{r_eff} can be disabled by -setting \code{r_eff} to \code{NA}.} - -\item{cores}{The number of cores to use for parallelization. This defaults to -the option \code{mc.cores} which can be set for an entire R session by -\code{options(mc.cores = NUMBER)}. The old option \code{loo.cores} is now -deprecated but will be given precedence over \code{mc.cores} until -\code{loo.cores} is removed in a future release. \strong{As of version -2.0.0 the default is now 1 core if \code{mc.cores} is not set}, but we -recommend using as many (or close to as many) cores as possible. -\itemize{ -\item Note for Windows 10 users: it is \strong{strongly} -\href{https://github.com/stan-dev/loo/issues/94}{recommended} to avoid using -the \code{.Rprofile} file to set \code{mc.cores} (using the \code{cores} argument or -setting \code{mc.cores} interactively or in a script is fine). -}} - -\item{is_method}{The importance sampling method to use. The following methods -are implemented: -\itemize{ -\item \code{\link[=psis]{"psis"}}: Pareto-Smoothed Importance Sampling (PSIS). Default method. -\item \code{\link[=tis]{"tis"}}: Truncated Importance Sampling (TIS) with truncation at -\code{sqrt(S)}, where \code{S} is the number of posterior draws. -\item \code{\link[=sis]{"sis"}}: Standard Importance Sampling (SIS). -}} -} -\description{ -Importance sampling of array -} -\keyword{internal} diff --git a/man/importance_sampling.default.Rd b/man/importance_sampling.default.Rd deleted file mode 100644 index 505abb67..00000000 --- a/man/importance_sampling.default.Rd +++ /dev/null @@ -1,41 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/importance_sampling.R -\name{importance_sampling.default} -\alias{importance_sampling.default} -\title{Importance sampling (default)} -\usage{ -\method{importance_sampling}{default}(log_ratios, method, ..., r_eff = NULL) -} -\arguments{ -\item{log_ratios}{An array, matrix, or vector of importance ratios on the log -scale (for PSIS-LOO these are \emph{negative} log-likelihood values). See the -\strong{Methods (by class)} section below for a detailed description of how -to specify the inputs for each method.} - -\item{...}{Arguments passed on to the various methods.} - -\item{r_eff}{Vector of relative effective sample size estimates containing -one element per observation. The values provided should be the relative -effective sample sizes of \code{1/exp(log_ratios)} (i.e., \code{1/ratios}). -This is related to the relative efficiency of estimating the normalizing -term in self-normalizing importance sampling. If \code{r_eff} is not -provided then the reported PSIS effective sample sizes and Monte Carlo -error estimates will be over-optimistic. See the \code{\link[=relative_eff]{relative_eff()}} -helper function for computing \code{r_eff}. If using \code{psis} with -draws of the \code{log_ratios} not obtained from MCMC then the warning -message thrown when not specifying \code{r_eff} can be disabled by -setting \code{r_eff} to \code{NA}.} - -\item{is_method}{The importance sampling method to use. The following methods -are implemented: -\itemize{ -\item \code{\link[=psis]{"psis"}}: Pareto-Smoothed Importance Sampling (PSIS). Default method. -\item \code{\link[=tis]{"tis"}}: Truncated Importance Sampling (TIS) with truncation at -\code{sqrt(S)}, where \code{S} is the number of posterior draws. -\item \code{\link[=sis]{"sis"}}: Standard Importance Sampling (SIS). -}} -} -\description{ -Importance sampling (default) -} -\keyword{internal} diff --git a/man/importance_sampling.matrix.Rd b/man/importance_sampling.matrix.Rd deleted file mode 100644 index bd3226ed..00000000 --- a/man/importance_sampling.matrix.Rd +++ /dev/null @@ -1,61 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/importance_sampling.R -\name{importance_sampling.matrix} -\alias{importance_sampling.matrix} -\title{Importance sampling of matrices} -\usage{ -\method{importance_sampling}{matrix}( - log_ratios, - method, - ..., - r_eff = NULL, - cores = getOption("mc.cores", 1) -) -} -\arguments{ -\item{log_ratios}{An array, matrix, or vector of importance ratios on the log -scale (for PSIS-LOO these are \emph{negative} log-likelihood values). See the -\strong{Methods (by class)} section below for a detailed description of how -to specify the inputs for each method.} - -\item{...}{Arguments passed on to the various methods.} - -\item{r_eff}{Vector of relative effective sample size estimates containing -one element per observation. The values provided should be the relative -effective sample sizes of \code{1/exp(log_ratios)} (i.e., \code{1/ratios}). -This is related to the relative efficiency of estimating the normalizing -term in self-normalizing importance sampling. If \code{r_eff} is not -provided then the reported PSIS effective sample sizes and Monte Carlo -error estimates will be over-optimistic. See the \code{\link[=relative_eff]{relative_eff()}} -helper function for computing \code{r_eff}. If using \code{psis} with -draws of the \code{log_ratios} not obtained from MCMC then the warning -message thrown when not specifying \code{r_eff} can be disabled by -setting \code{r_eff} to \code{NA}.} - -\item{cores}{The number of cores to use for parallelization. This defaults to -the option \code{mc.cores} which can be set for an entire R session by -\code{options(mc.cores = NUMBER)}. The old option \code{loo.cores} is now -deprecated but will be given precedence over \code{mc.cores} until -\code{loo.cores} is removed in a future release. \strong{As of version -2.0.0 the default is now 1 core if \code{mc.cores} is not set}, but we -recommend using as many (or close to as many) cores as possible. -\itemize{ -\item Note for Windows 10 users: it is \strong{strongly} -\href{https://github.com/stan-dev/loo/issues/94}{recommended} to avoid using -the \code{.Rprofile} file to set \code{mc.cores} (using the \code{cores} argument or -setting \code{mc.cores} interactively or in a script is fine). -}} - -\item{is_method}{The importance sampling method to use. The following methods -are implemented: -\itemize{ -\item \code{\link[=psis]{"psis"}}: Pareto-Smoothed Importance Sampling (PSIS). Default method. -\item \code{\link[=tis]{"tis"}}: Truncated Importance Sampling (TIS) with truncation at -\code{sqrt(S)}, where \code{S} is the number of posterior draws. -\item \code{\link[=sis]{"sis"}}: Standard Importance Sampling (SIS). -}} -} -\description{ -Importance sampling of matrices -} -\keyword{internal}