mcount: Count bipartite motifs

Description Usage Arguments Details Value References Examples

View source: R/mcount.R

Description

Counts occurrences of motifs in a bipartite network

Usage

1
mcount(M, six_node = FALSE, normalisation, mean_weight, standard_dev)

Arguments

M

A numeric matrix representing interactions between two groups of nodes. Each row corresponds to a node in one level and each column corresponds to a node in the other level. Elements of M are positive numbers if nodes do interact, and 0 otherwise. Formally, M is a biadjacency matrix. When nodes i and j interact, m_ij > 0; if they do not interact, m_ij = 0.

six_node

Logical; should six node motifs be counted? Defaults to FALSE.

normalisation

Logical; should motif frequencies be normalised to control for network size?

mean_weight

Logical; used for weighted networks. Should the mean weight of each motif be computed?

standard_dev

Logical; should the standard deviation of the mean weight for each motif be computed? Warning: can be slow for larger networks.

Details

Counts the number of times each of the 17 motifs up to five nodes (if six_node = FALSE), or 44 motifs up to six nodes (if six_node = TRUE), occurs in a network (note: if the network has weights it will be converted to binary; see below for how to use the weights argument to account for network weights).

Six-node motifs

If six_node = FALSE, all motifs containing between 2 and 5 nodes are counted. If six_node = TRUE, all motifs containing between 2 and 6 nodes are counted. Analyses where six_node = FALSE are substantially faster than when six_node = TRUE, especially for large networks. For large networks, counting six node motifs is also memory intensive. In some cases, R can crash if there is not enough memory.

Normalisation

Larger networks tend to contain more motifs. Controlling for this effect by normalising motif counts is important if different sized networks are being compared. If normalisation = TRUE, motif frequencies are normalised in four ways:

Weighted networks

mcount also supports weighted networks. We let the weight of a given subgraph be the arithmetic mean of the weights of its links (note: we only consider links which are actually present), following Mora et al. (2018).

For each motif we do the following:
We calculate the weights of all subgraphs of the same type as (formally: isomorphic to) the motif.
If mean_weight = TRUE, we compute the arithmetic mean of the subgraph weights.
If standard_dev = TRUE, we compute the standard deviation of the subgraph weights.

For example, let there be two subgraphs, A and B, which are isomorphic to motif 5. Subgraph A has three links with weights 1, 2 and 3; subgraph B has three links with weights 4, 5 and 6. The weight of subgraph A is the mean of 1, 2 and 3, which is 2. The weight of subgraph B is the mean of 4, 5 and 6 which is 5. The mean weight of motif 5 which would be returned by mcount is therefore the mean of 2 and 5 which is 3.5.

Value

Returns a data frame with one row for each motif: either 17 rows (if six_node = FALSE) or 44 rows (if six_node = TRUE). The data frame has three columns. The first column ("motif") indicates the motif ID as described in Simmons et al. (2017). To view the 'motif dictionary' showing which motif a given ID corresponds to, enter vignette("bmotif-dictionary"). The second column ("nodes") indicates how many nodes the motif contains. The third column ("frequency") is the number of times each motif appears in the network.

If normalisation = TRUE, three additional columns are added to the output data frame, each corresponding to a different method of normalising motif frequencies as described above. If mean_weight = TRUE, an additional column with the mean weight values is added. If standard_dev = TRUE, an additional column with the standard deviation values is added.

References

Baker, N., Kaartinen, R., Roslin, T., and Stouffer, D. B. (2015). Species’ roles in food webs show fidelity across a highly variable oak forest. Ecography, 38(2):130–139.

Cirtwill, A. R. and Eklöf, A (2018), Feeding environment and other traits shape species’ roles in marine food webs. Ecol Lett, 21: 875-884. doi:10.1111/ele.12955

Mora, B.B., Cirtwill, A.R. and Stouffer, D.B., 2018. pymfinder: a tool for the motif analysis of binary and quantitative complex networks. bioRxiv, 364703.

Poisot, T. & Stouffer, D. (2016). How ecological networks evolve. bioRxiv.

Simmons, B. I., Sweering, M. J. M., Dicks, L. V., Sutherland, W. J. and Di Clemente, R. bmotif: a package for counting motifs in bipartite networks. bioRxiv. doi: 10.1101/302356

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
set.seed(123)
row <- 10
col <- 10

# motif counts for a binary network
m <- matrix(sample(0:1, row*col, replace=TRUE), row, col)
mcount(M = m, six_node = TRUE, normalisation = TRUE, mean_weight = FALSE, standard_dev = FALSE)

# motif counts in a weighted network
m[m>0] <- stats::runif(sum(m), 0, 100)
mcount(M = m, six_node = TRUE, normalisation = TRUE, mean_weight = TRUE, standard_dev = TRUE)

SimmonsBI/bmotif documentation built on Sept. 28, 2020, 1:34 p.m.