indicspecies (version 1.7.15)

nichedispl: Metrics to compare pairs of resource niches

Description

Functions nicheoverlap and nichedispl compute the overlap and centroid distance between pairs of resource distributions. In both cases resource relationships are given in the distance matrix D and the resource use data are given in data frame P1 (and in some modes also P2).

Usage

nichedispl(
  P1,
  P2 = NULL,
  D = NULL,
  q1 = NULL,
  q2 = NULL,
  mode = "multiple",
  Np1 = NULL,
  Np2 = NULL,
  Nq1 = NULL,
  Nq2 = NULL,
  nboot = 1000,
  alpha = 0.05
)
nicheoverlap(
  P1,
  P2 = NULL,
  D = NULL,
  q1 = NULL,
  q2 = NULL,
  mode = "multiple",
  Np1 = NULL,
  Np2 = NULL,
  Nq1 = NULL,
  Nq2 = NULL,
  nboot = 1000,
  alpha = 0.05
)

Value

Function nicheoverlap (resp. nichedispl) returns the overlap (resp. the distance between centroids) between the each pair of rows in P1 and P2. If mode = "multiple" or mode = "single" the values are returned as a data frame. If mode = "pairwise" a matrix of values is returned instead. If bootstrap confidence intervals are asked then the functions also compute the lower and upper bounds of a confidence interval obtained following the bias-corrected percentile method. Upper and lower bounds are returned as additional columns of the data frame in mode = "multiple" or mode = "single" or as additional matrices of a list in mode = "pairwise".

Arguments

P1

Data frame containing the amount of usage that a set of species (in rows) make of a first set of resources (in columns)

P2

Data frame containing the amount of usage that a set of species (in rows) make of a second set of resources (in columns). Not used if mode = "pairwise"

D

Object of type dist containing distance values between resources. If no distance matrix is provided (i.e. if D==NULL), the distances between resources is assumed to be maximum

q1

Vector with the availability of each resource corresponding to P1

q2

Vector with the availability of each resource corresponding to P2

mode

Either mode = "single" (rows of matrices P1 and P2 are individual observations to be pooled, for example to compare the niche of two species each with its individual observations), mode = "multiple" (each row in P1 is compared to the corresponding row of P2, for example, to compare seasonal niche shifts in each species) or mode = "pairwise" (all rows in P1 are compared pairwise).

Np1

Vector with the number of observations per species from which the values in P1 come (in mode = "multiple" or mode = "pairwise").

Np2

Vector with the number of observations per species from which the values in P2 come (only in mode = "multiple").

Nq1

The number of observations from which the values in q1 come.

Nq2

The number of observations from which the values in q2 come.

nboot

Number of boostrap samples used to compute bias-corrected percentile confidence intervals.

alpha

Used to set the confidence level (i.e. alpha = 0.05 means 95 percent confidence interval).

Author

Miquel De Caceres Ainsa, EMF-CREAF

Details

The method is described in De Caceres et al. (2011). If the distance matrix is not specified (i.e. if D=NULL) the function assumes that all resources are at a maximum distance (d=1). If the resource availability vector q1 (and q2 if supplied) is specified, then the values in P1 (and P2 if supplied) are taken as assessments of resource use and the species preference is calculated taking into account resource availability. Otherwise, resource use is equated to resource preference (i.e. all resources are considered equally available). The functions can compute bootstrap confidence intervals following the bias-corrected percentile method (Manly 2007). If mode = "multiple" and Np1 and Np2 are not null, bootstrap samples for a given niche are generated assuming a multinomial distribution with the proportions calculated from the corresponding row values in P1 (resp. P2), and the number of observations comes from the corresponding element in Np1 (resp. Np2). Similarly, if mode = "pairwise" and Np1 is not null, bootstrap samples for each niche are generated assuming a multinomial distribution with the proportions calculated from the corresponding row values in P1, and the number of observations comes from the corresponding element in Np1. Finally, if mode = "single" then the bootstrapped units are the rows of matrices P1 and P2. In both cases, if Nq1 (and Nq2) is indicated, the availability of resources is also bootstrapped. The bias-corrected percentile method is described for overlap niche measures in Mueller and Altenberg (1985).

References

Mueller, L.D. and L. Altenberg. 1985. Statistical Inference on Measures of Niche Overlap. Ecology 66:1204-1210.

Manly, B.F.J. 2007. Randomization, bootstrap and Monte Carlo methods in biology. Chapman and Hall texts in statistical science series. 2nd edition.

De Caceres, M., Sol, D., Lapiedra, O. and P. Legendre. (2011) A framework for estimating niche metrics using the resemblance between qualitative resources. Oikos 120: 1341-1350.

See Also

See nichevar for descriptors of single niches.

Examples

# Loads example data
data(birds)

# The overlap and displacement metrics using distances among 
# resources and assuming equal availability of resources
nicheoverlap(birdsbreed, birdswinter, D = resourceD, mode="multiple") 
nichedispl(birdsbreed, birdswinter, D = resourceD, mode="multiple") 

# The overlap and displacement metrics using distances among resources
# and computes 95 percent confidence intervals
nicheoverlap(birdsbreed, birdswinter, D = resourceD, mode="multiple", 
             Np1 = rowSums(birdsbreed), Np2 = rowSums(birdswinter), Nq1 = 100, Nq2 = 100) 
nichedispl(birdsbreed, birdswinter, D = resourceD, mode="multiple", 
           Np1 = rowSums(birdsbreed), Np2 = rowSums(birdswinter), Nq1 = 100, Nq2 = 100) 

# Same computations with different resource availability
q <- c(0.18, 0.24, 0.22, 0.21, 0.15)
nicheoverlap(birdsbreed, birdswinter, D = resourceD, 
             q1 = q, q2 = q, mode="multiple")
nichedispl(birdsbreed, birdswinter, D = resourceD, 
           q1 = q, q2 = q, mode="multiple")
nicheoverlap(birdsbreed, birdswinter, D = resourceD, 
             q1 = q, q2 = q, mode="multiple", 
             Np1 = rowSums(birdsbreed), Np2 = rowSums(birdswinter), 
             Nq1 = 100, Nq2 = 100)
nichedispl(birdsbreed, birdswinter, D = resourceD, 
           q1 = q, q2 = q, mode="multiple", 
           Np1 = rowSums(birdsbreed), Np2 = rowSums(birdswinter), 
           Nq1 = 100, Nq2 = 100)

# The overlap metrics using distances among rows of 'birdsbreed'
nicheoverlap(birdsbreed, D = resourceD, mode="pairwise")