boral (version 2.0.2)

get.enviro.cor: Extract covariances and correlations due to shared environmental responses

Description

lifecycle::badge("stable")

Calculates the correlation between columns of the response matrix, due to similarities in the response to explanatory variables i.e., shared environmental response.

Usage

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

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\(\times\)prob) % HPD interval.

sig.cor

A \(p \times p\) correlation matrix containing only the ``significant" correlations whose (100\(\times\)prob) % HPD interval does not contain zero. All non-significant correlations are set to zero.

cov

A \(p \times p\) covariance matrix.

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 are "significant". Defaults to 0.95.

Author

tools:::Rd_package_author("boral")

Maintainer: tools:::Rd_package_maintainer("boral")

Details

In both independent response and correlated response models, where the each of the columns of the response matrix \(\bm{Y}\) are fitted to a set of covariates, the covariance and thus between two columns \(j\) and \(j'\) due to similarities in their response to the model matrix is calculated based on the linear predictors \(\bm{x}^\top_i\bm{\beta}_j\) and \(\bm{x}^\top_i\bm{\beta}_{j'})\), where \(\bm{\beta}_j\) are response-specific coefficients relating to the explanatory variables.

For multivariate abundance data, the correlation calculated by this function can be interpreted as the correlation attributable to similarities in the environmental response between species. Such correlation matrices are discussed and found in Ovaskainen et al., (2010), Pollock et al., 2014.

Please note this correlation calculation does not include any row effects or any response-specific random intercepts.

References

• Ovaskainen et al. (2010). Modeling species co-occurrence by multivariate logistic regression generates new hypotheses on fungal interactions. Ecology, 91, 2514-2521.

• 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.residual.cor, which calculates the residual correlation matrix for models involving latent variables.

Examples

if (FALSE) {
## 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
X <- scale(spider$x)
n <- nrow(y)
p <- ncol(y)
    
spiderfit_nb <- boral(y, X = X, family = "negative.binomial", 
     save.model = TRUE, mcmc.control = example_mcmc_control,
     model.name = testpath)

enviro.cors <- get.enviro.cor(spiderfit_nb)

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