The input to 'extract.chains' is one of 5 types:  (i) output produced by a call to 'bugs' in package R2OpenBUGS; (ii) output produced by a call to 'bugs in package R2WinBUGS; (iii) output produced by a call to 'jags' in package R2jags; (iv) a list of class "mcmc.list";  or (v) output produced by a previous call to 'extract.chains' (which was applied to 'bugs' or 'jags' output).  Case (v) is mainly used by the 'extract.vars' function to reorganize chains that were previously processes by 'extract.chains' (e.g., 'extract.vars' calls 'extract.chains').  If the chains were produced by a call to functions in BRugs, use 'brugs.chains' to load the chains into R.  

Henceforth, OpenBUGS, WinBUGS and JAGS will all be referenced as BUGS in this documentation.

The output of 'extract.chains' is a list. Suppose that the output is assigned to the object 'bugs.out',   The 1st component of 'bugs.out' contains chains for the 1st saved parameter; ...; the j-th component contains chains for the j-th saved parameter. The last component of this list, called $doc..BUGS, contains documentation of the BUGS run.  Except for the last component, a component is a vector if the BUGS output was computed with only 1 chain or if the call to 'extract.chains' specifies that multiple chains are to be combined into a single vector (see 'combine.chains' below).  If the multiple chains in the 'bugs' or 'jags' run are preserved ('combine.chains = FALSE'), then each component is a matrix.  The columns of each matrix are the parameter estimates from one of the chains in the BUGS run.  The estimates are enumerated in the order in which the estimates were computed unless randomization is requested.  Each matrix has as many columns as there were chains in the BUGS run.  

ARGUMENTS:

'bugs.out' = output from a call to 'bugs' in the R2OpenBUGS or R2WinBUGS package or output from a call to 'jags' in the R2jags package.

'burnin = 0' (default) is used to set the number of burn-in samples to be discarded.  If the 'bugs' or 'jags' call was computed with a non-zero burnin specification, then these samples will have been discarded before 'extract.chains' can access these samples.  Therefore if 'extract.chains' is called with 'burnin' > 0, then these samples are discarded in addition to any that were discarded as burnin samples in the call to 'bugs' or 'jags'.  Typically, 'extract.chains' should be used with a 'bugs' or 'jags' call that specifies a burnin of 0 because burnin samples can be discarded after looking at the chains extracted by 'extract.chains'.  

'n.thin' indicates the rate at which estimates are saved.  If 'n.thin = 1', then all estimates are saved (not counting the discarded burnin samples).  Note that the discarding of samples by 'n.thin' occurs after discarding the initial 'burnin' samples.

If 'parameters = NA' (default), then all saved parameters are extracted.  Otherwise, set 'parameters' to a character vector that names the parameters whose estimates are to be extracted.  Use 'dimnames(Bugs.Out$sims.array)[[3]]' to see the names of the parameters whose estimates were saved in the call to 'bugs' (substitute the name of the 'bugs' output for 'BUGS.OUTPUT'). Use 'dimnames(JAGS.Out$BUGSoutput$sims.array)[[3]]' to see the names of the parameters whose estimates were saved in the call to 'jags' (substitute the name of the 'jags' output for 'JAGS.Out'). 

'improve.names = TRUE' (default) uses the 'make.names.jm' function to create names for list components that are syntactically valid in R.  If 'improve.names = FALSE', then the parameter names in the 'bugs' output are retained without changes.

'combine.chains = FALSE' (default).  If $n.chains > 1 & 'combine.chains = FALSE', then each component of the output list is a matrix with $n.chains columns and $n.iter - burnin rows.  If $n.chains = 1 or if 'combine.chains = TRUE', then each component of the output is a vector.  Each vector combines the separate chains for a parameter 
(after discarding burnin samples from each chain). 

'randomize = FALSE' (default) if the output vectors or matrices are in the order of $sims.array (after discarding burnin samples). If  'randomize = TRUE', then the rows of the output matrix (multiple chains), or the elements of the output vector (1 chain) are randomly reordered.

'include.doc = TRUE' (default).  If TRUE, the output has a 'doc' component that retains a record of the BUGS/JAGS run that produced the output.  If FALSE, this component is omitted from the output. 

'Warn = TRUE' (default) gives the user feedback whenever any burnin samples were dropped either in the original 'bugs' call or in the call to 'extract.chains'.  If 'Warn = FALSE', the feedback is suppressed.

OUTPUT:

The last component of the output, called 'doc..BUGS', is documentation of the simulation that produced the chains of estimates, including the name of the program, OpenBUGS, WinBUGS or JAGS, the name of the model file, parameters that defined the BUGS run (n.chains, burnin, n.iter, n.thin), and the model code in the model file.  In the case of OpenBUGs and WinBUGS, the model code is read from the file named by the 'model.file' component of the 'bugs' output.  There is the possibility that the record of this code will be inaccurate in the case where the user has changed the code between the time when BUGS was run and the time when extract.chains was used to extract the chains from the BUGS output, but this is not likely to occur as long as extract.chains has been applied to the BUGS output soon after it was produced.  This problem does not occur with JAGS output because the 'jags' function in R2jags preserves the model code in the JAGS output.  

The output contains one component for each of the saved parameters.  As explained above, each component is either a vector (if only one chain was specified in the BUGS run or if chains have been combined), or a matrix if multiple chains were created and preserved.