Skip to contents

Run nested sampling to estimate Bayesian evidence

Source: R/generate.R
generate.ernest_sampler.Rd

Executes the nested sampling algorithm, iteratively replacing the worst live point with a new sample from a likelihood-restricted prior until a stopping criterion is met.

Usage

# S3 method for class 'ernest_sampler'
generate(
  x,
  max_iterations = NULL,
  max_evaluations = NULL,
  min_logz = 0.05,
  show_progress = NULL,
  ...
)

# S3 method for class 'ernest_run'
generate(
  x,
  max_iterations = NULL,
  max_evaluations = NULL,
  min_logz = 0.05,
  show_progress = NULL,
  ...
)

Arguments

x

[ernest_sampler] or [ernest_run]
A nested sampling specification.

max_iterations

[integer(1)]
The maximum number of iterations to perform. Optional; if NULL this criterion is ignored.

max_evaluations

[integer(1)]
The maximum number of likelihood function evaluations to perform. Optional; if NULL this criterion is ignored.

min_logz

[double(1)]
The minimum log-ratio between the current estimated evidence and the remaining evidence. Must be non-negative; if set to zero, this criterion is ignored.

show_progress

[logical(1)]
If TRUE, displays a progress spinner and iteration counter during sampling. Optional; if NULL the global option rlib_message_verbosity is used to determine whether to show progress.

...

Arguments passed on to compile.ernest_run

clear

[logical(1)]
If TRUE, clears results from previous runs before compiling. If FALSE, retains previous results and validates the live set.

Value

[ernest_run]

A named list containing the results of the nested sampling run, which contains nsample = nlive + niter samples from the prior distribution. This list inherits from ernest_sampler, and additionally contains:

  • niter: [integer(1)] Number of iterations performed.

  • neval: [integer(1)] Total number of likelihood function evaluations. Note that it is possible for a single call to a likelihood function to evaluate the likelihoods of multiple parameter samples.

  • log_evidence: [double(1)] The log-evidence estimate.

  • log_evidence_err: [double(1)] The standard error of the log-evidence estimate, estimated from information.

  • information: [double(1)] The estimated Kullback-Leibler divergence.

  • samples: [list] The posterior samples ordered by their log-likelihood values:

    • original: [matrix(double(), nsample, ndim)] The samples transformed to the parameter space.

    • unit_cube: [matrix(double(), nsample, ndim)] The samples in the unit hypercube.

  • weights: [list] Additional information on the points generated by the run:

    • id: [integer(nsample)] The index of each point in the live set for each sample.

    • evaluations: [integer(nsample)] The number of likelihood evaluations needed to replace each point.

    • log_weight: [double(nsample)] The log-weight of each sample.

    • imp_weight: [double(nsample)] The normalized importance weight for each sample. This is given by normalizing log_weight with log_evidence, then applying exp to the result so the weights sum to one.

    • log_lik: [double(nsample)] The log-likelihood for each sample.

    • birth_lik: [double(nsample)] The log-likelihood of the point used to create each sample.

Details

At least one of max_iterations, max_evaluations, or min_logz must specify a valid stopping criterion. Setting min_logz to zero while leaving max_iterations and max_evaluations at their defaults will result in an error.

If x is an ernest_run object, the stopping criteria are checked against the current state of the run. An error is thrown if the stopping criteria have already been satisfied by x.

The min_logz parameter controls the relative tolerance for the remaining evidence in the unexplored parameter space. Sampling stops when the estimated remaining evidence is sufficiently small compared to the accumulated evidence.

References

Skilling, J. (2006). Nested Sampling for General Bayesian Computation. Bayesian Analysis, 1(4), 833–859. doi:10.1214/06-BA127

Examples

prior <- create_uniform_prior(lower = c(-1, -1), upper = 1)
ll_fn <- function(x) -sum(x^2)
sampler <- ernest_sampler(ll_fn, prior, nlive = 100)
sampler
#> Nested sampling run specification:
#> * No. points: 100
#> * Sampling method: 25-step random walk sampling (acceptance target = 50.0%)
#> * Prior: uniform prior distribution with 2 dimensions (Uniform_1 and Uniform_2)

# Stop sampling after a set number of iterations or likelihood calls.
generate(sampler, max_iterations = 100)
#> Nested sampling run:
#> * No. points: 100
#> * Sampling method: 25-step random walk sampling (acceptance target = 50.0%)
#> * Prior: uniform prior distribution with 2 dimensions (Uniform_1 and Uniform_2)
#> ── Results ─────────────────────────────────────────────────────────────────────
#> * Iterations: 100
#> * Likelihood evals.: 166
#> * Log-evidence: -0.5983 (± 0.1235)
#> * Information: 0.08405

# The final number of calls may exceed `max_evaluations`, as `generate`
# only checks the number of calls when removing a live point.
generate(sampler, max_evaluations = 2600)
#> Nested sampling run:
#> * No. points: 100
#> * Sampling method: 25-step random walk sampling (acceptance target = 50.0%)
#> * Prior: uniform prior distribution with 2 dimensions (Uniform_1 and Uniform_2)
#> ── Results ─────────────────────────────────────────────────────────────────────
#> * Iterations: 223
#> * Likelihood evals.: 2607
#> * Log-evidence: -0.5962 (± 0.0745)
#> * Information: 0.08494

# Use the default stopping criteria
if (FALSE)  generate(sampler)  # \dontrun{}