`R/effective_sample_sizes.R`

`relative_eff.Rd`

`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, ...)
```

- 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:- 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.

A vector of relative effective sample sizes.

`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`i`

th 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`

.

```
LLarr <- example_loglik_array()
LLmat <- example_loglik_matrix()
dim(LLarr)
#> [1] 500 2 32
dim(LLmat)
#> [1] 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)
#> [1] TRUE
```