dissCqN: Multiple Assemblage Dissimilarity for Orders q = 0-N

Description

Calculate multiple or pairwise dissimilarity for orders q = 0-N (CqN; Chao et al. 2008 <doi:10/fcvn63>) for a set of species assemblages or interaction networks.

Author(s)

Maintainer: Mark Murphy murphymv@gmail.com

See Also

Useful links:

• https://murphymv.github.io/dissCqN/

• https://github.com/murphymv/dissCqN

• Report bugs at https://github.com/murphymv/dissCqN/issues

Object Types

Description

Functions to determine the 'type' of an R object using classes. Intended largely for convenience and internal use.

Usage

isList(x)

isBoot(x)

isMod(x)

Arguments

Value

A logical value.

Functions

• isList: Is object a list (class "list" only)?

• isBoot: Is object a boot object (class "boot")?

• isMod: Is object a fitted model?

Multiple Assemblage Dissimilarity

Description

Multiple assemblage dissimilarity for orders q = 0-N.

Usage

dissCqN(
  mat,
  q = 0:2,
  pairwise = FALSE,
  compare.sub = NULL,
  shared.spp = FALSE,
  parallel = "no",
  ncpus = NULL,
  cl = NULL
)

Arguments

Details

Dissimilarity is calculated here for multiple species assemblages (or interaction networks) via the CqN generalisation of similarity indices (Chao et al. 2008, Jost et al. 2011). Increasing the value of q increases the 'depth' of the measure, that is, how much emphasis is placed on changes in relative abundance of the most common species. Setting q = 0 represents the qualitative Sørensen index (Sørensen 1948), where rare and common species are treated equally. q > 0 is more sensitive to common species, with q = 1 representing the Shannon-based Horn index (Horn 1966) and q = 2 the Simpson-based Morisita-Horn index (Morisita 1959, Horn 1966). For N > 2, indices are generalised to consider species shared across multiple assemblages (Diserud & Ødegaard 2007, eqns. 6.3-6.5 in Jost et al. 2011). For q >= 2 <= N, common species increasingly dominate the measure, and it can then be interpreted as the ratio of two probabilities of randomly sampling q individuals of the same species from the N assemblages, where 1) the individuals came from at least one different assemblage (^{q}G_{D}) and 2) they all came from the same assemblage (^{q}G_{S}) (Jost et al. 2011). Dissimilarity is thus:

1 - ^{q}G_{D} / ^{q}G_{S}

Pairwise dissimilarity can be calculated for all or a subset of the assemblages (or networks) in mat, in which case a dissimilarity matrix is returned (one for each value of q). If comparing subsets, the names or indices of assemblages to compare should be supplied to compare.sub. Note that pairwise calculation may take a long time if N is large, in which case parallel processing may speed up results (e.g. parallel = "snow").

If shared.spp = TRUE and mat is a list of interaction networks (as matrices), multiple or pairwise interaction dissimilarity will be calculated for networks of shared species only (see netShared()). This can be useful to help partition the different components of network dissimilarity, e.g. dissimilarity due to interaction 'rewiring' among shared species vs. that due to species turnover (Poisot et al. 2012).

Value

A numeric vector of dissimilarities, or a pairwise dissimilarity matrix (or list of matrices), for the orders of q.

References

Chao, A., Jost, L., Chiang, S. C., Jiang, Y.-H., & Chazdon, R. L. (2008). A Two-Stage Probabilistic Approach to Multiple-Community Similarity Indices. Biometrics, 64(4), 1178–1186. doi: 10/fcvn63

Diserud, O. H., & Ødegaard, F. (2007). A multiple-site similarity measure. Biology Letters, 3(1), 20–22. doi: 10/bwhfx6

Horn, H. S. (1966). Measurement of “Overlap” in Comparative Ecological Studies. The American Naturalist, 100(914), 419–424. doi: 10/b62ct5

Jost, L., Chao, A., & Chazdon, R. L. (2011). Compositional similarity and beta diversity. In A. E. Magurran & B. J. McGill (Eds.), Biological Diversity: Frontiers in Measurement and Assessment (pp. 66–84). Oxford University Press.

Morisita, M. (1959). Measuring of interspecific association and similarity between communities. Memoirs of the Faculty of Science, Kyushu Univ., Series E (Biology), 3, 65–80.

Poisot, T., Canard, E., Mouillot, D., Mouquet, N., & Gravel, D. (2012). The dissimilarity of species interaction networks. Ecology Letters, 15(12), 1353–1361. doi: 10/f4dv37

Sørensen, T. (1948). A method of establishing groups of equal amplitude in plant sociology based on similarity of species and its application to analyses of the vegetation on Danish commons. Kongelige Danske Videnskabernes Selskabs Biologiske Skrifter, 5, 1–34.

Examples

# Sample community data from SpadeR package (three assemblages, 120 species)
data(SimilarityMultData, package = "SpadeR")
d <- SimilarityMultData$Abu

# Multiple-assemblage dissimilarity for q = 0:2
(CqN <- dissCqN::dissCqN(t(d)))

# Compare to empirical CqN values from SpadeR::SimilarityMult()
sim <- SpadeR::SimilarityMult(d, datatype = "abundance", nboot = 1)
CqN_2 <- 1 - c(
  "C0N" = sim$Empirical_richness["C0N(q=0,Sorensen)", "Estimate"],
  "C1N" = sim$Empirical_relative["C1N=U1N(q=1,Horn)", "Estimate"],
  "C2N" = sim$Empirical_relative["C2N(q=2,Morisita)", "Estimate"]
)
stopifnot(all.equal(CqN, CqN_2))

# Pairwise dissimilarity matrices
dissCqN::dissCqN(t(d), pairwise = TRUE)

Assemblage x Species Interaction Matrix

Description

Generate a matrix of assemblages x species interactions from a set of networks.

Usage

intMat(net, shared.spp = FALSE, ...)

Arguments

Value

A matrix with assemblages in rows and species interactions in columns.

Networks of Shared Species

Description

Generate interaction networks comprising only the shared species across two or more networks.

Usage

netShared(net, pairwise = TRUE, compare.sub = NULL)

Arguments

Value

A list of networks of shared species. If comparing pairwise, this will be of length n1 * n2 * 2 (with n1 and n2 being the numbers of networks in each set), or if considering multiple networks, the length of the original list.

Note

If comparing networks pairwise, and subsets are not specified, the output will contain network self-comparisons (redundancy).

Parallel sapply()

Description

Apply a function to a vector using parallel processing.

Usage

pSapply(
  X,
  FUN,
  parallel = c("snow", "multicore", "no"),
  ncpus = NULL,
  cl = NULL,
  add.obj = NULL,
  ...
)

Arguments

Details

This is a wrapper for parallel::parSapply() ("snow") or parallel::mcmapply() ("multicore"), enabling (potentially) faster processing of a function over a vector of objects. If parallel = "no", sapply() is used instead.

Parallel processing via option "snow" (default) is carried out using a cluster of workers, which is automatically set up via makeCluster() using all available system cores or a user supplied number of cores. The function then exports the required objects and functions to this cluster using clusterExport(), after performing a (rough) match of all objects and functions in the current global environment to those referenced in the call to FUN (and also any calls in X). Any additional required object names can be supplied using add.obj.

Value

The output of FUN in a list, or simplified to a vector or array.

Recursive mapply()

Description

Recursively apply a function to a list or lists.

Usage

rMapply(FUN, ..., MoreArgs = NULL, SIMPLIFY = TRUE, USE.NAMES = TRUE)

Arguments

Details

rMapply() recursively applies FUN to the elements of the lists in ... via mapply(). If only a single list is supplied, the function acts like a recursive version of sapply(). The particular condition that determines if the function should stop recursing is if either the first or second objects in ... are not of class "list". Thus, unlike mapply(), it will not iterate over non-list elements in these objects, but instead returns the output of FUN(...).

This is primarily a convenience function used internally to enable recursive application of functions to lists or nested lists. Its particular stop condition for recursing is also designed to either a) act as a wrapper for FUN if the first object in ... is not a list, or b) apply a weighted averaging operation if the first object is a list and the second object is a numeric vector of weights.

Value

The output of FUN in a list or nested list, or simplified to a vector or array (or list of arrays).