Extract residual correlations based on latent factors from a fitted jsdgam

Compute residual correlation estimates from Joint Species Distribution jsdgam models using latent factor loadings

Usage

residual_cor(object, ...)

# S3 method for jsdgam
residual_cor(
  object,
  summary = TRUE,
  robust = FALSE,
  probs = c(0.025, 0.975),
  ...
)

Arguments

object: list object of class mvgam resulting from a call to jsdgam()
...: ignored
summary: Should summary statistics be returned instead of the raw values? Default is TRUE..
robust: If FALSE (the default) the mean is used as a measure of central tendency. If TRUE, the median is used instead. Only used if summary is TRUE
probs: The percentiles to be computed by the quantile function. Only used if summary is TRUE.

Value

If summary = TRUE, 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 credible intervals supplied to probs
sig_cor: A \(p \times p\) correlation matrix containing only those correlations whose credible interval does not contain zero. All other correlations are set to zero
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 credible intervals supplied to probs
sig_prec: A \(p \times p\) precision matrix containing only those precisions whose credible interval does not contain zero. All other precisions are set to zero
cov: A \(p \times p\) posterior median or mean covariance matrix
trace: The median/mean point estimator of the trace (sum of the diagonal elements) of the residual covariance matrix cov

If summary = FALSE, this function returns a list containing the following components:

all_cormat: A \(n_{draws} \times p \times p\) array of posterior residual correlation matrix draws
all_covmat: A \(n_{draws} \times p \times p\) array of posterior residual covariance matrix draws
all_presmat: A \(n_{draws} \times p \times p\) array of posterior residual precision matrix draws
all_trace: A \(n_{draws}\) vector of posterior covariance trace draws

Details

Hui (2016) provides an excellent description of the quantities that this function calculates, so this passage is heavily paraphrased from his associated boral package.

In Joint Species Distribution Models, the residual covariance matrix is calculated based on the matrix of latent factor loading matrix \(\Theta\), where the residual covariance matrix \(\Sigma = \Theta\Theta'\). A strong residual covariance/correlation matrix between two species can 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 captured in formula.

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 are not directly associated, 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 may imply 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 [\Theta\Theta']_{jj}\). Often used in other areas of multivariate statistics, the trace may be interpreted as the amount of covariation explained by the latent factors. One situation where the trace may be useful is when comparing a pure latent factor model (where no terms are suppled to formula) versus a model with latent factors and some additional predictors in formula -- the proportional difference in trace between these two models may be interpreted as the proportion of covariation between species explained by the predictors in formula. Of course, the trace itself is random due to the MCMC sampling, and so it is not always guaranteed to produce sensible answers.

References

Francis KC Hui (2016). BORAL - Bayesian ordination and regression analysis of multivariate abundance data in R. Methods in Ecology and Evolution. 7, 744-750.

Otso 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.

Author

Nicholas J Clark