loo: relative_eff – R documentation

Pricing

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Get Started for Free

Documentation

loo

relative_eff

Convenience function for computing relative efficiencies

Description

relative_eff() computes the the MCMC effective sample size divided by the total sample size.

Usage

relative_eff(x, ...)

## Default S3 method:
relative_eff(x, chain_id, ...)

## S3 method for class 'matrix'
relative_eff(x, chain_id, ..., cores = getOption("mc.cores", 1))

## S3 method for class 'array'
relative_eff(x, ..., cores = getOption("mc.cores", 1))

## S3 method for class ''function''
relative_eff(
  x,
  chain_id,
  ...,
  cores = getOption("mc.cores", 1),
  data = NULL,
  draws = NULL
)

## S3 method for class 'importance_sampling'
relative_eff(x, ...)

Arguments

`x`	A vector, matrix, 3-D array, or function. See the Methods (by class) section below for details on specifying `x`, but where "log-likelihood" is mentioned replace it with one of the following depending on the use case: For use with the `loo()` function, the values in `x` (or generated by `x`, if a function) should be likelihood values (i.e., `exp(log_lik)`), not on the log scale. For generic use with `psis()`, the values in `x` should be the reciprocal of the importance ratios (i.e., `exp(-log_ratios)`).
`chain_id`	A vector of length `NROW(x)` containing MCMC chain indexes for each each row of `x` (if a matrix) or each value in `x` (if a vector). No `chain_id` is needed if `x` is a 3-D array. If there are `C` chains then valid chain indexes are values in `1:C`.
`cores`	The number of cores to use for parallelization.
`data, draws, ...`	Same as for the `loo()` function method.

Value

A vector of relative effective sample sizes.

Methods (by class)

default: A vector of length S (posterior sample size).
matrix: An S by N matrix, where S is the size of the posterior sample (with all chains merged) and N is the number of data points.
array: An I by C by N array, where I is the number of MCMC iterations per chain, C is the number of chains, and N is the number of data points.
function: A function f() that takes arguments data_i and draws and returns a vector containing the log-likelihood for a single observation i evaluated at each posterior draw. The function should be written such that, for each observation i in 1:N, evaluating
```
f(data_i = data[i,, drop=FALSE], draws = draws)
```
results in a vector of length S (size of posterior sample). The log-likelihood function can also have additional arguments but data_i and draws are required.

If using the function method then the arguments data and draws must also be specified in the call to loo():
- data: A data frame or matrix containing the data (e.g. observed outcome and predictors) needed to compute the pointwise log-likelihood. For each observation i, the ith row of data will be passed to the data_i argument of the log-likelihood function.
- draws: An object containing the posterior draws for any parameters needed to compute the pointwise log-likelihood. Unlike data, which is indexed by observation, for each observation the entire object draws will be passed to the draws argument of the log-likelihood function.
- The ... can be used if your log-likelihood function takes additional arguments. These arguments are used like the draws argument in that they are recycled for each observation.
importance_sampling: If x is an object of class "psis", relative_eff() simply returns the r_eff attribute of x.

Examples

LLarr <- example_loglik_array()
LLmat <- example_loglik_matrix()
dim(LLarr)
dim(LLmat)

rel_n_eff_1 <- relative_eff(exp(LLarr))
rel_n_eff_2 <- relative_eff(exp(LLmat), chain_id = rep(1:2, each = 500))
all.equal(rel_n_eff_1, rel_n_eff_2)

loo

Efficient Leave-One-Out Cross-Validation and WAIC for Bayesian Models

v2.4.1

GPL (>= 3)

Authors

Aki Vehtari [aut], Jonah Gabry [cre, aut], Mans Magnusson [aut], Yuling Yao [aut], Paul-Christian Bürkner [aut], Topi Paananen [aut], Andrew Gelman [aut], Ben Goodrich [ctb], Juho Piironen [ctb], Bruno Nicenboim [ctb]

Initial release

2020-12-07