R: Convenience function for computing relative efficiencies

relative_eff {loo} | R Documentation

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

### Arguments

`x` | A vector, matrix, 3-D array, or function. See the Methods (by class) section below for details on the shape of `x`. For use with the `loo` function, the values in `x` (or generated by `x` if `x` is 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 `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 to pass additional arguments to your log-likelihood function. These arguments are used like the `draws` argument in that they are recycled for each observation.

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

[Package loo version 2.0.0 Index]