cooccur {cooccur}

A function to calculate pairwise co-occurrence patterns from a community dataset

Description

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.

Usage

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)
        

Arguments

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.

Value

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.

Author(s)

Daniel M Griffith

References

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

Examples

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