File: jmfuns.rda
extract.vars extracts samples from 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 the 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.
extract.vars( bugs.out, parameters = NA, burnin = 0, n.thin = 1,
new.names = NA, keep.bugs.names = FALSE, randomize = TRUE)
DETAILS
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.vars 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. The extract.vars output is a dataframe .
A previous version of this function was named bugs.var.
ARGUMENTS:
bugs.out Output from an OpenBUGS or JAGS MCMC simulation. extract.vars assumes that this output was created by a call to one of the following functions: (i) a call to bugs in the R2OpenBUGS or R2WinBUGS package; (ii) a call to jags in the R2jags package; (iii) a call to the coda.samples or jags.samples function in the rjags package; (iv) or output from a previous call to extract.chains.
parameters If parameters = NA (default), extract.vars extracts samples for all parameters that were saved (monitored) in bugs.out. parameters can be set to a vector of variable names to extract a subset of the monitored variables.
burnin If burnin = 0 (default), no samples to be discarded. If burnin = n, then n samples are discarded from the initial segment of each chain prior to combining them into a vector. Note that the BUGS or JAGS run may have already discarded m burnin samples. If this has occurred, then the total number of burnin samples discarded will be m + n. Typically, the burnin samples will be discarded during the initial BUGS or JAGS run and no burnin samples will be discarded by extract.vars. Occasionally, no burnin samples are discarded during the initial BUGS or JAGS run because the user wishes to examine the initial segments of chains for possible lack of convergence. In this case, the burnin argument of extract.vars can be used to discard burnin samples from the chains of samples.
n.thin Indicates the thinning rate. n.thin = 1 indicates no thinning. Note that the BUGS or JAGS run may have already thinned the samples at a rate of m.thin. If this has occurred, the effective thinning rate from the MCMC sampling process will be m.thin*n.thin. Comments apply to n.thin that are analogous to the comments for burnin.
new.names If new.names = NA & keep.bugs.names == FALSE (default), the variable names created by BUGS or JAGS are converted to R-legal variable names. The R-legal names ared used as column names in the output dataframe. Set new.names to a character vector of names if alternative names are preferred.
keep.bugs.names If keep.bugs.names = TRUE, the variable names created by BUGS or JAGS are retained as column names in the extract.vars output, even if these names 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 If randomize = TRUE (default), the samples in the extract.vars output 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.
#-------------- The 'doc' bookmark highlights all of the documentation but not the function skeleton at the top of the file. Use rdocToString macro to convert documentation to an R string variable. Bkmk docStringsLoc = <\PATH\docStrings\> ---------------
Format for this html document: Page Size = Tabloid: 11" x 17". Note that Tabloid page size is available if Adobe PDF is set as the default printer, but not if the default printer is a physical printer that prints 8.5" x 11" standard paper. Table widths = 9.5"