make_netassoc_network: Infer species-association network

Description Usage Arguments Details Value See Also Examples

View source: R/make_netassoc_network.R

Description

Infers a species association network by determining which co-occurrence patterns between species are more or less likely than expected under a null model of community assembly. Defaults to estimation of association using a robust shrinkage estimator for inverse covariance matrices.

Usage

1
2
3
4
make_netassoc_network(obs, nul=vegan::permatfull(obs)$perm[[1]], 
  method="partial_correlation", args=list(method="shrinkage",verbose=FALSE),
  p.method="fdr", alpha=0.05, numnulls=1000, 
  plot=TRUE,plot.legend=TRUE, plot.title=TRUE, verbose=TRUE)

Arguments

obs

A m x n community matrix describing the abundance or presence/absence of m species at n sites. Represents the observed data.

nul

A m x n community matrix describing the abundance or presence/absence of m species at n sites. Represents the regional null expectation data. The default value is a resampling of the observed data that preserves row and column sums, but this default method is not recommended.

method

The name of a function used to calculate relationships between species. The function must accept at least the arguments mat, a m x n (species x site) matrix. Defaults to partial_correlation.

args

A list of additional arguments to be passed to the method function.

p.method

The method used to correct p-values for multiple comparisons. See p.adjust for options.

alpha

Analysis-wide Type I error rate, controlled via the argument p.method.

numnulls

Number of resamples of the nul matrix used to assemble null communities. Larger values produce more accurate results.

plot

If TRUE, plots all intermediate matrices calculated by the algorithm. Can be used to visualize input and output.

plot.title

If TRUE, adds titles to diagnostic plots.

plot.legend

If TRUE, adds legends to diagnostic plots.

verbose

If TRUE, prints status updates and progress bars during calculations.

Details

Steps taken are:

1) obtaining input data and trimming to eliminate species that do not occur in any site 2) resampling a set of null community matrices from the expectation with the same richness and abundance as the observed community 3) calculating species co-occurrence scores for each pair of species within the observed matrix and all resampled null matrices 4) calculating standardized effect sizes and p-values for species' co-occurrence scores 5) thresholding effect sizes to retain only significant associations 6) converting matrix of scores to association network

The resulting network can be analyzed using functions from the igraph network package.

The user should specify a nul matrix of the same dimensionality as obs based on some regional distribution modeling approach (e.g. MaxEnt). The default reshuffling method is not recommended but provided to allow immediate output from the function.

This process by default builds a Gaussian graphical model via estimating an inverse covariance matrix (precision matrix, which can be used to calculate partial correlation coefficients) for all species pairs. This graph is then compared to a distribution of null graphs, such that the final output is a graph with edge weights corresponding to standardized effect sizes after correction for multiple comparisons.

A range of different methods are provided in partial_correlation for estimating relationships between species. Note that while a method is provided for the graphical lasso (L1-regularization) its use is not recommended, as it will produce very sparse null networks and then a narrow (or singular) distribution of null edge weights.

The inverse covariance methods implemented in partial_correlation result in symmetric association metrics. Non-symmetric metrics (e.g. describing predation or commensalism) are possible mathematically but their usage is not well-established. For an example of how to implement these, see pairwise_association.

Value

A list with the following components:

matrix_spsite_obs

Trimmed obs matrix

matrix_spsite_nul

Trimmed nul matrix

matrix_spsp_obs

Observed co-occurrence scores for all species

matrix_spsp_ses_thresholded

Observed co-occurrence scores for all species after removing those with non-significant p-values

matrix_spsp_pvalue

P-values for all species after correction for multiple comparisons

network_all

An igraph object representing the association network

network_pos

An igraph object representing an association network including only positive associations

network_pos

An igraph object representing an association network including only negative associations

See Also

vegan::permat

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
set.seed(1)
nsp <- 10
nsi <- 50
m_obs <- floor(matrix(rpois(nsp*nsi,lambda=5),ncol=nsi,nrow=nsp))
m_nul <- floor(matrix(rpois(nsp*nsi,lambda=5),ncol=nsi,nrow=nsp))

m_obs[1,1:(nsi/2)] <- rpois(n=nsi/2,lambda=20)
m_obs[2,1:(nsi/2)] <- rpois(n=nsi/2,lambda=20)

n <- make_netassoc_network(m_obs, m_nul,
  method="partial_correlation",args=list(method="shrinkage"),
  p.method='fdr', 
  numnulls=100, plot=TRUE,alpha=0.05)
  
# experimental demonstration of non-symmetric metrics  
#n <- make_netassoc_network(m_obs, m_nul,
#  method="pairwise_association",args=list(method="condentropy"),
#  p.method='fdr', 
#  numnulls=100, plot=TRUE,alpha=0.05)

n$network_all

Example output

Loading required package: igraph

Attaching package: 'igraph'

The following objects are masked from 'package:stats':

    decompose, spectrum

The following object is masked from 'package:base':

    union

Loading required package: infotheo
Calculating observed co-occurrence scores...
Generating null replicate 1...
Generating null replicate 2...
Generating null replicate 3...
Generating null replicate 4...
Generating null replicate 5...
Generating null replicate 6...
Generating null replicate 7...
Generating null replicate 8...
Generating null replicate 9...
Generating null replicate 10...
Generating null replicate 11...
Generating null replicate 12...
Generating null replicate 13...
Generating null replicate 14...
Generating null replicate 15...
Generating null replicate 16...
Generating null replicate 17...
Generating null replicate 18...
Generating null replicate 19...
Generating null replicate 20...
Generating null replicate 21...
Generating null replicate 22...
Generating null replicate 23...
Generating null replicate 24...
Generating null replicate 25...
Generating null replicate 26...
Generating null replicate 27...
Generating null replicate 28...
Generating null replicate 29...
Generating null replicate 30...
Generating null replicate 31...
Generating null replicate 32...
Generating null replicate 33...
Generating null replicate 34...
Generating null replicate 35...
Generating null replicate 36...
Generating null replicate 37...
Generating null replicate 38...
Generating null replicate 39...
Generating null replicate 40...
Generating null replicate 41...
Generating null replicate 42...
Generating null replicate 43...
Generating null replicate 44...
Generating null replicate 45...
Generating null replicate 46...
Generating null replicate 47...
Generating null replicate 48...
Generating null replicate 49...
Generating null replicate 50...
Generating null replicate 51...
Generating null replicate 52...
Generating null replicate 53...
Generating null replicate 54...
Generating null replicate 55...
Generating null replicate 56...
Generating null replicate 57...
Generating null replicate 58...
Generating null replicate 59...
Generating null replicate 60...
Generating null replicate 61...
Generating null replicate 62...
Generating null replicate 63...
Generating null replicate 64...
Generating null replicate 65...
Generating null replicate 66...
Generating null replicate 67...
Generating null replicate 68...
Generating null replicate 69...
Generating null replicate 70...
Generating null replicate 71...
Generating null replicate 72...
Generating null replicate 73...
Generating null replicate 74...
Generating null replicate 75...
Generating null replicate 76...
Generating null replicate 77...
Generating null replicate 78...
Generating null replicate 79...
Generating null replicate 80...
Generating null replicate 81...
Generating null replicate 82...
Generating null replicate 83...
Generating null replicate 84...
Generating null replicate 85...
Generating null replicate 86...
Generating null replicate 87...
Generating null replicate 88...
Generating null replicate 89...
Generating null replicate 90...
Generating null replicate 91...
Generating null replicate 92...
Generating null replicate 93...
Generating null replicate 94...
Generating null replicate 95...
Generating null replicate 96...
Generating null replicate 97...
Generating null replicate 98...
Generating null replicate 99...
Generating null replicate 100...
Calculating standardized effect sizes...
Adjusting p-values for multiple comparisons... Building network...
IGRAPH 9d7b430 DNW- 10 2 -- 
+ attr: name (v/c), weight (e/n)
+ edges from 9d7b430 (vertex names):
[1] Species 1->Species 2 Species 2->Species 1

netassoc documentation built on May 2, 2019, 6:49 a.m.