get.hpdintervals: Highest posterior density intervals for a fitted model
In emitanaka/boral: Bayesian Ordination and Regression AnaLysis

Description Usage Arguments Details Value Warnings Note Author(s) Examples

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

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

`y`	The response matrix that the model was fitted to.
`X`	The model matrix used in the model. Defaults to `NULL`, in which case it is assumed no model matrix was used.
`traits`	The matrix of species traits used in the 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 model. These can be extracted by fitting a 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.

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.

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.
`lv`	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.

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.

boral fits the model and returns the HPD intervals by default.

Maintainer: NA

## 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 


## End(Not run)