get.residual.cor: Extract residual correlations and precisions from models

In boral: Bayesian Ordination and Regression AnaLysis

Extract residual correlations and precisions from models

Description

\Sexpr[results=rd, stage=render]{lifecycle::badge("stable")}

Calculates the residual correlation and precision matrices from models that include latent variables.

Usage

get.residual.cor(object, est = "median", prob = 0.95)

Arguments

object	An object for class "boral".
est	A choice of either the posterior median (est = "median") or posterior mean (est = "mean"), which are then treated as estimates and the fitted values are calculated from. Default is posterior median.
prob	A numeric scalar in the interval (0,1) giving the target probability coverage of the intervals, by which to determine whether the correlations and precisions are "significant". Defaults to 0.95.

Details

In models with latent variables, the residual covariance matrix is calculated based on the matrix of latent variables regression coefficients formed by stacking the rows of \bm{\theta}_j. That is, if we denote \bm{\Theta} = (\bm{\theta}_1 \ldots \bm{\theta}_p)', then the residual covariance and hence residual correlation matrix is calculated based on \bm{\Theta}\bm{\Theta}'.

For multivariate abundance data, the inclusion of latent variables provides a parsimonious method of accounting for correlation between species. Specifically, the linear predictor,

\beta_{0j} + \bm{x}^\top_i\bm{\beta}_j + \bm{u}^\top_i\bm{\theta}_j

is normally distributed with a residual covariance matrix given by \bm{\Theta}\bm{\Theta}'. A strong residual covariance/correlation matrix between two species can then be interpreted as evidence of species interaction (e.g., facilitation or competition), missing covariates, as well as any additional species correlation not accounted for by shared environmental responses (see also Pollock et al., 2014, for residual correlation matrices in the context of Joint Species Distribution Models). If random effects \bm{z}^\top_i\bm{b}_j are also included in the model, then the latent variables induce a residual covariance/correlation between responses than is conditional on this.

The residual precision matrix (also known as partial correlation matrix, Ovaskainen et al., 2016) is defined as the inverse of the residual correlation matrix. The precision matrix is often used to identify direct or causal relationships between two species e.g., two species can have a zero precision but still be correlated, which can be interpreted as saying that two species do not directly interact, but they are still correlated through other species. In other words, they are conditionally independent given the other species. It is important that the precision matrix does not exhibit the exact same properties of the correlation e.g., the diagonal elements are not equal to 1. Nevertheless, relatively larger values of precision imply a stronger direct relationships between two species.

In addition to the residual correlation and precision matrices, the median or mean point estimator of trace of the residual covariance matrix is returned, \sum\limits_{j=1}^p [\bm{\Theta}\bm{\Theta}']_{jj}. Often used in other areas of multivariate statistics, the trace may be interpreted as the amount of covariation explained by the latent variables. One situation where the trace may be useful is when comparing a pure LVM versus a model with latent variables and some predictors (correlated response models) – the proportional difference in trace between these two models may be interpreted as the proportion of covariation between species explained by the predictors. Of course, the trace itself is random due to the MCMC sampling, and so it is not always guranteed to produce sensible answers!

Value

A list with the following components:

cor, cor.lower, cor.upper	A set of p \times p correlation matrices, containing either the posterior median or mean estimate plus lower and upper limits of the corresponding (100\timesprob) % HPD interval.
sig.cor	A p \times p correlation matrix containing only the “significant" correlations whose (100\timesprob) % HPD interval does not contain zero. All non-significant correlations are set to zero.
cov	A p \times p covariance matrix.
prec, prec.lower, prec.upper	A set of p \times p precision matrices, containing either the posterior median or mean estimate plus lower and upper limits of the corresponding (100\timesprob) % HPD interval.
sig.prec	A p \times p residual precision matrix containing only the “significant" precisions whose (100\timesprob) % HPD interval does not contain zero. All non-significant precision are set to zero.
trace	The median/mean point estimator of the trace (sum of the diagonal elements) of the residual covariance matrix.

Note

Residual correlation and precision matrices are reliably modeled only with two or more latent variables i.e., num.lv > 1 when fitting the model using boral.

Author(s)

Francis K.C. Hui [aut, cre], Wade Blanchard [aut]

Maintainer: Francis K.C. Hui <[e-mail]>

References

• Ovaskainen et al. (2016). Using latent variable models to identify large networks of species-to-species associations at different spatial scales. Methods in Ecology and Evolution, 7, 549-555.

• Pollock et al. (2014). Understanding co-occurrence by modelling species simultaneously with a Joint Species Distribution Model (JSDM). Methods in Ecology and Evolution, 5, 397-406.

See Also

get.enviro.cor, which calculates the correlation matrix due to similarities in the response to the explanatory variables (i.e., similarities due to a shared environmental response).

Examples

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

testpath <- file.path(tempdir(), "jagsboralmodel.txt")


library(mvabund) ## Load a dataset from the mvabund package
library(corrplot) ## For plotting correlations
data(spider)
y <- spider$abun
n <- nrow(y)
p <- ncol(y)
    
spiderfit_nb <- boral(y, X = spider$x, family = "negative.binomial", 
    lv.control = list(num.lv = 2), save.model = TRUE, 
    mcmc.control = example_mcmc_control, model.name = testpath)

res.cors <- get.residual.cor(spiderfit_nb)

corrplot(res.cors$sig.cor, title = "Residual correlations", 
    type = "lower", diag = FALSE, mar = c(3,0.5,2,1), tl.srt = 45)

## End(Not run)

boral documentation built on May 29, 2024, 12:30 p.m.