cooccur: A function to calculate pairwise co-occurrence patterns from...
In cooccur: Probabilistic Species Co-Occurrence Analysis in R

Description Usage Arguments Value Author(s) References Examples

This is the main function in the package cooccur. This R package applies the probabilistic model of species co-occurrence (Veech 2013) to a set of species distributed among a set of survey or sampling sites. The algorithm calculates the observed and expected frequencies of co-occurrence between each pair of species. The expected frequency is based on the distribution of each species being random and independent of the other species. The analysis returns the probabilities that a more extreme (either low or high) value of co-occurrence could have been obtained by chance. The package also includes functions for visualizing species co-occurrence results and preparing data for downstream analyses.

This function takes a community dataset (data frame or matrix) of species by site presence-absence data and classifies species pairs as having positive, negative, and random associations based on the probabilistic model of specie co-occurrence from Veech (2013). It produces an object of class cooccur.

cooccur(mat, type = "spp_site", thresh = TRUE, spp_names = FALSE,
        true_rand_classifier = 0.1, prob = "hyper", 
        site_mask = NULL, only_effects = FALSE,
        eff_standard = TRUE, eff_matrix = FALSE)

`mat`	A species by site (r,c) data.frame or matrix of presence-absence (or abundance) data. Or, a site by species dataset with `type="site_spp"`.
`type`	Default is `"spp_site"` meaning `mat` specifies species by site (r,c) data. For site by species use `"site_spp"`.
`thresh`	Logical. If TRUE then species pairs that are expected have less than 1 co-occurrences are filtered from the analysis. This will remove pairs from the results.
`spp_names`	Logical. Are there species names in either the column names or row names of the species matrix? If so then `spp_names` should be TRUE to use them.
`true_rand_classifier`	When a species pair is not classified as positive or negative, the species pair can be truely randomly distributed or they can be unclassifiable due to low statistical power. We classify truly random associations as those that do not deviate from their expected co-occurrences by more than 0.1 x the total number of sites. Therefore the default value is 0.1 but any proportion can be specified to be more or less strict.
`prob`	Should co-occurrence probabilities be calculated using the hypergeometric distribution (`prob="hyper"`) or the combinatorics approach from Veech 2013 (`prob="comb"`).
`site_mask`	A matrix with the same dimensions as `mat`, where each cell is a 1 or 0. 1 indicates sites that a species can exist and 0 indicates sites where the species cannot exist.
`only_effects`	Logical. Probability calculations can be time consuming; if only effect sizes are required from the analysis, then specific TRUE.
`eff_standard`	Logical. If `only_effects=TRUE` then should the effect sizes be standardized?
`eff_matrix`	Logical. If `only_effects=TRUE` then should the effect sizes be returned in a distance matrix? The alternative is a list of pairs.

Returns a list of class cooccur.

`call`	Original function call.
`results`	Probability table containing all analyzed species pairs and their observed and expected co-occurrences and probabilities for classifying positive and negative associations.
`positive`	Number of positive pairs.
`negative`	Number of negative pairs.
`co_occurrences`	Sum of positive and negative pairs.
`pairs`	Number of analyzed species pairs.
`random`	Number of truly random species pairs.
`unclassifiable`	Number of unclassifiable species pairs.
`sites`	Number of sites.
`species`	Number of species.
`percent_sig`	Percent of pairs classified as either positive or negative.
`true_rand_classifier`	The proportion used to classify truly random pairs.
`spp_key`	A key relating the species numbers and names.
`spp.names`	Ordered list of species names.
`omitted`	Number of pairs removed due to the threshold filter.
`pot_pairs`	Number of pairs before application of the threshold.

Daniel M Griffith

Veech (2013). A probabilistic model for analysing species co-occurrence. Global Ecology and Biogeography, DOI: 10.1111/j.1466-8238.2012.00789.x

Griffith, Veech, and Marsh (2016). cooccur: Probabilistic Species Co-Occurrence Analysis in R. Journal of Statistical Software, 69(2), 1-17. doi:10.18637/jss.v069.c02

#data(finches)
#cooccur.finches <- cooccur(mat=finches,
#			   type="spp_site",
#			   thresh=TRUE,
#			   spp_names=TRUE)
#summary(cooccur.finches)
#plot(cooccur.finches)