chain: run a Monte Carlo Markov Chain.
Syntax: chain [burn <length>] [clear] [info] [length <length>] [load <filename>] [rand on|off] [recalc] [run <filename>] [stat <par num>] [unload <range>]
Before running any chains you must perform a fit. The MCMC algorithm uses the correlation matrix produced at the end of a fit as the initial source for the proposal distribution.
burn <length> specifies that the first <length> steps should be thrown away prior to storing the chain.
clear does a reset and removes all chains from the list.
info prints out information on the current chains.
length <length> sets the length for new chains.
load <filename> will load a chain which has been run earlier, stored in file given by <filename>.
rand on specifies that the chain start point will be randomized. rand off specifies that the current parameters should be taken as the start point.
recalc derives a new proposal distribution from the current chains. This assumes a multidimensional normal distribution and is described using eigenvectors and eigenvalues which are then stored in the standard xspec arrays.
run <filename> will run a new chain written to the specified file. The chain is written to the file as it runs so its performance can be monitored by examining the file. A long run may be interrupted with Ctrl-C, in which case the chain file will still exist but will not be automatically loaded.
stat <par num> writes out statistical information on a particular parameter of the chain, specified by the integer <par num>. The information displayed is
line1: The mean of the parameter over each chain file.
line2: The parameter mean over all chain files, the total variance, the variance within the chains, and the Rubin-Gelman convergence criterion.
unload <range> removes the chains specified by <range> from the list in xspec. Note that this does NOT delete the chain files.
All loaded chains must contain the same fit parameters. xspec will prevent the loading of a chain with a different number of parameters from the currently loaded chains.
Examples:
XSPEC12>chain length 100
//Sets length of chains produced by the run command to 100.
XSPEC12>chain run chain_file1.out
//Runs a chain based on current valid fit parameters, output to
//chain_file1.out
XSPEC12>chain load chain_old.out
//Loads a pre-existing chain file, the result of an earlier run
//command. Warning is issued if not the same length as
//chain_file1.out
XSPEC12>chain stat 3
//Prints statistical information on the 3rd parameter of the chain.
XSPEC12>chain clear
//Removes the 2 loaded chains from xspec’s chain list.