## ./

# mcmc__define.pro

This class defines an interface for running Markov Chain Monte Carlo simulations. The code is based on the opening chapters of "Markov Chain Monte Carlo in Practice" by Gilks et al. The code in this file sets up the logic for running an MCMC simulation using the Metropolis Hastings algorithm. To actually use these functions, a subclass must be defined, and the selectTrial and logTargetDistribution methods must be overridden. Each of these methods is problem-specific, and cannot be coded in advance.

## Class description for mcmc

Subclasses: mcmc_multi

## Author information

- History
September 2009: Written by Chris Beaumont October 2 2009: Modified run procedure to avoid unnecessary calls to logTargetDistribution October 3 2009: Added THIN keyword and state variable

## Routines

`mcmc::run, verbose=verbose`

This procedure runs the Markov Chain

`result = mcmc::selectTrial(current [, transitionRatio=transitionRatio])`

This function generates a new trial link in the markov chain, given the current link.

`result = mcmc::logTargetDistribution(link)`

This function calculates the (unnormalized) logarithm of the target distribution that the Marcov Chain aims to sample from.

`result = mcmc::getChain(logf=logf)`

This function returns the markov chain

`result = mcmc::getNSuccess( [nfail=nfail])`

This function returns the number of successes and failures (that is, acceptances and rejections of the proposal link) in the Markov chain.

`result = mcmc::getData()`

This method returns the MCMC object's data, if any

`result = mcmc::getSeed()`

This function returns the seed link

`result = mcmc::init(seed, nstep, data [, thin=thin])`

This function initializes the MCMC object

`mcmc::cleanup`

Free memory when we are finished

`mcmc__define`

define the mcmc data structure

## Routine details

## topmcmc::run

statistics

`mcmc::run, verbose=verbose`

This procedure runs the Markov Chain

mcmc_common: Holds the seed variable for calls to randomu

### Keywords

- verbose

### Author information

- History:
September 2009: Written by Chris Beaumont Oct 3 2009: Optimized so that logTargetDistribution is only ever evaluated once per link

## topmcmc::selectTrial

statistics

`result = mcmc::selectTrial(current [, transitionRatio=transitionRatio])`

This function generates a new trial link in the markov chain, given the current link. It is not implemented by default, and must be overridden. This function must also return the ratio of the transition probabilities between the old and new links (i.e., q(old | new) / q(new | old) ). This ratio is needed by the Metropolis Hastings algorithm implemented in getTransitionProbability.

### Return value

The next link in the chain to try.

### Parameters

- current in required
The current link in the chain. This can be any kind of scalar (number, structure, object, etc), as long as the implementing class knows how to handle it.

### Keywords

- transitionRatio in optional
This must be set to a named variable that will hold, on output, the transition ratio q(current | next) / q(next | current)

## topmcmc::logTargetDistribution

statistics

`result = mcmc::logTargetDistribution(link)`

This function calculates the (unnormalized) logarithm of the target distribution that the Marcov Chain aims to sample from. It is usually a likelihood or posterior distribution, but the function is not implemented in this interface. We use the logarithm of the function, since its values may often be very small.

### Return value

The log of the target distribution, evaluated at link.

### Parameters

- link in required
The point at which to evaluate the target distribution.

## topmcmc::getChain

statistics

`result = mcmc::getChain(logf=logf)`

This function returns the markov chain

### Return value

The Markov Chain

### Keywords

- logf

## topmcmc::getNSuccess

statistics

`result = mcmc::getNSuccess( [nfail=nfail])`

This function returns the number of successes and failures (that is, acceptances and rejections of the proposal link) in the Markov chain.

### Return value

The number of successes

### Keywords

- nfail in optional
Set to a named variable to hold the number of failures

## topmcmc::getData

statistics

`result = mcmc::getData()`

This method returns the MCMC object's data, if any

## topmcmc::init

statistics

`result = mcmc::init(seed, nstep, data [, thin=thin])`

This function initializes the MCMC object

### Return value

1 for success

### Parameters

- seed in required
The initial point to start the chain at. Can be any scalar, as long as it is correctly handeled by the other MCMC methods

- nstep in required
The number of links in the desired Markov Chain.

- data in required
Any data relevant to the process

### Keywords

- thin in optional
Set to a number to avoid storing every step of the chain. This is useful for long chains which might otherwise take up lots of memory. If set, then only every THIN'th link will be saved to the chain. Should be less than the correlation length of the chain.

## topmcmc__define

statistics

`mcmc__define`

define the mcmc data structure

### Author information

- History:
September 2009: Written by Chris Beaumont Oct 2010: Added logf field

## File attributes

Modifcation date: | Thu Nov 3 17:24:52 2011 |

Lines: | 301 |