coefsplot: Caterpillar plots of the regression coefficients from a boral model

Description

Constructs horizontal line plot (point estimate and HPD intervals), otherwise known as "caterpillar plots", for the column-specific regression coefficients corresponding to a covariate in X fitted in the boral model.

Usage

coefsplot(covname, x, labely = NULL, est = "median", ...)

Arguments

covname

The name of one of the covariates fitted in the boral model. That is, it must be a character vector corresponding to one of the elements in colnames(x)$X.coefs.median.

An object for class "boral".

labely

Controls the labels on the y-axis for the line plot. If it is not NULL, then it must be a vector either of length 1 or the same length as the number of columns in the y in the fitted boral object. In the former, it is treated as the y-axis label. In the latter, it is used in place of the column names of y to label each line. Defaults to NULL, in which the each line in the plot is labeled according to the columns of y, or equivalently rownames(x$X.coefs.median).

est

A choice of either the posterior median (est = "median") or posterior mean (est = "mean"), which are then used as the point estimates in the lines. Default is posterior median.

...

Additional graphical options to be included in. These include values for cex, cex.lab, cex.axis, cex.main, lwd, and so on.

Value

If SSVS was applied individually to each coefficient of X when fitting the boral model, then the posterior probabilities of including the specified covariate are printed out i.e., those from x$ssvs.indcoefs.mean.

Details

For each species (column of y), the horizontal line or "caterpillar" is constructed by first marking the point estimate (posterior mean or median) with an "x" symbol. Then the line is construed based on the lower and upper limits of the highest posterior density (HPD) intervals as found in x$hpdintervals. By default these intervals of 95% HPD intervals. To complete the plot, a vertical dotted line is drawn to denote the zero value. All HPD intervals that include zero are colored gray, while HPD intervals that exclude zero are colored black.

The graph is probably better explained by, well, plotting it using the toy example below =P

Thanks to Robert O'Hara for suggesting and providing the original code for this function.

Examples

Run this code

# NOT RUN {
## NOTE: The values below MUST NOT be used in a real application;
## they are only used here to make the examples run quick!!!
example_mcmc_control <- list(n.burnin = 10, n.iteration = 100, 
     n.thin = 1)

library(mvabund) ## Load a dataset from the mvabund package
data(spider)
y <- spider$abun
n <- nrow(y)
p <- ncol(y)

X <- scale(spider$x)
spiderfit_nb <- boral(y, X = X, family = "negative.binomial", 
    lv.control = list(num.lv = 2), mcmc.control = example_mcmc_control)


## Do separate line plots for all the coefficients of X
par(mfrow=c(2,3), mar = c(5,6,1,1))
sapply(colnames(spiderfit_nb$X), coefsplot, 
    spiderfit_nb)
# }
# NOT RUN {
# }