'extract.vars' extracts samples from one or more posterior distributions from output that was created by a call to the bugs function in R2OpenBUGS or R2WinBUGS, or by a call to the jags function in R2jags or by a call to 'extract.chains'.  If the samples were computed as 2 or more chains, 'extract.vars' combines these chains into a single vector after (optionally) removing an initial set of burnin samples from each chain, thinning the remaining data at the rate indicated by 'n.thin, and randomizing the order of samples.  (A previous version of this function was named 'bugs.var'.)

Use the 'extract.chains' function to extract the individual chains of estimates for a parameter (usually to examine issues of convergence).  'extract.vars' uses 'extract.chains' to extract the chains of estimates, so you should look at 'extract.chains' to see exactly how the chains of estimates were extracted.  'extract.chains' can be applied to output from a previous call to 'extract.chains', so it is possible to use the output of 'extract.chains' as the main record of an MCMC run (discarding a lot of space-consuming stuff).  Then 'extract.vars' can be applied to this output whenever one wants to reorganize the chains into individual variables, one for each parameter.  

By default, the 'extract.vars' output is a vector if the estimates for only 1 parameter are extracted, and the output is a dataframe if the estimates for k > 1 parameters are extracted.

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, or output from a previous call to 'extract.chains'.  

'parameters = NA' (default) extracts samples for all parameters that were saved in 'bugs.out'.  'parameters' can be set to a vector of variable names if only a subset of the variables are to be extracted.

'burnin = 0' (default) is used to set the number of burn-in samples to be discarded.  Note that these samples are discarded from the initial segment of each chain prior to combining them into a vector.

'n.thin' indicates the thinning rate. 'n.thin = 1' indicates no thinning.

if 'new.names = NA & keep.bugs.names == FALSE' (default), the R-legal versions of the WinBUGS parameter names are to be used as column names in the output dataframe.  Set 'new.names' to a character vector of names if alternative names are preferred.

If 'keep.bugs.names == TRUE', the BUGS names for the parameters are retained,  even if they are not legal names in R, e.g., the name "x[1]" will be retained.  If 'keep.bugs.names == FALSE' (default), the variable names in the output will be R-legal names.

'randomize = TRUE' (default) if the samples are randomly reordered.  If 'randomize = FALSE', then the samples in a vector are ordered [(chain 1 - burnin)//n.thin][(chain 2 - burnin)//n.thin]... [(chain k - burnin)//n.thin],  where '//' indicates thinning at the rate indicated by 'n.thin'.