Skip to contents

Metrics to compare pairs of resource niches

Source: R/nichedispl.R, R/nicheoverlap.R
nicheoverlap.Rd

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
)

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).

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".

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.

Author

Miquel De Caceres Ainsa, EMF-CREAF

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") 
#>                        O
#> sp1B vs sp1W   0.9180321
#> sp2B vs sp2W   0.9928700
#> sp3B vs sp3W   1.0000000
#> sp4B vs sp4W   0.9982815
#> sp5B vs sp5W   0.9168365
#> sp6B vs sp6W   0.9538433
#> sp7B vs sp7W   0.9843038
#> sp8B vs sp8W   0.4964025
#> sp9B vs sp9W          NA
#> sp10B vs sp10W 0.7178288
nichedispl(birdsbreed, birdswinter, D = resourceD, mode="multiple") 
#>                        CD
#> sp1B vs sp1W   0.24372798
#> sp2B vs sp2W   0.07334250
#> sp3B vs sp3W   0.00000000
#> sp4B vs sp4W   0.03636655
#> sp5B vs sp5W   0.24986173
#> sp6B vs sp6W   0.19374648
#> sp7B vs sp7W   0.10245775
#> sp8B vs sp8W   0.69797974
#> sp9B vs sp9W           NA
#> sp10B vs sp10W 0.42080273

# 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) 
#>                        O        LC        UC
#> sp1B vs sp1W   0.9180321 0.7883775 0.9866784
#> sp2B vs sp2W   0.9928700 0.9735237 0.9999586
#> sp3B vs sp3W   1.0000000        NA        NA
#> sp4B vs sp4W   0.9982815 0.9779393 0.9999998
#> sp5B vs sp5W   0.9168365 0.7819348 0.9895666
#> sp6B vs sp6W   0.9538433 0.8669563 0.9939099
#> sp7B vs sp7W   0.9843038 0.9252224 0.9998875
#> sp8B vs sp8W   0.4964025 0.4709896 0.5861006
#> sp9B vs sp9W          NA        NA        NA
#> sp10B vs sp10W 0.7178288 0.5549183 0.8929712
nichedispl(birdsbreed, birdswinter, D = resourceD, mode="multiple", 
           Np1 = rowSums(birdsbreed), Np2 = rowSums(birdswinter), Nq1 = 100, Nq2 = 100) 
#>                        CD         LC        UC
#> sp1B vs sp1W   0.24372798 0.09363914 0.4138077
#> sp2B vs sp2W   0.07334250         NA        NA
#> sp3B vs sp3W   0.00000000         NA        NA
#> sp4B vs sp4W   0.03636655         NA        NA
#> sp5B vs sp5W   0.24986173 0.06141686 0.4028571
#> sp6B vs sp6W   0.19374648 0.07438823 0.3137258
#> sp7B vs sp7W   0.10245775         NA        NA
#> sp8B vs sp8W   0.69797974 0.61414324 0.7273310
#> sp9B vs sp9W           NA         NA        NA
#> sp10B vs sp10W 0.42080273 0.28017376 0.5383399

# 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")
#>                        O
#> sp1B vs sp1W   0.9395885
#> sp2B vs sp2W   0.9918133
#> sp3B vs sp3W   1.0000000
#> sp4B vs sp4W   0.9986449
#> sp5B vs sp5W   0.8933637
#> sp6B vs sp6W   0.9727062
#> sp7B vs sp7W   0.9848794
#> sp8B vs sp8W   0.4919339
#> sp9B vs sp9W          NA
#> sp10B vs sp10W 0.6624301
nichedispl(birdsbreed, birdswinter, D = resourceD, 
           q1 = q, q2 = q, mode="multiple")
#>                        CD
#> sp1B vs sp1W   0.20977627
#> sp2B vs sp2W   0.07753105
#> sp3B vs sp3W   0.00000000
#> sp4B vs sp4W   0.03321146
#> sp5B vs sp5W   0.27919844
#> sp6B vs sp6W   0.15151280
#> sp7B vs sp7W   0.10178862
#> sp8B vs sp8W   0.70300550
#> sp9B vs sp9W           NA
#> sp10B vs sp10W 0.46117552
nicheoverlap(birdsbreed, birdswinter, D = resourceD, 
             q1 = q, q2 = q, mode="multiple", 
             Np1 = rowSums(birdsbreed), Np2 = rowSums(birdswinter), 
             Nq1 = 100, Nq2 = 100)
#>                        O        LC        UC
#> sp1B vs sp1W   0.9395885 0.8278564 0.9913655
#> sp2B vs sp2W   0.9918133 0.9649513 0.9999292
#> sp3B vs sp3W   1.0000000        NA        NA
#> sp4B vs sp4W   0.9986449 0.9856260 1.0000000
#> sp5B vs sp5W   0.8933637 0.7021522 0.9886982
#> sp6B vs sp6W   0.9727062 0.9077447 0.9958008
#> sp7B vs sp7W   0.9848794 0.9286959 0.9999946
#> sp8B vs sp8W   0.4919339 0.4709896 0.5740590
#> sp9B vs sp9W          NA        NA        NA
#> sp10B vs sp10W 0.6624301 0.4885985 0.8428243
nichedispl(birdsbreed, birdswinter, D = resourceD, 
           q1 = q, q2 = q, mode="multiple", 
           Np1 = rowSums(birdsbreed), Np2 = rowSums(birdswinter), 
           Nq1 = 100, Nq2 = 100)
#>                        CD          LC        UC
#> sp1B vs sp1W   0.20977627 0.080266621 0.3477571
#> sp2B vs sp2W   0.07753105          NA        NA
#> sp3B vs sp3W   0.00000000          NA        NA
#> sp4B vs sp4W   0.03321146          NA        NA
#> sp5B vs sp5W   0.27919844 0.097639746 0.4503583
#> sp6B vs sp6W   0.15151280 0.049988587 0.2714120
#> sp7B vs sp7W   0.10178862 0.006887496 0.2428102
#> sp8B vs sp8W   0.70300550 0.630636997 0.7273310
#> sp9B vs sp9W           NA          NA        NA
#> sp10B vs sp10W 0.46117552 0.302029552 0.5708371

# The overlap metrics using distances among rows of 'birdsbreed'
nicheoverlap(birdsbreed, D = resourceD, mode="pairwise") 
#>            sp1B      sp2B      sp3B      sp4B      sp5B      sp6B      sp7B
#> sp1B  1.0000000 0.6645078 0.8576099 0.9841992 0.9225876 0.4493889 0.9896160
#> sp2B  0.6645078 1.0000000 0.3558765 0.5803276 0.8508925 0.9155505 0.7246835
#> sp3B  0.8576099 0.3558765 1.0000000 0.9351235 0.7716197 0.2257267 0.8657498
#> sp4B  0.9841992 0.5803276 0.9351235 1.0000000 0.9012619 0.3873154 0.9798477
#> sp5B  0.9225876 0.8508925 0.7716197 0.9012619 1.0000000 0.6669124 0.9654380
#> sp6B  0.4493889 0.9155505 0.2257267 0.3873154 0.6669124 1.0000000 0.5220447
#> sp7B  0.9896160 0.7246835 0.8657498 0.9798477 0.9654380 0.5220447 1.0000000
#> sp8B  0.8717161 0.3989051 0.9987823 0.9444225 0.8008132 0.2648938 0.8843865
#> sp9B  0.9152202 0.8952192 0.6634003 0.8589282 0.9786929 0.6891189 0.9435430
#> sp10B 0.5428608 0.9486252 0.2892194 0.4735713 0.7571142 0.9416413 0.6144665
#>            sp8B      sp9B     sp10B
#> sp1B  0.8717161 0.9152202 0.5428608
#> sp2B  0.3989051 0.8952192 0.9486252
#> sp3B  0.9987823 0.6634003 0.2892194
#> sp4B  0.9444225 0.8589282 0.4735713
#> sp5B  0.8008132 0.9786929 0.7571142
#> sp6B  0.2648938 0.6891189 0.9416413
#> sp7B  0.8843865 0.9435430 0.6144665
#> sp8B  1.0000000 0.6953454 0.3308257
#> sp9B  0.6953454 1.0000000 0.7846453
#> sp10B 0.3308257 0.7846453 1.0000000