Skip to contents

Sample a Markov chain

Source: R/chains.R
sample_chain.Rd

Sample a Markov chain using Metropolis-Hastings kernel with given proposal and target distributions, optionally adapting proposal parameters in warm-up stage.

Usage

sample_chain(
  target_distribution,
  proposal,
  initial_state,
  n_warm_up_iteration,
  n_main_iteration,
  adapters = NULL,
  trace_function = NULL,
  show_progress_bar = TRUE,
  trace_warm_up = FALSE
)

Arguments

target_distribution

Target stationary distribution for chain. A list with named entries log_density and gradient_log_density corresponding to respectively functions for evaluating the logarithm of the (potentially unnormalized) density of the target distribution and its gradient. As an alternative to gradient_log_density an entry value_and_gradient_log_density may instead be provided which is a function returning both the value and gradient of the logarithm of the (unnormalized) density of the target distribution as a list under the names value and gradient respectively.

proposal

Proposal distribution object. Must define entries sample, a function to generate sample from proposal distribution given current chain state and log_density_ratio, a function to compute log density ratio for proposal for a given pair of current and proposed chain states.

initial_state

Initial chain state. Either a vector specifying just the position component of the chain state or a list output by chain_state specifying the full chain state.

n_warm_up_iteration

Number of warm-up (adaptive) chain iterations to run.

n_main_iteration

Number of main (non-adaptive) chain iterations to run.

adapters

List of adapters to tune proposal parameters during warm-up.

trace_function

Function which given current chain state outputs list of variables to trace on each main (non-adaptive) chain iteration.

show_progress_bar

Whether to show progress bars during sampling. Requires progress package to be installed to have an effect.

trace_warm_up

Whether to record chain traces and adaptation / transition statistics during (adaptive) warm-up iterations in addition to (non-adaptive) main chain iterations.

Value

A list with entries

  • final_state: the final chain state,

  • traces: a matrix with named columns contained traced variables for each main chain iteration, with variables along columns and iterations along rows.

  • statistics: a matrix with named columns containing transition statistics for each main chain iteration, with statistics along columns and iterations along rows.

  • warm_up_traces: a matrix with named columns contained traced variables for each warm-up chain iteration, with variables along columns and iterations along rows. Only present if trace_warm_up = TRUE.

  • warm_up_statistics: a matrix with named columns containing adaptation and transition statistics for each warm-up chain iteration, with statistics along columns and iterations along rows. Only present if trace_warm_up = TRUE.

Examples

target_distribution <- list(
  log_density = function(x) -sum(x^2) / 2,
  gradient_log_density = function(x) -x
)
proposal <- barker_proposal(target_distribution, scale = 1.)
n_warm_up_iteration <- 1000
n_main_iteration <- 1000
withr::with_seed(876287L, {
  initial_state <- chain_state(stats::rnorm(2))
  results <- sample_chain(
    target_distribution,
    proposal,
    initial_state,
    n_warm_up_iteration,
    n_main_iteration
  )
})