get.hpdintervals: Highest posterior density intervals for an boral model

Description

Calculates the lower and upper bounds of the highest posterior density intervals for parameters and latent variables in a fitted boral model.

Usage

get.hpdintervals(y, X = NULL, traits = NULL, row.ids = NULL, 
	fit.mcmc, lv.control, prob = 0.95, num.lv = NULL)

Arguments

The response matrix that the boral model was fitted to.

The model matrix used in the boral model. Defaults to NULL, in which case it is assumed no model matrix was used.

traits

The matrix of species traits used in the boral model. Defaults to NULL, in which case it is assumed no traits were included.

row.ids

A matrix with the number of rows equal to the number of rows in y, and the number of columns equal to the number of row effects to be included in the model. Element \((i,j)\) indicates to the cluster ID of row \(i\) in y for random effect eqnj; please see boral for details. Defaults to NULL, in which case iti assumed no random effects were included in the model.

fit.mcmc

All MCMC samples for the fitted boral model. These can be extracted by fitting an boral model using boral with save.model = TRUE, and then applying get.mcmcsamples(fit).

lv.control

A list (currently) with the following arguments:

num.lv: which specifies the number of true latent variables to generate. Defaults to 0.
type: which specifies the type the correlation structure of the latent variables (across sites). Defaults to independence correlation structure.
distmat: which a distance matrix required to calculate correlations across sites when a non-independence correlation structure on the latent variables is imposed.

Please see about.lvs for more information.

prob

A numeric scalar in the interval (0,1) giving the target probability coverage of the intervals. Defaults to 0.95.

num.lv

Old argument superceded by lv.control. Defaults to NULL and ignored.

Value

A list containing the following components where applicable:

lv.coefs

A three dimensional array giving the lower lv.coefs[,,"lower"] and upper lv.coefs[,,"upper"] bounds of the HPD intervals for the column-specific intercepts, latent variable coefficients, and dispersion parameters if appropriate.

A three dimensional array giving the lv.coefs[,,"lower"] and upper lv.coefs[,,"upper"] bounds of the HPD intervals for the latent variables.

lv.covparams

A matrix giving the lower and upper bounds of the HPD intervals for the parameters characterizing the correlation structure of the latent variables when they are assumed to be non-independent across rows.

row.coefs

A list with each element being a matrix giving the lower and upper bounds of the HPD intervals for row effects. The number of elements in the list should equal the number of row effects included in the model i.e., ncol(row.ids).

row.sigma

A list with each element being a vector giving the lower and upper bounds of the HPD interval for the standard deviation of the normal distribution for the row effects. The number of elements in the list should equal the number of row effects included in the model i.e., ncol(row.ids).

X.coefs

A three dimensional array giving the lower lv.coefs[,,"lower"] and upper lv.coefs[,,"upper"] bounds of the HPD intervals for coefficients relating to X.

traits.coefs

A three dimensional array giving the lower lv.coefs[,,"lower"] and upper lv.coefs[,,"upper"] bounds of the HPD intervals for coefficients and standard deviation relating to the traits matrix traits.

cutoffs

A matrix giving the lower and upper bounds of the HPD intervals for common cutoffs in proportional odds regression.

powerparam

A vector giving the lower and upper bounds of the HPD interval for common power parameter in tweedie regression.

Warnings

HPD intervals tend to be quite wide, and inference is somewhat tricky with them. This is made more difficult by the multiple comparison problem due to the construction one interval for each parameter!
Be very careful with interpretation of coefficients and HPD intervals if different columns of y have different distributions!
HPD intervals for the cutoffs in proportional odds regression may be poorly estimated for levels with few data.

Details

The function uses the HPDinterval function from the coda package to obtain the HPD intervals. See HPDinterval for details regarding the definition of the HPD interval.

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)
    
## Example 1 - model with two latent variables, site effects, 
## 	and no environmental covariates
spiderfit_nb <- boral(y, family = "negative.binomial", lv.control = list(num.lv = 2),
    row.eff = "fixed", save.model = TRUE, mcmc.control = example_mcmc_control)

## Returns a list with components corresponding to values described above.
spiderfit_nb$hpdintervals 

## Example 2 - model with two latent variable, site effects, 
## 	and environmental covariates
spiderfit_nb2 <- boral(y, X = spider$x, family = "negative.binomial", 
    lv.control = list(num.lv = 2), row.eff = "fixed", save.model = TRUE,
    mcmc.control = example_mcmc_control)

## Returns a list with components corresponding to values described above.
spiderfit_nb2$hpdintervals 

# }

Run the code above in your browser using DataCamp Workspace