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

relative_eff(x, ...)

# S3 method for default
relative_eff(x, chain_id, ...)

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

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

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

# S3 method for 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)

• relative_eff(default): A vector of length $$S$$ (posterior sample size).

• relative_eff(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.

• relative_eff(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.

• relative_eff(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.

• relative_eff(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)
#>  500   2  32
dim(LLmat)
#>  1000   32

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)
#>  TRUE