Package 'boa'

Description

Computes lag autocorrelations for the parameters in an MCMC sequence.

Usage

boa.acf(link, lags)

Arguments

Value

A matrix whose columns and rows contain the estimated autocorrelation functions at the specified lags and the monitored parameters, respectively.

Author(s)

Brian J. Smith

See Also

boa.plot, boa.plot.acf, boa.print.acf

Description

Extracts and sets the MCMC sequence(s) stored internally for use during a BOA session. Users can safely use this function to extract data. However, it should not be called directly to modify the stored MCMC sequence(s). Instead, data management should accomplished with the libboa.chain functions.

Usage

boa.chain(...)

Arguments

Value

If no arguments are supplied, a list of the current values is returned. If a character string is given, the current value of the named variable is returned. Otherwise, no values are returned.

Parameter Names and Default Values

master = list()

Master list containing all added MCMC sequences. Sequences may only be added to or deleted from the master list. The sequences in this list are never modified or used in any of the analyses. It serves as a template for the working list described below. The parameters and iterations may differ between the sequences. Each element in the list is a matrix whose columns and rows contain the monitored parameters and the MCMC iterations, respectively. The iteration numbers and parameter names are stored in the dimnames.

master.support = list()

List containing the support for each of the parameters in 'master'. Each element in the list is a matrix whose columns and rows contain the monitored parameters and the support (lower and upper limits), respectively. The default for each parameter is c(-Inf, Inf).

work = master

Working list used in all analyses. This list is essentially a modifiable copy of 'master'. All data management functions operate on the working list.

work.support = master.support

List containing the support for each of the parameters in 'work'.

work.sync = TRUE

Logical value indicating that the working list is an identical copy of the master list. This variable is automatically set to F after a successful call to boa.chain.subset or boa.chain.collapse. While work.sync = F, only the master list will be updated if MCMC sequences are added or deleted. A call to boa.chain.reset will reset this variable to T and copy the master list to the working list.

Side Effects

When variables are set, boa.chain() modifies the internal list .boa.chain. If boa.chain() is called with either a list as the single argument, or with one or more arguments in the <name> = <value> form, the variables specified by the names in the arguments are modified.

Author(s)

Brian J. Smith

Description

Adds an MCMC sequence to the session lists of sequences. Most users should not call this function directly. Passing improperly formatted data to this function will most likely break the functions in this library. The preferred method of adding a new sequence is to call the function boa.chain.import.

Usage

boa.chain.add(link, lname)

Arguments

Value

A logical value indicating that 'link' has been successfully added.

Author(s)

Brian J. Smith

See Also

boa.chain.import

Description

Concatenates together all of the MCMC sequences in the working session list of sequences. Only those parameters common to all sequences are kept.

Usage

boa.chain.collapse()

Value

A logical value indicating that the MCMC sequences have been collapsed. If the sequences share no common parameters, no modifications are made to the working list and FALSE is returned.

Author(s)

Brian J. Smith

See Also

codeboa.chain.reset, codeboa.chain.subset

Description

Delete MCMC sequences from the session list of sequences.

Usage

boa.chain.del(lnames, pnames)

Arguments

Side Effects

The specified MCMC sequences are deleted from the session lists of sequences.

Author(s)

Brian J. Smith

Description

Evaluates a user-specified expression to formulate a new parameter in each of the system lists of MCMC sequences.

Usage

boa.chain.eval(expr, pname)

Arguments

Side Effects

The specified parameter is added to the session lists of MCMC sequences.

Author(s)

Brian J. Smith

Description

Computes the Gelman and Rubin convergence diagnostics for a list of MCMC sequences. Estimates are calculated from the second half of each sequence.

Usage

boa.chain.gandr(chain, chain.support, alpha, pnames, window, to)

Arguments

Value

Author(s)

Brian J. Smith, Nicky Best, Kate Cowles

References

1. Brooks, S. and Gelman, A. (1998). General methods for monitoring convergence of iterative simulations. Journal of Computational and Graphical Statistics, 7(4), 434-55.

2. Gelman, A. and Rubin, D. B. (1992). Inference from iterative simulation using multiple sequences. Statistical Science, 7, 457-72.

See Also

boa.plot, boa.plot.bandg, boa.plot.gandr, boa.print.gandr

Description

Reads an MCMC sequence from an external file and adds it to the session lists of sequences.

Usage

boa.chain.import(prefix, path = boa.par("path"), type = "ASCII")

Arguments

Value

A logical value indicating that the specified file(s) has been successfully imported.

Side Effects

The imported MCMC sequence is automatically added to the session lists of sequences via a call to boa.chain.add.

Author(s)

Brian J. Smith

See Also

boa.chain.add, boa.importASCII, boa.importBUGS

Description

Returns summary information from a list of MCMC sequences.

Usage

boa.chain.info(chain, chain.support)

Arguments

Value

Author(s)

Brian J. Smith

See Also

boa.print.info

Description

Returns the data in the working list of MCMC sequences to the state it was in when originally imported. This function undoes any subsetting or collapsing that was done via the boa.chain.collapse or boa.chain.subset functions.

Usage

boa.chain.reset()

Side Effects

Returns the data in the working list of MCMC sequences to the state it was in when originally imported. This function undoes any subsetting or collapsing that was done via the boa.chain.collapse or boa.chain.subset functions.

Author(s)

Brian J. Smith

See Also

boa.chain.collapse, boa.chain.subset

Description

Selects a subset of the MCMC sequences stored in the working session list of sequences.

Usage

boa.chain.subset(lnames, pnames, iter)

Arguments

Value

A logical value indicating that the data has been successfully subsetted. If the requested subset contains no data, the working session list is not modified and FALSE is returned.

Side Effects

The subsetted data, if not an empty set, is copied to the working session list of MCMC sequences used in all analyses.

Author(s)

Brian J. Smith

See Also

boa.chain.collapse, boa.chain.reset

Description

Modifies the support (range of possible values) for the parameters in the session lists of MCMC sequences.

Usage

boa.chain.support(lnames, pnames, limits)

Arguments

Value

A logical vector with two elements indicating that the support has been changed for variables in the master list and working list of MCMC sequences, respectively.

Side Effects

The support for each of the specified parameters is changed in the session lists of MCMC sequences.

Author(s)

Brian J. Smith

Description

Computes the Geweke convergence diagnostics for the parameters in an MCMC sequence.

Usage

boa.geweke(link, p.first, p.last)

Arguments

Value

A matrix whose columns contain the Z-Scores and associated p-values and whose rows contain the monitored parameters.

Author(s)

Brian J. Smith

References

Geweke, J. (1992). Evaluating the accuracy of sampling-based approaches to calculating posterior moments. In Bayesian Statistics 4, (ed. J. M. Bernardo, J. O. Berger, A. P. Dawid, and A. F. M. Smith). Clarendon Press, Oxford, UK.

See Also

boa.plot, boa.plot.geweke, boa.print.geweke

Description

Computes the Heidleberger and Welch convergence diagnostics for the parameters in an MCMC sequence.

Usage

boa.handw(link, error, alpha)

Arguments

Value

A matrix whose columns and rows are the Heidleberger and Welch convergence diagnostics (i.e. stationarity test, number of iterations to keep and to drop, Cramer-von-Mises statistic, halfwidth test, mean, and halfwidth) and the monitored parameters, respectively.

Author(s)

Brian J. Smith, Nicky Best, Kate Cowles

References

Heidelberger, P. and Welch, P. (1983). Simulation run length control in the presence of an initial transient. Operations Research, 31, 1109-44.

See Also

boa.print.handw

Description

Estimates the highest probability density (HPD) interval for the given parameter draws. Uses the Chen and Shao algorithm assuming a unimodal marginal posterior distribution.

Usage

boa.hpd(x, alpha)

Arguments

Value

A vector containing the lower and upper bound of the HPD interval, labeled "Lower Bound" and "Upper Bound", respectively.

Author(s)

Brian J. Smith

References

Chen, M-H. and Shao, Q-M. (1999). Monte Carlo estimation of Bayesian credible and HPD intervals. Journal of Computational and Graphical Statistics, 8(1), 69-92.

Description

Import data from an ASCII text file. The variables and iterations should appear in the columns and rows, respectively, of the file. The variable names must be given in the first row. The iteration numbers are taken from the the column entitled "iter" (case-sensitive), if it exists; otherwise, the numbers 1..n are used, where n is the number of rows. The columns may be separated by white space or tabs.

Usage

boa.importASCII(prefix, path = NULL)

Arguments

Value

If the data is successfully imported, a matrix is returned whose columns and rows contain the monitored parameters and the MCMC iterations, respectively. The iteration numbers and parameter names are stored in the dimnames of the returned matrix. Otherwise, NULL is returned.

Author(s)

Brian J. Smith

See Also

boa.chain.import, boa.importBUGS, boa.importMatrix

Description

Import data from BUGS output files.

Usage

boa.importBUGS(prefix, path = NULL)

Arguments

Value

If the data is successfully imported, a matrix is returned whose columns and rows contain the monitored parameters and the MCMC iterations, respectively. The iteration numbers and parameter names are stored in the dimnames of the returned matrix. Otherwise, NULL is returned.

Author(s)

Brian J. Smith

See Also

boa.chain.import, boa.importASCII, boa.importMatrix

Description

Import data from an S numeric matrix object. The variables and iterations should appear in the columns and rows, respectively, of the matrix. The variable names and iteration numbers may be optionally specified in the dimnames of the matrix object. Otherwise, the iterations will be numbered 1..n, where n is the number of rows.

Usage

boa.importMatrix(prefix)

Arguments

Value

If the data is successfully imported, a matrix is returned whose columns and rows contain the monitored parameters and the MCMC iterations, respectively. The iteration numbers and parameter names are stored in the dimnames of the returned matrix. Otherwise, NULL is returned.

Author(s)

Brian J. Smith

See Also

boa.chain.import, boa.importASCII, boa.importBUGS

Description

boa.init() is the first function called to start a BOA session when using the command-line. It sets up the internal data structures and initializes them with the appropriate default values.

Usage

boa.init(recover = FALSE)

Arguments

Author(s)

Brian J. Smith

See Also

boa.load, boa.quit

Description

Loads the data and global parameter settings from a previously saved BOA session.

Usage

boa.load(name, envir = globalenv())

Arguments

Value

A logical value indicating that the object was successfully loaded.

Author(s)

Brian J. Smith

Description

Starts the interactive menu for BOA. Provides a menu-driven interface to all of the convergence diagnostics and statistical and graphical analysis tools.

Usage

boa.menu(recover = FALSE)

Arguments

Warning

Do not use the recover argument unless starting the menu immediately after a crash.

Note

boa.menu is the only function in the BOA library that need be called in order to use the menu-driven interface.

Author(s)

Brian J. Smith

Examples

## Not run: 
## Start the menu system
boa.menu()

## End(Not run)

Description

Displays and sets the global parameters stored internally for use during a BOA session.

Usage

boa.par(...)

Arguments

Value

If no arguments are supplied, a list of the current values is returned. If a character string is given, the current value of the named variable is returned. Otherwise, a list of the named variables and their old values is returned, but not printed.

Parameter Names and Default Values

acf.lags = c(1, 5, 10, 50)

Numeric vector of lags at which to estimate the autocorrelation function.

alpha = 0.05

Type I error rate used for all statistical tests and confidence intervals.

ASCIIext = ".txt"

Character string giving the filename extension used when importing ASCII files.

bandwidth = function(x) 0.5 * diff(range(x)) / (log(length(x)) + 1)

Function for computing the bandwidth used in estimating the density functions for parameters. This should take one argument which is a numeric vector of data on which density estimation is to be performed. A constant bandwidth may be specified by having this function return the desired constant.

batch.size = 50

Number of iterations to include in each batch when computing batch means and lag-1 batch autocorrelations. The batch size has the single largest impact on the time required to compute summary statistics. The computation time is decreased dramatically as the batch size increases. Consequently, users may want to increase the value of this variable for long MCMC sequences.

dev = <<see below>>

Character string giving the name of the function that creates graphics windows on the current platform. For Unix systems this is either "motif", "openlook", or "X11". The default is "motif" for the UNIX S-PLUS, "win.graph" for Windows S-PLUS, "X11" for UNIX R, and "windows" for Windows R.

dev.list = numeric(0)

Numeric vector containing the active graphics windows in use by the program. This is automatically maintained by the program, user should not directly modify this variable.

gandr.bins = 20

Number of line segments within the MCMC sequence at which to plot the Gelman and Rubin shrink factors.

gandr.win = 0.50

Proportion of iterations to include in the Brooks, Gelman, and Rubin Statistics.

geweke.bins = 10

Number of line segments within the MCMC sequence at which to plot the Geweke convergence diagnostics.

geweke.first = 0.1

Proportion of iterations to include in the first window when computing the Geweke convergence diagnostics.

geweke.last = 0.5

Proportion of iterations to include in the last window when computing the Geweke convergence diagnostics.

handw.error = 0.1

Accuracy of the posterior estimates when computing the Heidleberger and Welch convergence diagnostics.

kernel = "gaussian"

Character string giving the type of window used in estimating the density functions for parameters. Other choices are "cosine", "rectangular", or "triangular".

legend = TRUE

Logical value indicating that a legend be included in the plots.

path = ""

Character string giving the directory path in which the raw data files are stored. The default may be used if the files are located in the current working directory. The specified path should not end with a slash(es).

par = list()

List specifying graphics parameters passed to the par function for the construction of new plots.

plot.mfdim = c(3, 2)

Numeric vector giving the maximum number of rows and columns, respectively, of plots to include in a single graphics window.

plot.new = F

Logical value indicating that a new graphics window be automatically opened upon successive calls to boa.plot(). Otherwise, previous graphics windows will be closed.

plot.onelink = FALSE

Logical value indicating that each plot should include only one MCMC sequence. Otherwise, all sequences are displayed on the same plot.

quantiles = c(0.025, 0.5, 0.975)

Vector of probabilities at which to compute the quantiles. Values must be between 0 and 1.

randl.error = 0.005

Desired amount of error in estimating the quantile specified in the Raftery and Lewis convergence diagnostics.

randl.delta = 0.001

Delta valued used in computing the Raftery and Lewis convergence diagnostics.

randl.q = 0.025

Quantile to be estimated in computing the Raftery and Lewis convergence diagnostics.

title = TRUE

Logical value indicating that a title be added to the plots.

Side Effects

When variables are set, boa.par() modifies the internal list .boa.par. If boa.par() is called with either a list as the single argument, or with one or more arguments in the <name> = <value> form, the variables specified by the names in the arguments are modified.

Author(s)

Brian J. Smith

Description

Automatically generates the specified plot type for all parameters in the working session list of MCMC sequences. This function takes care of all the plotting tasks - opening windows, setting the number of plots per page, and adding titles.

Usage

boa.plot(type, dev = boa.par("dev"), mfdim = boa.par("plot.mfdim"),
newplot = boa.par("plot.new"), onelink = boa.par("plot.onelink"),
title = boa.par("title"))

Arguments

Value

A logical value indicating that the plots were successfully created.

Author(s)

Brian J. Smith

See Also

boa.plot.acf, boa.plot.bandg, boa.plot.density, boa.plot.gandr, boa.plot.geweke, boa.plot.history, boa.plot.trace

Description

Creates a single plot of the lag autocorrelations for a specified parameter.

Usage

boa.plot.acf(lname, pname, annotate = boa.par("legend"))

Arguments

Value

A logical value indicating that the plot was successfully created.

Author(s)

Brian J. Smith

See Also

boa.acf, boa.print.acf

Description

Plots the Brooks and Gelman multivariate shrink factors within different line segments across the MCMC sequences. This diagnostic is a multivariate extension to the Gelman and Rubin shrink factors.

Usage

boa.plot.bandg(bins = boa.par("gandr.bins"), win = boa.par("gandr.win"),
annotate = boa.par("legend"))

Arguments

Value

A logical value indicating that the plot was successfully created.

Author(s)

Brian J. Smith

See Also

boa.chain.gandr, boa.plot, boa.plot.gandr, boa.print.gandr

Description

Estimates and displays, in a single plot, the density function(s) for the specified parameter(s).

Usage

boa.plot.density(lnames, pname, bandwidth = boa.par("bandwidth"),
window = boa.par("kernel"), annotate = boa.par("legend"))

Arguments

Value

A logical value indicating that the plot was successfully created.

Author(s)

Brian J. Smith

See Also

boa.plot

Description

Creates a single plot of the Gelman and Rubin shrink factors within different line segments for a parameter in an MCMC sequence.

Usage

boa.plot.gandr(pname, bins = boa.par("gandr.bins"), alpha = boa.par("alpha"),
win = boa.par("gandr.win"), annotate = boa.par("legend"))

Arguments

Value

A logical value indicating that the plot was successfully created.

Author(s)

Brian J. Smith

See Also

boa.chain.gandr, boa.plot, boa.plot.bandg, boa.print.gandr

Description

Creates a single plot of the Geweke convergence diagnostics within different line segments for a parameter in an MCMC sequence.

Usage

boa.plot.geweke(lname, pname, bins = boa.par("geweke.bins"),
                p.first = boa.par("geweke.first"), p.last = boa.par("geweke.last"),
                alpha = boa.par("alpha"), annotate = boa.par("legend"))

Arguments

Value

A logical value indicating that the plot was successfully created.

Author(s)

Brian J. Smith, Nicky Best, Kate Cowles

See Also

boa.geweke, boa.plot, boa.print.geweke

Description

Computes and displays, in a single plot, the running mean(s) for the specified parameter(s).

Usage

boa.plot.history(lnames, pname, annotate = boa.par("legend"))

Arguments

Value

A logical value indicating that the plot was successfully created.

Author(s)

Brian J. Smith

See Also

boa.plot

Description

Set Plotting Parameters

Usage

boa.plot.par(mfdim = c(1, 1), title = TRUE)

Arguments

Author(s)

Brian J. Smith

Description

Adds a title to the graphics window. This function should be called after all plots have been added to the target graphics window.

Usage

boa.plot.title(text)

Arguments

Author(s)

Brian J. Smith

Description

Displays, in a single plot, the trace histories for the specified parameter(s).

Usage

boa.plot.trace(lnames, pname, annotate = boa.par("legend"))

Arguments

Value

A logical value indicating that the plot was successfully created.

Author(s)

Brian J. Smith

See Also

boa.plot

Description

Iteratively calls boa.acf() to display the lag autocorrelations for the parameters in each of the MCMC sequences in the working session list of sequences.

Usage

boa.print.acf(lags = boa.par("acf.lags"))

Arguments

Author(s)

Brian J. Smith

See Also

boa.acf, boa.plot, boa.plot.acf

Description

Iteratively computes and displays the correlation matrices for the parameters in each of the MCMC sequences in the working session list of sequences.

Usage

boa.print.cor()

Author(s)

Brian J. Smith

Description

Calls boa.chain.gandr() and displays the Gelman and Rubin convergence diagnostics for the MCMC sequences in the working session list of sequences.

Usage

boa.print.gandr(alpha = boa.par("alpha"), win = boa.par("gandr.win"))

Arguments

Author(s)

Brian J. Smith

See Also

boa.chain.gandr, boa.plot, boa.plot.bandg, boa.plot.gandr

Description

Iteratively calls boa.geweke() to display the Geweke convergence diagnostics for the parameters in each of the MCMC sequences in the working session list of sequences.

Usage

boa.print.geweke(p.first = boa.par("geweke.first"), p.last = boa.par("geweke.last"))

Arguments

Author(s)

Brian J. Smiht

See Also

boa.geweke, boa.plot, boa.plot.geweke

Description

Iteratively calls boa.handw() to display the Heidelberger and Welch convergence diagnostics for the parameters in each of the MCMC sequences in the working session list of sequences.

Usage

boa.print.handw(error = boa.par("handw.error"), alpha = boa.par("alpha"))

Arguments

Author(s)

Brian J. Smith

See Also

boa.handw

Description

Iteratively calls boa.hpd() to display the highest probability density (HPD) intervals for the parameters in each of the MCMC sequences in the working session list of sequences.

Usage

boa.print.hpd(alpha = boa.par("alpha"))

Arguments

Author(s)

Brian J. Smith

See Also

boa.hpd

Description

Iteratively calls boa.chain.info() to display information from the MCMC sequences in the specified session list of sequences.

Usage

boa.print.info(which = "work")

Arguments

Value

The full list obtained from boa.chain.info() is returned, but not printed.

Author(s)

Brian J. Smith

See Also

boa.chain.info

Description

Displays a description of and the current value for all global parameters.

Usage

boa.print.par(group)

Arguments

Value

The character matrix obtained from boa.pardesc() is returned, but not printed.

Author(s)

Brian J. Smith

See Also

boa.pardesc

Description

Iteratively calls boa.randl() to display the Raftery and Lewis convergence diagnostics for the parameters in each of the MCMC sequences in the working session list of sequences.

Usage

boa.print.randl(q = boa.par("randl.q"), error = boa.par("randl.error"),
                prob = 1 - boa.par("alpha"), delta = boa.par("randl.delta"))

Arguments

Author(s)

Brian J. Smith

See Also

boa.randl

Description

Iteratively calls boa.stats() to display summary statistics for the parameters in each of the MCMC sequences in the working session list of sequences.

Usage

boa.print.stats(probs = boa.par("quantiles"), batch.size = boa.par("batch.size"))

Arguments

Author(s)

Brian J. Smith

See Also

boa.stats

Description

boa.quit() is called to end a BOA session. It removes the objects used to store the session lists of MCMC sequences and the global parameters. Failure to do this may result in lost or lingering data.

Usage

boa.quit()

Author(s)

Brian J. Smith

See Also

boa.save, boa.init

Description

Computes the Raftery and Lewis convergence diagnostics for the parameters in an MCMC sequence.

Usage

boa.randl(link, q, error, prob, delta)

Arguments

Value

A matrix whose columns and rows are the Raftery and Lewis convergence diagnostics (i.e. thin, burn-in, total, lower bound, and dependence factor) and the monitored parameters, respectively.

Author(s)

Brian J. Smith, Nicky Best, Kate Cowles

References

1. Raftery, A. L. and Lewis, S. (1992a). Comment: One long run with diagnostics: Implementation strategies for Markov chain Monte Carlo. Statistical Science, 7, 493-7.

2. Raftery, A. L. and Lewis, S. (1992b). How many iterations in the Gibbs sampler? In Bayesian Statistics 4, (ed. J. M. Bernardo, J. O. Berger, A. P. Dawid, and A. F. M. Smith), pp. 763-74. Oxford University Press.

See Also

boa.print.randl

Description

Save the current state of the session lists of MCMC sequences and the global parameters to a database object.

Usage

boa.save(name, envir = globalenv(), replace = FALSE)

Arguments

Value

A logical value indicating that the session was successfully saved to the specified object.

Author(s)

Brian J. Smith

Description

Computes summary statistics for the parameters in an MCMC sequence.

Usage

boa.stats(link, probs, batch.size)

Arguments

Value

A matrix whose columns and rows contain the summary statistics (i.e. sample mean, standard deviation, naive standard error, MC error, batch standard error, lag-1 batch autocorrelation, specified quantiles, minimum and maximum iteration numbers, and total iterations in the sample) and the monitored parameters, respectively.

Author(s)

Brian J. Smith

See Also

boa.print.stats

Description

The Line example involves a linear regression analysis of the data points (1,1), (2,3), (3,3), (4,3), and (5,5). The proposed Bayesian model is

$y[i] ~ N(mu[i], tau)$

$mu[i] = alpha + beta * (x[i] - mean(x[]))$

with the following priors:

$alpha ~ N(0, 0.0001)$

$beta ~ N(0, 0.0001)$

$tau ~ Gamma(0.001, 0.001)$

Two parallel chains from the MCMC sampler were generated and the output saved in the S data frames line1 and line2.

Usage

data(line)

Format

The data frames line1 and line2 each containing 200 observations.

References

Spiegelhalter, D., Thomas, A. and Best, N., (2000). WinBugs Version 1.4 User Manual.