Syntax: chain [burn <length>] [clear] [filetype fits|ascii] [info] [length <length>] [load <filename>] [proposal [<distr> <source>]|[<user-defined>]] [rand on|off] [run [>]<filename>] [stat <par num>] [temperature <value>] [type mh|gw] [unload <range>] [walkers <value>]
If the proposal source is set to use the fit correlation matrix (the default), you must perform a fit before running any chains.
When chains are loaded (and their parameters correspond to the currently loaded model), they will be used by the various XSPEC commands that require distributions of parameter values, such as eqwidth or flux when calculating error estimations. The error command itself will also use the loaded chains, determining the error range from a central percentage of the sorted chain values. This is likely to be faster than the error command’s standard algorithm when not using chains.
|
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. |
||
|
filetype fits|ascii |
Chooses the format of the output chain file. fits (the default) writes the chain to a binary table in a FITS file. ascii writes the chain to a simple text file. Either format is readable when using the load command. |
||
|
info |
Prints out information on the current chains. |
||
|
length <length> |
Sets the length for new chains. |
||
|
load <filename> |
Loads a chain which has been run earlier, stored in file given by <filename>. |
||
|
proposal <distr> <source> |
Selects the proposal distribution and source of covariance information to be used when running new chains. The default is proposal gaussian fit. Currently implemented <distr> options are: gaussian and cauchy. <source> options are: |
||
|
|
chain |
Covariance is taken from the currently loaded chains. |
|
|
|
diagonal <values> |
The values of a diagonal covariance matrix are entered directly on the command line, separated by commas and/or spaces: C_11 C_22 ... C_nn. |
|
|
|
<filename> |
Covariance is read in from a user-specified text file. The file must contain the values of an NxN matrix where N is the current number of freely varying parameters. The values of each matrix row should be entered on one line with whitespace separation. Since this matrix is always symmetrical, values above the diagonal may be omitted. For example a 2x2 matrix could be entered as: 0.98 0.15 0.96 |
|
|
|
fit |
Covariance is taken from the correlation information produced by the current fit. |
|
|
|
matrix <values> |
The lower half and diagonal of a symmetrical square covariance matrix are entered directly on the command line, separated by commas and/or spaces: C_11 C_21 C_22 C_31 C_32 C_33 ... C_nn |
|
|
|
Typing chain proposal with no other arguments will show a list of all available proposal options. For an alternative to XSPEC’s <distr> <source> proposal options, the user may instead want to provide their own custom randomization algorithm. This can be done by writing their own C++ class(es) derived from an XSPEC randomizer base class. The custom class is added at runtime using the same initpackage/lmod command sequence as for local models, and is specified by proposal <name> where <name> is the unique name attribute the user provides for their class. Please see Appendix G for more information on writing a custom randomizing class, and initpackage for building and loading it. |
||
|
rand on|off |
Specifies whether the chain start point will be randomized, or taken from the current parameters. |
||
|
recalc |
A deprecated option that performs the equivalent of proposal gaussian chain. |
||
|
run [>]<filename> |
Runs a new chain written to the specified file, or append to an already loaded file if the “>” character preceeds the filename. The chain is written to the file as it runs so its performance can be monitored by examining the file. For high-chatter settings, additional information is printed to the screen. A long run may be interrupted with Ctrl-C, in which case the chain file will still exist but will not be automatically loaded. If appending to a file, the current filetype setting must match the format of the file or XSPEC will prevent it. |
||
|
stat [<modName>:]<parIdx> |
Writes out statistical information on a particular parameter of the chain, specified by the parameter index number (with optional model name). The information displayed is: line1: The mean of the parameter over each chain file. line2: The parameter mean over all chain files and the variance between chain means. line3: The variance within the chains. line4: The Rubin-Gelman convergence criterion. line5: The fraction of repeats, defined as the number of lines in the chain file for which all parameter values are identical to the previous line, divided by the number of lines in the file.
|
||
|
temperature <value> |
Sets the temperature parameter used in the Metropolis-Hastings algorithm for the proposal acceptance or rejection. The default value is 1.0 and zero or negative values are forbidden. By using the run append option, it is possible for different sections of the chain file to use different temperatures. The temperatures and the line numbers to which they apply are stored in the header of the FITS format chain files, or in the metadata section at the top of the ASCII text format files. |
||
|
type mh | gw |
Determines the algorithm used to generate the chain. Choices are “mh” (Metropolis-Hastings) or “gw” (Goodman-Weare, the default). If using Goodman-Weare, must also set the walkers parameter. |
||
|
unload <range> |
Removes the chains specified by <range> from the list in xspec. Note that this does NOT delete the chain files. |
||
|
walkers <value> |
Sets the walkers parameter for the Goodman-Weare chain algorithm (see type). This must be an even integer, and both the chain length and burn length should be divisible by it (XSPEC will adjust the lengths to make them so if necessary). |
||
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 run >chain_file1.out
//Appends another run of length 100 to the end of 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 proposal gaussian myfile.txt
//New chain proposals will be a normal distribution using
//covariance values stored in myfile.txt rather than fit
//correlation matrix.
XSPEC12>chain prop gauss diag .1 .001 .0001
// New chain proposals will be a normal distribution using a 3x3
// diagonal covariance matrix with the values from the
// command line.
XSPEC12>chain temperature .8
// Sets the Metropolis-Hastings temperature value to .8 for
// future chain runs, replacing the default 1.0.
XSPEC12>chain clear
//Removes the 2 loaded chains from xspec’s chain list.