Title: Analysis and Visualization of Archaeological Count Data
Version: 3.3.1
Maintainer: Nicolas Frerebeau <nicolas.frerebeau@u-bordeaux-montaigne.fr>
Description: An easy way to examine archaeological count data. This package provides several tests and measures of diversity: heterogeneity and evenness (Brillouin, Shannon, Simpson, etc.), richness and rarefaction (Chao1, Chao2, ACE, ICE, etc.), turnover and similarity (Brainerd-Robinson, etc.). It allows to easily visualize count data and statistical thresholds: rank vs abundance plots, heatmaps, Ford (1962) and Bertin (1977) diagrams, etc.
License: GPL (≥ 3)
URL: https://codeberg.org/tesselle/tabula, https://packages.tesselle.org/tabula/
BugReports: https://codeberg.org/tesselle/tabula/issues
Depends: R (≥ 3.5)
Imports: arkhe (≥ 1.11.0), graphics, grDevices, khroma (≥ 1.16.0), methods, stats, utils
Suggests: folio (≥ 1.5.0), fontquiver, knitr, markdown, rsvg, svglite, tinysnapshot, tinytest
VignetteBuilder: knitr
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.3.2.9000
X-schema.org-applicationCategory: Archaeological Science
X-schema.org-isPartOf: https://www.tesselle.org
X-schema.org-keywords: archaeological-science, archaeology, data-visualization, diversity-index, r-package
Collate: 'AllClasses.R' 'AllGenerics.R' 'coerce.R' 'data.R' 'diversity.R' 'diversity_alpha.R' 'diversity_beta.R' 'diversity_test.R' 'matrigraph.R' 'mutators.R' 'occurrence.R' 'plot_bertin.R' 'plot_diceleraas.R' 'plot_diversity.R' 'plot_ford.R' 'plot_heatmap.R' 'plot_matrix.R' 'plot_rank.R' 'plot_spot.R' 'rarefaction.R' 'reexport.R' 'resample.R' 'seriograph.R' 'show.R' 'similarity.R' 'statistics.R' 'subset.R' 'tabula-deprecated.R' 'tabula-internal.R' 'tabula-package.R' 'validate.R' 'zzz.R'
NeedsCompilation: no
Packaged: 2025-05-15 11:48:53 UTC; nfrerebeau
Author: Nicolas Frerebeau ORCID iD [aut, cre], Matthew Peeples ORCID iD [ctb], Ben Marwick ORCID iD [ctb], Jean-Baptiste Fourvel ORCID iD [ctb], Brice Lebrun ORCID iD [art] (Logo designer), Université Bordeaux Montaigne ROR ID [fnd], CNRS ROR ID [fnd]
Repository: CRAN
Date/Publication: 2025-05-15 13:30:02 UTC

tabula: Analysis and Visualization of Archaeological Count Data

Description

logo

An easy way to examine archaeological count data. This package provides several tests and measures of diversity: heterogeneity and evenness (Brillouin, Shannon, Simpson, etc.), richness and rarefaction (Chao1, Chao2, ACE, ICE, etc.), turnover and similarity (Brainerd-Robinson, etc.). It allows to easily visualize count data and statistical thresholds: rank vs abundance plots, heatmaps, Ford (1962) and Bertin (1977) diagrams, etc.

Details

Version 3.3.1
License GPL-3
CRAN DOI doi:10.32614/CRAN.package.tabula
Zenodo DOI doi:10.5281/zenodo.1489944
JOSS DOI doi:10.21105/joss.01821

Archéosciences Bordeaux (UMR 6034)
Maison de l'Archéologie
Université Bordeaux Montaigne
33607 Pessac cedex
France

Package options

tabula uses the following options() to configure behavior:

Author(s)

Maintainer: Nicolas Frerebeau nicolas.frerebeau@u-bordeaux-montaigne.fr (ORCID)

Other contributors:

See Also

Useful links:

Composition Index

Description

An S4 class to represent an composition measure.

Note

This class inherits from DiversityIndex.

Author(s)

N. Frerebeau

See Also

composition()

Other classes: DiversityIndex-class, EvennessIndex-class, HeterogeneityIndex-class, RarefactionIndex-class, RichnessIndex-class

Diversity Index

Description

An S4 class to represent a diversity measure.

Slots

.Data

A numeric vector of diversity measures.

labels

A character vector giving the sample names.

size

An integer vector giving the sample sizes.

data

A numeric matrix of count data.

method

A character string specifying the method used.

simulation

A four columns numeric matrix giving the diversity measures for the simulated assemblage (sample size, mean estimate, lower and upper boundaries of the confidence interval).

seed

A numeric vector giving the value of .Random.seed before the simulation was started; otherwise it is the user specified value with a kind attribute with value ⁠as.list(⁠RNGkind()⁠)⁠.

Coerce

In the code snippets below, x is an DiversityIndex object.

as.data.frame(x)

Coerces to a data.frame.

Note

This class inherits from base numeric.

Author(s)

N. Frerebeau

See Also

Other classes: CompositionIndex-class, EvennessIndex-class, HeterogeneityIndex-class, RarefactionIndex-class, RichnessIndex-class

Evenness Index

Description

An S4 class to represent an evenness measure.

Note

This class inherits from DiversityIndex.

Author(s)

N. Frerebeau

See Also

evenness()

Other classes: CompositionIndex-class, DiversityIndex-class, HeterogeneityIndex-class, RarefactionIndex-class, RichnessIndex-class

Heterogeneity Index

Description

An S4 class to represent an heterogeneity measure.

Note

This class inherits from DiversityIndex.

Author(s)

N. Frerebeau

See Also

heterogeneity()

Other classes: CompositionIndex-class, DiversityIndex-class, EvennessIndex-class, RarefactionIndex-class, RichnessIndex-class

Rarefaction Index

Description

An S4 class to represent an rarefaction measure.

Slots

.Data

A numeric matrix of count data (expected taxa per fixed number of individuals).

labels

A character vector giving the sample names.

size

An integer vector giving the sample sizes.

method

A character string specifying the method used.

Note

This class inherits from base matrix.

Author(s)

N. Frerebeau

See Also

rarefaction()

Other classes: CompositionIndex-class, DiversityIndex-class, EvennessIndex-class, HeterogeneityIndex-class, RichnessIndex-class

Richness Index

Description

An S4 class to represent a richness measure.

Note

This class inherits from DiversityIndex.

Author(s)

N. Frerebeau

See Also

richness()

Other classes: CompositionIndex-class, DiversityIndex-class, EvennessIndex-class, HeterogeneityIndex-class, RarefactionIndex-class

Birds Species and Abundances

Description

A dataset of birds species and abundances in managed and unmanaged areas along the River Wye (UK).

Usage

aves

Format

A data.frame with 2 rows and 26 variables (bird species).

Source

Magurran, A. E. (1988). Ecological Diversity and its Measurement. Princeton, NJ: Princeton University Press. doi:10.1007/978-94-015-7358-0.

See Also

Other datasets: cantabria, pueblo, woodland

Bootstrap Estimation

Description

Bootstrap Estimation

Usage

## S4 method for signature 'DiversityIndex'
bootstrap(
  object,
  n = 1000,
  f = NULL,
  level = 0.95,
  interval = c("basic", "normal", "percentiles"),
  seed = NULL,
  rare = FALSE
)

Arguments

object

An R object (typically a DiversityIndex object).

n

A non-negative integer giving the number of bootstrap replications.

f

A function that takes a single numeric vector (the bootstrap estimates) as argument.

level

A length-one numeric vector giving the confidence level. Must be a single number between 0 and 1. Only used if f is NULL.

interval

A character string giving the type of confidence interval to be returned. It must be one "basic" (the default), "normal" or "percentiles" (see arkhe::confidence_bootstrap()). Any unambiguous substring can be given. Only used if f is NULL.

seed

An object specifying if and how the random number generator should be initialized (see stats::simulate()).

rare

A logical scalar: should the sample be drawn from an uniform distribution with replacement instead of a multinomial distribution?

Details

n random samples are drawn, each with the same sample size as in the original sample and with class probabilities proportional to the original abundances.

Note that the mean of the bootstrapped samples will often be much lower than the observed value. Bootstrapping results must be interpreted with great care.

Value

If f is NULL (the default), bootstrap() returns a numeric matrix with the following columns:

original

The observed value.

mean

The bootstrap estimate of mean.

bias

The bootstrap estimate of bias.

error

The bootstrap estimate of standard error.

lower

The lower limit of the bootstrap confidence interval at level.

upper

The upper limit of the bootstrap confidence interval at level.

If f is a function, bootstrap() returns the result of f applied to the values computed from the n replications.

Author(s)

N. Frerebeau

See Also

Other resampling methods: jackknife()

Examples

## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## Shannon diversity index
(h <- heterogeneity(cantabria, method = "shannon"))

## Bootstrap resampling
bootstrap(h)

bootstrap(h, f = summary)

quant <- function(x) quantile(x, probs = c(0.05, 0.95))
bootstrap(h, f = quant)

Early Magdalenian Engraved Bones

Description

A dataset of design elements in engraved bones from Cantabrian Spain.

Usage

cantabria

Format

A data.frame with 5 rows and 44 variables (designs).

Source

Conkey, M. W. (1980). The Identification of prehistoric hunter-gatherer aggregation sites: The case of Altamira. Current Anthropology, 21(5), 609-630.

Kintigh, K. W. (1989). Sample Size, Significance, and Measures of Diversity. In Leonard, R. D. and Jones, G. T., Quantifying Diversity in Archaeology. New Directions in Archaeology. Cambridge: Cambridge University Press, p. 25-36.

See Also

Other datasets: aves, pueblo, woodland

Coerce to a Data Frame

Description

Coerce to a Data Frame

Usage

## S4 method for signature 'DiversityIndex'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

x

An object.

row.names, optional

Currently not used.

...

Currently not used.

Value

A data.frame.

Author(s)

N. Frerebeau

See Also

Other mutators: mutators

Alpha Diversity

Description

Computes multiple alpha diversity indices.

Usage

diversity(object, ...)

## S4 method for signature 'matrix'
diversity(object, ..., evenness = FALSE, unbiased = FALSE)

## S4 method for signature 'data.frame'
diversity(object, ..., evenness = FALSE, unbiased = FALSE)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Currently not used.

evenness

A logical scalar: should an evenness measure be computed instead of an heterogeneity/dominance index? Only available for shannon, simpson and brillouin indices.

unbiased

A logical scalar: should the bias-corrected estimator be used? Only available for shannon, simpson and chao1 indices.

Details

Alpha diversity refers to diversity at the local level, assessed within a delimited system. It is the diversity within a uniform habitat of fixed size.

Diversity measurement assumes that all individuals in a specific taxa are equivalent and that all types are equally different from each other (Peet 1974). A measure of diversity can be achieved by using indices built on the relative abundance of taxa. These indices (sometimes referred to as non-parametric indices) benefit from not making assumptions about the underlying distribution of taxa abundance: they only take relative abundances of the species that are present and species richness into account. Peet (1974) refers to them as indices of heterogeneity.

Diversity indices focus on one aspect of the taxa abundance and emphasize either richness (weighting towards uncommon taxa) or dominance (weighting towards abundant taxa; Magurran 1988).

Evenness is a measure of how evenly individuals are distributed across the sample.

Value

A data.frame with the following columns:

size

Sample size.

observed

Number of observed taxa/types.

shannon

Shannon-Wiener diversity index.

brillouin

Brillouin diversity index.

simpson

Simpson dominance index.

berger

Berger-Parker dominance index.

menhinick

Menhinick richness index.

margalef

Margalef richness index.

chao1

Chao1 estimator.

ace

Abundance-based Coverage Estimator.

squares

Squares estimator.

Note

The berger and simpson methods return a dominance index, not the reciprocal or inverse form usually adopted, so that an increase in the value of the index accompanies a decrease in diversity.

Author(s)

N. Frerebeau

References

Magurran, A. E. (1988). Ecological Diversity and its Measurement. Princeton, NJ: Princeton University Press. doi:10.1007/978-94-015-7358-0.

Peet, R. K. (1974). The Measurement of Species Diversity. Annual Review of Ecology and Systematics, 5(1), 285-307. doi:10.1146/annurev.es.05.110174.001441.

See Also

Other diversity measures: evenness(), heterogeneity(), occurrence(), plot.DiversityIndex(), plot.RarefactionIndex(), profiles(), rarefaction(), richness(), she(), similarity(), simulate(), turnover()

Examples

## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## Alpha diversity
diversity(cantabria)

## Shannon diversity index
(h <- heterogeneity(cantabria, method = "shannon"))
(e <- evenness(cantabria, method = "shannon"))

as.data.frame(h)

Evenness

Description

Computes an evenness measure.

Usage

evenness(object, ...)

## S4 method for signature 'matrix'
evenness(
  object,
  ...,
  method = c("shannon", "simpson", "brillouin", "mcintosh")
)

## S4 method for signature 'data.frame'
evenness(
  object,
  ...,
  method = c("shannon", "simpson", "brillouin", "mcintosh")
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Further arguments to be passed to internal methods (see below).

method

A character string specifying the index to be computed (see details). Any unambiguous substring can be given.

Details

Evenness is a measure of how evenly individuals are distributed across the sample.

The following evenness measures are available (see Magurran 1988 for details):

brillouin

Brillouin diversity index.

mcintosh

McIntosh dominance index.

shannon

Shannon-Wiener diversity index.

simpson

Simpson dominance index.

Value

An EvennessIndex object.

Author(s)

N. Frerebeau

References

Magurran, A. E. (1988). Ecological Diversity and its Measurement. Princeton, NJ: Princeton University Press. doi:10.1007/978-94-015-7358-0.

See Also

index_brillouin(), index_mcintosh(), index_shannon(), index_simpson()

Other diversity measures: diversity(), heterogeneity(), occurrence(), plot.DiversityIndex(), plot.RarefactionIndex(), profiles(), rarefaction(), richness(), she(), similarity(), simulate(), turnover()

Examples

## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## Alpha diversity
diversity(cantabria)

## Shannon diversity index
(h <- heterogeneity(cantabria, method = "shannon"))
(e <- evenness(cantabria, method = "shannon"))

as.data.frame(h)

Heterogeneity

Description

Computes an heterogeneity or a dominance index.

Usage

heterogeneity(object, ...)

## S4 method for signature 'matrix'
heterogeneity(
  object,
  ...,
  method = c("shannon", "simpson", "berger", "boone", "brillouin", "mcintosh")
)

## S4 method for signature 'data.frame'
heterogeneity(
  object,
  ...,
  method = c("shannon", "simpson", "berger", "boone", "brillouin", "mcintosh")
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Further arguments to be passed to internal methods (see below).

method

A character string specifying the index to be computed (see details). Any unambiguous substring can be given.

Details

The following heterogeneity index are available (see Magurran 1988 for details):

berger

Berger-Parker dominance index.

boone

Boone heterogeneity measure.

brillouin

Brillouin diversity index.

mcintosh

McIntosh dominance index.

shannon

Shannon-Wiener diversity index.

simpson

Simpson dominance index.

The berger, mcintosh and simpson methods return a dominance index, not the reciprocal or inverse form usually adopted, so that an increase in the value of the index accompanies a decrease in diversity.

Value

An HeterogeneityIndex object.

Author(s)

N. Frerebeau

References

Magurran, A. E. (1988). Ecological Diversity and its Measurement. Princeton, NJ: Princeton University Press. doi:10.1007/978-94-015-7358-0.

See Also

index_berger(), index_boone(), index_brillouin(), index_mcintosh(), index_shannon(), index_simpson()

Other diversity measures: diversity(), evenness(), occurrence(), plot.DiversityIndex(), plot.RarefactionIndex(), profiles(), rarefaction(), richness(), she(), similarity(), simulate(), turnover()

Examples

## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## Alpha diversity
diversity(cantabria)

## Shannon diversity index
(h <- heterogeneity(cantabria, method = "shannon"))
(e <- evenness(cantabria, method = "shannon"))

as.data.frame(h)

Abundance-based Coverage Estimator

Description

Abundance-based Coverage Estimator

Usage

index_ace(x, ...)

## S4 method for signature 'numeric'
index_ace(x, k = 10, na.rm = FALSE, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

k

A length-one numeric vector giving the threshold between rare/infrequent and abundant/frequent species.

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Chao, A. & Lee, S.-M. (1992). Estimating the Number of Classes via Sample Coverage. Journal of the American Statistical Association, 87(417), 210-217. doi:10.1080/01621459.1992.10475194.

See Also

Other alpha diversity measures: index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), index_squares(), observed()

Baxter's Rarefaction

Description

Baxter's Rarefaction

Usage

index_baxter(x, ...)

## S4 method for signature 'numeric'
index_baxter(x, sample, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

sample

A length-one numeric vector giving the sub-sample size. The size of sample should be smaller than total community size.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Baxter, M. J. (2001). Methodological Issues in the Study of Assemblage Diversity. American Antiquity, 66(4), 715-725. doi:10.2307/2694184.

See Also

Other alpha diversity measures: index_ace(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), index_squares(), observed()

Berger-Parker Dominance Index

Description

Berger-Parker Dominance Index

Usage

index_berger(x, ...)

## S4 method for signature 'numeric'
index_berger(x, na.rm = FALSE, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Details

The Berger-Parker index expresses the proportional importance of the most abundant type. This metric is highly biased by sample size and richness, moreover it does not make use of all the information available from sample.

This is a dominance index, so that an increase in the value of the index accompanies a decrease in diversity.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Berger, W. H. & Parker, F. L. (1970). Diversity of Planktonic Foraminifera in Deep-Sea Sediments. Science, 168(3937), 1345-1347. doi:10.1126/science.168.3937.1345.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), index_squares(), observed()

Binomial Co-Occurrence Assessment

Description

Binomial Co-Occurrence Assessment

Usage

index_binomial(x, y, ...)

## S4 method for signature 'numeric,numeric'
index_binomial(x, y)

Arguments

x, y

A numeric vector.

...

Currently not used.

Details

This assesses the degree of co-occurrence between taxa/types within a dataset. The strongest associations are shown by large positive numbers, the strongest segregations by large negative numbers.

The Binomial co-occurrence assessment approximates a Z-score.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Kintigh, K. (2006). Ceramic Dating and Type Associations. In J. Hantman and R. Most (eds.), Managing Archaeological Data: Essays in Honor of Sylvia W. Gaines. Anthropological Research Paper, 57. Tempe, AZ: Arizona State University, p. 17-26.

See Also

Other beta diversity measures: index_brainerd(), index_bray(), index_cody(), index_jaccard(), index_morisita(), index_routledge, index_sorensen(), index_whittaker(), index_wilson()

Boone Heterogeneity Measure

Description

Boone Heterogeneity Measure

Usage

index_boone(x, ...)

## S4 method for signature 'matrix'
index_boone(x, j = NULL, na.rm = FALSE, ...)

Arguments

x

A m \times p numeric matrix of count data (absolute frequencies, i.e. a contingency table).

...

Currently not used.

j

An integer giving the index of the reference type/taxa. If NULL (the default), the most frequent type/taxa in any assemblage will be used.

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Boone, J. L. (1987). Defining and Measuring Midden Catchment. American Antiquity, 52(2), 336-45. doi:10.2307/281785.

Kintigh, K. W. (1989). Sample Size, Significance, and Measures of Diversity. In Leonard, R. D. and Jones, G. T., Quantifying Diversity in Archaeology. New Directions in Archaeology. Cambridge: Cambridge University Press, p. 25-36.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), index_squares(), observed()

Brainerd-Robinson Quantitative Index

Description

Brainerd-Robinson Quantitative Index

Usage

index_brainerd(x, y, ...)

## S4 method for signature 'numeric,numeric'
index_brainerd(x, y)

Arguments

x, y

A numeric vector.

...

Currently not used.

Details

A city-block metric of similarity between pairs of samples/cases.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Brainerd, G. W. (1951). The Place of Chronological Ordering in Archaeological Analysis. American Antiquity, 16(04), 301-313. doi:10.2307/276979.

Robinson, W. S. (1951). A Method for Chronologically Ordering Archaeological Deposits. American Antiquity, 16(04), 293-301. doi:10.2307/276978.

See Also

Other beta diversity measures: index_binomial(), index_bray(), index_cody(), index_jaccard(), index_morisita(), index_routledge, index_sorensen(), index_whittaker(), index_wilson()

Bray-Curtis Similarity

Description

Bray and Curtis modified version of the Dice-Sorensen index.

Usage

index_bray(x, y, ...)

## S4 method for signature 'numeric,numeric'
index_bray(x, y)

Arguments

x, y

A numeric vector.

...

Currently not used.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Bray, J. R. & Curtis, J. T. (1957). An Ordination of the Upland Forest Communities of Southern Wisconsin. Ecological Monographs, 27(4), 325-349. doi:10.2307/1942268.

See Also

Other beta diversity measures: index_binomial(), index_brainerd(), index_cody(), index_jaccard(), index_morisita(), index_routledge, index_sorensen(), index_whittaker(), index_wilson()

Brillouin Diversity Index.

Description

Brillouin Diversity Index.

Usage

index_brillouin(x, ...)

## S4 method for signature 'numeric'
index_brillouin(x, evenness = FALSE, na.rm = FALSE, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

evenness

A numeric scalar: should evenness be computed?

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Details

The Brillouin index describes a known collection: it does not assume random sampling in an infinite population. Pielou (1975) and Laxton (1978) argues for the use of the Brillouin index in all circumstances, especially in preference to the Shannon index.

Value

A numeric vector.

Note

Ramanujan approximation is used for x! computation if x > 170.

Author(s)

N. Frerebeau

References

Brillouin, L. (1956). Science and information theory. New York: Academic Press.

Laxton, R. R. (1978). The measure of diversity. Journal of Theoretical Biology, 70(1), 51-67. doi:10.1016/0022-5193(78)90302-8.

Pielou, E. C. (1975). Ecological Diversity. New York: Wiley. doi:10.4319/lo.1977.22.1.0174b

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), index_squares(), observed()

Chao1 Estimator

Description

Chao1 Estimator

Usage

index_chao1(x, ...)

## S4 method for signature 'numeric'
index_chao1(x, unbiased = FALSE, improved = FALSE, na.rm = FALSE, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

unbiased

A logical scalar: should the bias-corrected estimator be used?

improved

A logical scalar: should the improved estimator be used?

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Chao, A. (1984). Nonparametric Estimation of the Number of Classes in a Population. Scandinavian Journal of Statistics, 11(4), 265-270.

Chiu, C.-H., Wang, Y.-T., Walther, B. A. & Chao, A. (2014). An improved nonparametric lower bound of species richness via a modified good-turing frequency formula. Biometrics, 70(3), 671-682. doi:10.1111/biom.12200.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), index_squares(), observed()

Chao2 Estimator

Description

Chao2 Estimator

Usage

index_chao2(x, ...)

## S4 method for signature 'matrix'
index_chao2(x, unbiased = FALSE, improved = FALSE, ...)

Arguments

x

A m \times p matrix of presence/absence data (incidence).

...

Currently not used.

unbiased

A logical scalar: should the bias-corrected estimator be used?

improved

A logical scalar: should the improved estimator be used?

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Chao, A. (1987). Estimating the Population Size for Capture-Recapture Data with Unequal Catchability. Biometrics 43(4), 783-791.

Chiu, C.-H., Wang, Y.-T., Walther, B. A. & Chao, A. (2014). An improved nonparametric lower bound of species richness via a modified good-turing frequency formula. Biometrics, 70(3), 671-682. doi:10.2307/2531532.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), index_squares(), observed()

Cody Measure

Description

Cody Measure

Usage

index_cody(x, ...)

## S4 method for signature 'matrix'
index_cody(x)

Arguments

x

A m \times p numeric matrix of count data (absolute frequencies, i.e. a contingency table).

...

Currently not used.

Details

This assumes that the order of the matrix rows (from 1 to n) follows the progression along the gradient/transect.

Data are standardized on a presence/absence scale (0/1) beforehand.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Cody, M. L. (1975). Towards a theory of continental species diversity: Bird distributions over Mediterranean habitat gradients. In M. L. Cody & J. M. Diamond (Eds.), Ecology and Evolution of Communities. Cambridge, MA: Harvard University Press, p. 214-257.

See Also

Other beta diversity measures: index_binomial(), index_brainerd(), index_bray(), index_jaccard(), index_morisita(), index_routledge, index_sorensen(), index_whittaker(), index_wilson()

Hurlbert's Rarefaction

Description

Hurlbert's unbiased estimate of Sander's rarefaction.

Usage

index_hurlbert(x, ...)

## S4 method for signature 'numeric'
index_hurlbert(x, sample, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

sample

A length-one numeric vector giving the sub-sample size. The size of sample should be smaller than total community size.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Hurlbert, S. H. (1971). The Nonconcept of Species Diversity: A Critique and Alternative Parameters. Ecology, 52(4), 577-586. doi:10.2307/1934145.

Sander, H. L. (1968). Marine Benthic Diversity: A Comparative Study. The American Naturalist, 102(925), 243-282.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), index_squares(), observed()

Incidence-based Coverage Estimator

Description

Incidence-based Coverage Estimator

Usage

index_ice(x, ...)

## S4 method for signature 'matrix'
index_ice(x, k = 10, ...)

Arguments

x

A m \times p matrix of presence/absence data (incidence).

...

Currently not used.

k

A length-one numeric vector giving the threshold between rare/infrequent and abundant/frequent species.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Chao, A. & Chiu, C.-H. (2016). Species Richness: Estimation and Comparison. In Balakrishnan, N., Colton, T., Everitt, B., Piegorsch, B., Ruggeri, F. & Teugels, J. L. (Eds.), Wiley StatsRef: Statistics Reference Online. Chichester, UK: John Wiley & Sons, Ltd., 1-26. doi:10.1002/9781118445112.stat03432.pub2

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), index_squares(), observed()

Jaccard Index

Description

Jaccard Index

Usage

index_jaccard(x, y, ...)

## S4 method for signature 'character,character'
index_jaccard(x, y)

## S4 method for signature 'logical,logical'
index_jaccard(x, y)

## S4 method for signature 'numeric,numeric'
index_jaccard(x, y)

Arguments

x, y

A numeric vector.

...

Currently not used.

Details

Data are standardized on a presence/absence scale (0/1) beforehand.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Magurran, A. E. (1988). Ecological Diversity and its Measurement. Princeton, NJ: Princeton University Press. doi:10.1007/978-94-015-7358-0.

See Also

Other beta diversity measures: index_binomial(), index_brainerd(), index_bray(), index_cody(), index_morisita(), index_routledge, index_sorensen(), index_whittaker(), index_wilson()

Margalef Richness Index

Description

Margalef Richness Index

Usage

index_margalef(x, ...)

## S4 method for signature 'numeric'
index_margalef(x, na.rm = FALSE, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Margalef, R. (1958). Information Theory in Ecology. General Systems, 3, 36-71.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), index_squares(), observed()

McIntosh Dominance Index.

Description

McIntosh Dominance Index.

Usage

index_mcintosh(x, ...)

## S4 method for signature 'numeric'
index_mcintosh(x, evenness = FALSE, na.rm = FALSE, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

evenness

A numeric scalar: should evenness be computed?

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Details

The McIntosh index expresses the heterogeneity of a sample in geometric terms. It describes the sample as a point of a S-dimensional hypervolume and uses the Euclidean distance of this point from the origin.

This is a dominance index, so that an increase in the value of the index accompanies a decrease in diversity.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

McIntosh, R. P. (1967). An Index of Diversity and the Relation of Certain Concepts to Diversity. Ecology, 48(3), 392-404. doi:10.2307/1932674.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_menhinick(), index_shannon(), index_simpson(), index_squares(), observed()

Menhinick Richness Index

Description

Menhinick Richness Index

Usage

index_menhinick(x, ...)

## S4 method for signature 'numeric'
index_menhinick(x, na.rm = FALSE, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Menhinick, E. F. (1964). A Comparison of Some Species-Individuals Diversity Indices Applied to Samples of Field Insects. Ecology, 45(4), 859-861. doi:10.2307/1934933.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_shannon(), index_simpson(), index_squares(), observed()

Morisita-Horn Quantitative Index

Description

Horn modified version of the Morisita overlap index.

Usage

index_morisita(x, y, ...)

## S4 method for signature 'numeric,numeric'
index_morisita(x, y)

Arguments

x, y

A numeric vector.

...

Currently not used.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Horn, H. S. (1966). Measurement of "Overlap" in Comparative Ecological Studies. The American Naturalist, 100(914): 419-424. doi:10.1086/282436.

Mosrisita, M. (1959). Measuring of interspecific association and similarity between communities. Memoirs of the Faculty of Science, Kyushu University, Series E, 3:65-80.

See Also

Other beta diversity measures: index_binomial(), index_brainerd(), index_bray(), index_cody(), index_jaccard(), index_routledge, index_sorensen(), index_whittaker(), index_wilson()

Routledge Measures

Description

Routledge Measures

Usage

index_routledge1(x, ...)

index_routledge2(x, ...)

index_routledge3(x, ...)

## S4 method for signature 'matrix'
index_routledge1(x)

## S4 method for signature 'matrix'
index_routledge2(x)

## S4 method for signature 'matrix'
index_routledge3(x)

Arguments

x

A m \times p numeric matrix of count data (absolute frequencies, i.e. a contingency table).

...

Currently not used.

Details

This assumes that the order of the matrix rows (from 1 to n) follows the progression along the gradient/transect.

Data are standardized on a presence/absence scale (0/1) beforehand.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Routledge, R. D. (1977). On Whittaker's Components of Diversity. Ecology, 58(5), 1120-1127. doi:10.2307/1936932.

See Also

Other beta diversity measures: index_binomial(), index_brainerd(), index_bray(), index_cody(), index_jaccard(), index_morisita(), index_sorensen(), index_whittaker(), index_wilson()

Shannon-Wiener Diversity Index

Description

Shannon-Wiener Diversity Index

Usage

index_shannon(x, ...)

## S4 method for signature 'numeric'
index_shannon(
  x,
  evenness = FALSE,
  unbiased = FALSE,
  ACE = FALSE,
  base = exp(1),
  na.rm = FALSE,
  ...
)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

evenness

A numeric scalar: should evenness be computed?

unbiased

A logical scalar: should the bias-corrected estimator be used?

ACE

A logical scalar: should the ACE species richness estimator be used in the bias correction?

base

A positive numeric value specifying the base with respect to which logarithms are computed.

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Details

The Shannon index assumes that individuals are randomly sampled from an infinite population and that all taxa are represented in the sample (it does not reflect the sample size). The main source of error arises from the failure to include all taxa in the sample: this error increases as the proportion of species discovered in the sample declines (Peet 1974, Magurran 1988). The maximum likelihood estimator (MLE) is used for the relative abundance, this is known to be negatively biased by sample size.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Peet, R. K. (1974). The Measurement of Species Diversity. Annual Review of Ecology and Systematics, 5(1), 285-307. doi:10.1146/annurev.es.05.110174.001441.

Magurran, A. E. (1988). Ecological Diversity and its Measurement. Princeton, NJ: Princeton University Press. doi:10.1007/978-94-015-7358-0.

Shannon, C. E. (1948). A Mathematical Theory of Communication. The Bell System Technical Journal, 27, 379-423. doi:10.1002/j.1538-7305.1948.tb01338.x.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_simpson(), index_squares(), observed()

Simpson Dominance Index

Description

Simpson Dominance Index

Usage

index_simpson(x, ...)

## S4 method for signature 'numeric'
index_simpson(x, evenness = FALSE, unbiased = FALSE, na.rm = FALSE, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

evenness

A numeric scalar: should evenness be computed?

unbiased

A logical scalar: should the bias-corrected estimator be used?

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Details

The Simpson index expresses the probability that two individuals randomly picked from a finite sample belong to two different types. It can be interpreted as the weighted mean of the proportional abundances. This metric is a true probability value, it ranges from 0 (all taxa are equally present) to 1 (one taxon dominates the community completely).

This is a dominance index, so that an increase in the value of the index accompanies a decrease in diversity.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Simpson, E. H. (1949). Measurement of Diversity. Nature, 163(4148), 688-688. doi:10.1038/163688a0.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_squares(), observed()

Dice-Sorensen Qualitative Index

Description

Dice-Sorensen Qualitative Index

Usage

index_sorensen(x, y, ...)

## S4 method for signature 'logical,logical'
index_sorensen(x, y)

## S4 method for signature 'numeric,numeric'
index_sorensen(x, y)

Arguments

x, y

A numeric vector.

...

Currently not used.

Details

Data are standardized on a presence/absence scale (0/1) beforehand.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Dice, L. R. (1945). Measures of the Amount of Ecologic Association Between Species. Ecology, 26(3): 297-302. doi:10.2307/1932409

Sorensen, T. (1948). A Method of Establishing Groups of Equal Amplitude in Plant Sociology Based on Similarity of Species Content and Its Application to Analyses of the Vegetation on Danish Commons. Kongelige Danske Videnskabernes Selskab, 5(4): 1-34.

See Also

Other beta diversity measures: index_binomial(), index_brainerd(), index_bray(), index_cody(), index_jaccard(), index_morisita(), index_routledge, index_whittaker(), index_wilson()

Squares Estimator

Description

Squares Estimator

Usage

index_squares(x, ...)

## S4 method for signature 'numeric'
index_squares(x, na.rm = FALSE, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Alroy, J. (2018). Limits to Species Richness in Terrestrial Communities. Ecology Letters, 21(12), 1781-1789. doi:10.1111/ele.13152.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), observed()

Whittaker Measure

Description

Whittaker Measure

Usage

index_whittaker(x, ...)

## S4 method for signature 'matrix'
index_whittaker(x)

Arguments

x

A m \times p numeric matrix of count data (absolute frequencies, i.e. a contingency table).

...

Currently not used.

Details

This assumes that the order of the matrix rows (from 1 to n) follows the progression along the gradient/transect.

Data are standardized on a presence/absence scale (0/1) beforehand.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Whittaker, R. H. (1960). Vegetation of the Siskiyou Mountains, Oregon and California. Ecological Monographs, 30(3), 279-338. doi:10.2307/1943563.

See Also

Other beta diversity measures: index_binomial(), index_brainerd(), index_bray(), index_cody(), index_jaccard(), index_morisita(), index_routledge, index_sorensen(), index_wilson()

Wilson Measure

Description

Wilson Measure

Usage

index_wilson(x, ...)

## S4 method for signature 'matrix'
index_wilson(x)

Arguments

x

A m \times p numeric matrix of count data (absolute frequencies, i.e. a contingency table).

...

Currently not used.

Details

This assumes that the order of the matrix rows (from 1 to n) follows the progression along the gradient/transect.

Data are standardized on a presence/absence scale (0/1) beforehand.

Value

A numeric vector.

Author(s)

N. Frerebeau

References

Wilson, M. V., & Shmida, A. (1984). Measuring Beta Diversity with Presence-Absence Data. The Journal of Ecology, 72(3), 1055-1064. doi:10.2307/2259551.

See Also

Other beta diversity measures: index_binomial(), index_brainerd(), index_bray(), index_cody(), index_jaccard(), index_morisita(), index_routledge, index_sorensen(), index_whittaker()

Jackknife Estimation

Description

Jackknife Estimation

Usage

## S4 method for signature 'DiversityIndex'
jackknife(object, f = NULL)

Arguments

object

An R object (typically a DiversityIndex object).

f

A function that takes a single numeric vector (the leave-one-out values) as argument.

Value

If f is NULL (the default), jackknife() returns a numeric matrix with the following columns:

original

The observed value.

mean

The jackknife estimate of mean.

bias

The jackknife estimate of bias.

error

The jackknife estimate of standard error.

If f is a function, jackknife() returns the result of f applied to the leave-one-out values.

Author(s)

N. Frerebeau

See Also

Other resampling methods: bootstrap()

Examples

## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## Shannon diversity index
(h <- heterogeneity(cantabria, method = "shannon"))

## Jackknife resampling
jackknife(h)

jackknife(h, f = summary)

Matrigraph

Description

Usage

matrigraph(object, ...)

pvi(object, ...)

## S4 method for signature 'matrix'
pvi(object)

## S4 method for signature 'data.frame'
pvi(object)

## S4 method for signature 'matrix'
matrigraph(object, reverse = FALSE, axes = TRUE, ...)

## S4 method for signature 'data.frame'
matrigraph(object, reverse = FALSE, ...)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table).

...

Currently not used.

reverse

A logical scalar: should negative deviations be centered (see details)?

axes

A logical scalar: should axes be drawn on the plot? It will omit labels where they would abut or overlap previously drawn labels.

Details

PVI (in french "pourcentages de valeur d'indépendance") is calculated for each cell as the percentage to the column theoretical independence value: PVI greater than 1 represent positive deviations from the independence, whereas PVI smaller than 1 represent negative deviations (Desachy 2004).

The PVI matrix allows to explore deviations from independence (an intuitive approach to \chi^2), in such a way that a high-contrast matrix has quite significant deviations, with a low risk of being due to randomness (Desachy 2004).

matrigraph() displays the deviations from independence:

If reverse is TRUE, the fraction of negative deviations is displayed as a white square.

Value

Author(s)

N. Frerebeau

References

Desachy, B. (2004). Le sériographe EPPM: un outil informatisé de sériation graphique pour tableaux de comptages. Revue archéologique de Picardie, 3(1), 39-56. doi:10.3406/pica.2004.2396.

See Also

plot_heatmap()

Other plot methods: plot_bertin(), plot_diceleraas(), plot_ford(), plot_heatmap(), plot_rank(), plot_spot(), seriograph()

Examples

## Data from Desachy 2004
data("compiegne", package = "folio")

## Matrigraph
matrigraph(compiegne)
matrigraph(compiegne, reverse = TRUE)

## Compute PVI
counts_pvi <- pvi(compiegne)
plot_heatmap(counts_pvi, col = khroma::color("iridescent")(12))

Get or Set Parts of an Object

Description

Getters and setters to extract or replace parts of an object.

Usage

get_method(x)

## S4 method for signature 'DiversityIndex'
labels(object, ...)

## S4 method for signature 'RarefactionIndex'
labels(object, ...)

## S4 method for signature 'DiversityIndex'
get_method(x)

Arguments

object, x

An R object from which to get or set element(s).

...

Currently not used.

Value

Author(s)

N. Frerebeau

See Also

Other mutators: data.frame

Number of Observed Species

Description

Number of Observed Species

Usage

observed(x, ...)

singleton(x, ...)

doubleton(x, ...)

## S4 method for signature 'numeric'
observed(x, na.rm = FALSE, ...)

## S4 method for signature 'numeric'
singleton(x, na.rm = FALSE, ...)

## S4 method for signature 'numeric'
doubleton(x, na.rm = FALSE, ...)

Arguments

x

A numeric vector of count data (absolute frequencies).

...

Currently not used.

na.rm

A numeric scalar: should missing values (including NaN) be removed?

Value

A numeric vector.

See Also

Other alpha diversity measures: index_ace(), index_baxter(), index_berger(), index_boone(), index_brillouin(), index_chao1(), index_chao2(), index_hurlbert(), index_ice(), index_margalef(), index_mcintosh(), index_menhinick(), index_shannon(), index_simpson(), index_squares()

Co-Occurrence

Description

Co-Occurrence

Usage

occurrence(object, ...)

## S4 method for signature 'matrix'
occurrence(object, method = c("absolute", "relative", "binomial"))

## S4 method for signature 'data.frame'
occurrence(object, method = c("absolute", "relative", "binomial"))

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Currently not used.

method

A character string specifying the method to be used. It must be one of "absolute", "relative" or "binomial" (see details). Any unambiguous substring can be given.

Details

absolute

Count how many times each pairs of types occur together in at least one sample (absolute frequencies).

relative

Count how many times each pairs of types occur together in at least one sample (relative frequencies).

binomial

Binomial co-occurrence assessment.

Value

A stats::dist object.

Author(s)

N. Frerebeau

See Also

Other diversity measures: diversity(), evenness(), heterogeneity(), plot.DiversityIndex(), plot.RarefactionIndex(), profiles(), rarefaction(), richness(), she(), similarity(), simulate(), turnover()

Examples

## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## Plot spot diagram of a co-occurrence matrix
occ_abs <- occurrence(cantabria, method = "absolute") # Absolute frequencies
plot_spot(occ_abs)

occ_rel <- occurrence(cantabria, method = "relative") # Relative frequencies
plot_spot(occ_rel)

## Binomial co-occurrence (similarity between types)
occ_bin <- occurrence(cantabria, method = "binomial")
plot_spot(occ_bin)

Diversity Plot

Description

Diversity Plot

Usage

## S4 method for signature 'DiversityIndex,missing'
plot(
  x,
  log = "x",
  col.mean = "#DDAA33",
  col.interval = "#004488",
  lty.mean = "solid",
  lty.interval = "dashed",
  lwd.mean = 1,
  lwd.interval = 1,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

Arguments

x

A DiversityIndex object to be plotted.

log

A character string indicating which axes should be in log scale. Defaults to x.

col.mean, col.interval

A character string specifying the color of the lines.

lty.mean, lty.interval

A character string or numeric value specifying the line types.

lwd.mean, lwd.interval

A non-negative numeric value specifying the line widths.

xlab, ylab

A character vector giving the x and y axis labels.

main

A character string giving a main title for the plot.

sub

A character string giving a subtitle for the plot.

ann

A logical scalar: should the default annotation (title and x, y and z axis labels) appear on the plot?

axes

A logical scalar: should axes be drawn on the plot?

frame.plot

A logical scalar: should a box be drawn around the plot?

panel.first

An an expression to be evaluated after the plot axes are set up but before any plotting takes place. This can be useful for drawing background grids.

panel.last

An expression to be evaluated after plotting has taken place but before the axes, title and box are added.

...

Further graphical parameters to be passed to graphics::points(), particularly, cex, col and pch.

Value

plot() is called for its side-effects: it results in a graphic being displayed (invisibly returns x).

Author(s)

N. Frerebeau

See Also

Other diversity measures: diversity(), evenness(), heterogeneity(), occurrence(), plot.RarefactionIndex(), profiles(), rarefaction(), richness(), she(), similarity(), simulate(), turnover()

Examples


## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## Assemblage diversity size comparison
## Warning: this may take a few seconds!
h <- heterogeneity(cantabria, method = "shannon")
h_sim <- simulate(h)
plot(h_sim)

r <- richness(cantabria, method = "observed")
r_sim <- simulate(r)
plot(r_sim)

Rarefaction Plot

Description

Rarefaction Plot

Usage

## S4 method for signature 'RarefactionIndex,missing'
plot(
  x,
  color = NULL,
  symbol = FALSE,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  legend = list(x = "topleft"),
  ...
)

Arguments

x

A RarefactionIndex object to be plotted.

color

A vector of colors (will be mapped to the rownames of object). If color is a named a named vector, then the colors will be associated with the rownames of object. Ignored if set to FALSE.

symbol

A specification for the line type (will be mapped to the names of x). If symbol is a named a named vector, then the line types will be associated with the names of x. Ignored if set to FALSE.

xlab, ylab

A character vector giving the x and y axis labels.

main

A character string giving a main title for the plot.

sub

A character string giving a subtitle for the plot.

ann

A logical scalar: should the default annotation (title and x, y and z axis labels) appear on the plot?

axes

A logical scalar: should axes be drawn on the plot?

frame.plot

A logical scalar: should a box be drawn around the plot?

panel.first

An an expression to be evaluated after the plot axes are set up but before any plotting takes place. This can be useful for drawing background grids.

panel.last

An expression to be evaluated after plotting has taken place but before the axes, title and box are added.

legend

A list of additional arguments to be passed to graphics::legend(); names of the list are used as argument names. If NULL, no legend is displayed.

...

Further graphical parameters to be passed to graphics::lines().

Value

plot() is called for its side-effects: it results in a graphic being displayed (invisibly returns x).

Author(s)

N. Frerebeau

See Also

Other diversity measures: diversity(), evenness(), heterogeneity(), occurrence(), plot.DiversityIndex(), profiles(), rarefaction(), richness(), she(), similarity(), simulate(), turnover()

Examples

## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## Replicate fig. 3 from Baxter 2011
rare <- rarefaction(cantabria, sample = 23, method = "baxter")
plot(rare, panel.first = graphics::grid())

## Change graphical parameters
plot(rare, color = color("bright")(5), symbol = 1:5)

Bertin Diagram

Description

Plots a Bertin diagram.

Usage

plot_bertin(object, ...)

## S4 method for signature 'matrix'
plot_bertin(
  object,
  threshold = NULL,
  freq = FALSE,
  margin = 1,
  color = c("white", "black"),
  flip = TRUE,
  axes = TRUE,
  ...
)

## S4 method for signature 'data.frame'
plot_bertin(
  object,
  threshold = NULL,
  freq = FALSE,
  margin = 1,
  color = c("white", "black"),
  flip = TRUE,
  axes = TRUE,
  ...
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table).

...

Currently not used.

threshold

A function that takes a numeric vector as argument and returns a numeric threshold value (see below). If NULL (the default), no threshold is computed. Only used if freq is FALSE.

freq

A logical scalar indicating whether conditional proportions given margins should be used (i.e. entries of object, divided by the appropriate marginal sums).

margin

An integer vector giving the margins to split by: 1 indicates individuals/rows (the default), 2 indicates variables/columns. Only used if freq is TRUE.

color

A vector of colors or a function that when called with a single argument (an integer specifying the number of colors) returns a vector of colors.

flip

A logical scalar: should x and y axis be flipped? Defaults to TRUE.

axes

A logical scalar: should axes be drawn on the plot? It will omit labels where they would abut or overlap previously drawn labels.

Details

As de Falguerolles et al. (1997) points out: "In abstract terms, a Bertin matrix is a matrix of displays. [...] To fix ideas, think of a data matrix, variable by case, with real valued variables. For each variable, draw a bar chart of variable value by case. High-light all bars representing a value above some sample threshold for that variable."

Value

plot_bertin() is called for its side-effects: it results in a graphic being displayed (invisibly returns object).

Author(s)

N. Frerebeau

References

Bertin, J. (1977). La graphique et le traitement graphique de l'information. Paris: Flammarion. Nouvelle Bibliothèque Scientifique.

de Falguerolles, A., Friedrich, F. & Sawitzki, G. (1997). A Tribute to J. Bertin's Graphical Data Analysis. In W. Badilla & F. Faulbaum (eds.), SoftStat '97: Advances in Statistical Software 6. Stuttgart: Lucius & Lucius, p. 11-20.

See Also

Other plot methods: matrigraph(), plot_diceleraas(), plot_ford(), plot_heatmap(), plot_rank(), plot_spot(), seriograph()

Examples

## Data from Lipo et al. 2015
data("mississippi", package = "folio")

## Plot a Bertin diagram...
## ...without threshold
plot_bertin(mississippi)

## ...with the variable mean as threshold
plot_bertin(mississippi, threshold = mean)

## Plot conditional proportions
plot_bertin(mississippi, freq = TRUE, margin = 1)
plot_bertin(mississippi, freq = TRUE, margin = 2)

Dice-Leraas Diagram

Description

Plots a Dice-Leraas diagram.

Usage

plot_diceleraas(object, ...)

## S4 method for signature 'matrix'
plot_diceleraas(
  object,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = FALSE,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

## S4 method for signature 'data.frame'
plot_diceleraas(
  object,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = FALSE,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Further graphical parameters.

main

A character string giving a main title for the plot.

sub

A character string giving a subtitle for the plot.

ann

A logical scalar: should the default annotation (title and x, y and z axis labels) appear on the plot?

axes

A logical scalar: should axes be drawn on the plot?

frame.plot

A logical scalar: should a box be drawn around the plot?

panel.first

An an expression to be evaluated after the plot axes are set up but before any plotting takes place. This can be useful for drawing background grids.

panel.last

An expression to be evaluated after plotting has taken place but before the axes, title and box are added.

Details

In a Dice-Leraas diagram, the horizontal line represents the range of data (min-max) and the small vertical line indicates the mean. The black rectangle is twice the standard error on the mean, while the white rectangle is one standard deviation on either side of the mean.

Value

plot_diceleraas() is called for its side-effects: it results in a graphic being displayed (invisibly returns object).

Author(s)

N. Frerebeau

References

Dice, L. R., & Leraas, H. J. (1936). A Graphic Method for Comparing Several Sets of Measurements. Contributions from the Laboratory of Vertebrate Genetics, 3: 1-3.

Hubbs, C. L., & C. Hubbs (1953). An Improved Graphical Analysis and Comparison of Series of Samples. Systematic Biology, 2(2): 49-56. doi:10.2307/sysbio/2.2.49.

Simpson, G. G., Roe, A., & Lewontin, R. C. Quantitative Zoology. New York: Harcourt, Brace and Company, 1960.

See Also

Other plot methods: matrigraph(), plot_bertin(), plot_ford(), plot_heatmap(), plot_rank(), plot_spot(), seriograph()

Examples

## Data from Desachy 2004
data("compiegne", package = "folio")

## Plot a Dice-Leraas diagram
plot_diceleraas(compiegne)

Ford Diagram

Description

Plots a Ford (battleship curve) diagram.

Usage

plot_ford(object, ...)

## S4 method for signature 'matrix'
plot_ford(
  object,
  weights = FALSE,
  EPPM = FALSE,
  fill = "darkgrey",
  border = NA,
  axes = TRUE,
  ...
)

## S4 method for signature 'data.frame'
plot_ford(
  object,
  weights = FALSE,
  EPPM = FALSE,
  fill = "darkgrey",
  border = NA,
  axes = TRUE,
  ...
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table).

...

Currently not used.

weights

A logical scalar: should the row sums be displayed?

EPPM

A logical scalar: should the EPPM be drawn? See seriograph().

fill

The color for filling the bars.

border

The color to draw the borders.

axes

A logical scalar: should axes be drawn on the plot? It will omit labels where they would abut or overlap previously drawn labels.

Value

plot_ford() is called for its side-effects: it results in a graphic being displayed (invisibly returns object).

Author(s)

N. Frerebeau

References

Ford, J. A. (1962). A quantitative method for deriving cultural chronology. Washington, DC: Pan American Union. Technical manual 1.

See Also

Other plot methods: matrigraph(), plot_bertin(), plot_diceleraas(), plot_heatmap(), plot_rank(), plot_spot(), seriograph()

Examples

## Data from Lipo et al. 2015
data("mississippi", package = "folio")

## Plot a Ford diagram
plot_ford(mississippi)

plot_ford(mississippi, weights = TRUE)

Heatmap

Description

Plots a heatmap.

Usage

plot_heatmap(object, ...)

## S4 method for signature 'matrix'
plot_heatmap(
  object,
  color = NULL,
  diag = TRUE,
  upper = TRUE,
  lower = TRUE,
  freq = FALSE,
  margin = 1,
  fixed_ratio = TRUE,
  axes = TRUE,
  legend = TRUE,
  ...
)

## S4 method for signature 'data.frame'
plot_heatmap(
  object,
  color = NULL,
  diag = TRUE,
  upper = TRUE,
  lower = TRUE,
  freq = FALSE,
  margin = 1,
  fixed_ratio = TRUE,
  axes = TRUE,
  legend = TRUE,
  ...
)

## S4 method for signature 'dist'
plot_heatmap(
  object,
  color = NULL,
  diag = FALSE,
  upper = FALSE,
  lower = !upper,
  axes = TRUE,
  legend = TRUE,
  ...
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table).

...

Currently not used.

color

A vector of colors or a function that when called with a single argument (an integer specifying the number of colors) returns a vector of colors.

diag

A logical scalar indicating whether the diagonal of the matrix should be plotted. Only used if object is a symmetric matrix.

upper

A logical scalar indicating whether the upper triangle of the matrix should be plotted. Only used if object is a symmetric matrix.

lower

A logical scalar indicating whether the lower triangle of the matrix should be plotted. Only used if object is a symmetric matrix.

freq

A logical scalar indicating whether conditional proportions given margins should be used (i.e. entries of object, divided by the appropriate marginal sums).

margin

An integer vector giving the margins to split by: 1 indicates individuals/rows (the default), 2 indicates variables/columns. Only used if freq is TRUE.

fixed_ratio

A logical scalar: should a fixed aspect ratio (1) be used?

axes

A logical scalar: should axes be drawn on the plot? It will omit labels where they would abut or overlap previously drawn labels.

legend

A logical scalar: should a legend be displayed?

Value

plot_heatmap() is called for its side-effects: it results in a graphic being displayed (invisibly returns object).

Author(s)

N. Frerebeau

See Also

Other plot methods: matrigraph(), plot_bertin(), plot_diceleraas(), plot_ford(), plot_rank(), plot_spot(), seriograph()

Examples

## Data from Lipo et al. 2015
data("mississippi", package = "folio")

## Plot raw data
plot_heatmap(mississippi)

## Change colors
plot_heatmap(mississippi, color = color("iridescent"))

## Plot conditional proportions
plot_heatmap(mississippi, freq = TRUE, margin = 1)
plot_heatmap(mississippi, freq = TRUE, margin = 2)

Matrix Plot

Description

Matrix Plot

Usage

plot_matrix(
  object,
  panel,
  diag = TRUE,
  upper = TRUE,
  lower = TRUE,
  freq = FALSE,
  margin = 1,
  scale = TRUE,
  drop_zero = TRUE,
  color = graphics::par("fg"),
  midpoint = NULL,
  axes = TRUE,
  legend = TRUE,
  asp = 1,
  ...
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table).

panel

A function in the form ⁠function(x, y, z, color, ...)⁠ which gives the action to be carried out in each panel of the display.

diag

A logical scalar indicating whether the diagonal of the matrix should be plotted. Only used if object is a symmetric matrix.

upper

A logical scalar indicating whether the upper triangle of the matrix should be plotted. Only used if object is a symmetric matrix.

lower

A logical scalar indicating whether the lower triangle of the matrix should be plotted. Only used if object is a symmetric matrix.

freq

A logical scalar indicating whether conditional proportions given margins should be used (i.e. entries of object, divided by the appropriate marginal sums).

margin

An integer vector giving the margins to split by: 1 indicates individuals/rows (the default), 2 indicates variables/columns. Only used if freq is TRUE.

scale

A logical scalar indicating whether data should be rescaled to [-1,1]. Only used if freq if FALSE.

drop_zero

A logical scalar: should zeros be discarded?

color

A vector of colors or a function that when called with a single argument (an integer specifying the number of colors) returns a vector of colors.

midpoint

A numeric value specifying the data midpoint.

axes

A logical scalar: should axes be drawn on the plot? It will omit labels where they would abut or overlap previously drawn labels.

legend

A logical scalar: should a legend be displayed?

asp

A length-one numeric vector, giving the aspect ratio y/x.

...

Further arguments to be passed to panel.

Rank Plot

Description

Plots a rank vs relative abundance diagram.

Usage

plot_rank(object, ...)

## S4 method for signature 'matrix'
plot_rank(
  object,
  log = NULL,
  color = NULL,
  symbol = FALSE,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  legend = list(x = "topright"),
  ...
)

## S4 method for signature 'data.frame'
plot_rank(
  object,
  log = NULL,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  legend = list(x = "topright"),
  ...
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Further graphical parameters.

log

A character string which contains "x" if the x axis is to be logarithmic, "y" if the y axis is to be logarithmic and "xy" or "yx" if both axes are to be logarithmic (base 10).

color

A vector of colors (will be mapped to the rownames of object). If color is a named a named vector, then the colors will be associated with the rownames of object. Ignored if set to FALSE.

symbol

A specification for the line type (will be mapped to the rownames of object). If symbol is a named a named vector, then the line types will be associated with the rownames of object. Ignored if set to FALSE.

xlab, ylab

A character vector giving the x and y axis labels.

main

A character string giving a main title for the plot.

sub

A character string giving a subtitle for the plot.

ann

A logical scalar: should the default annotation (title and x, y and z axis labels) appear on the plot?

axes

A logical scalar: should axes be drawn on the plot?

frame.plot

A logical scalar: should a box be drawn around the plot?

panel.first

An an expression to be evaluated after the plot axes are set up but before any plotting takes place. This can be useful for drawing background grids.

panel.last

An expression to be evaluated after plotting has taken place but before the axes, title and box are added.

legend

A list of additional arguments to be passed to graphics::legend(); names of the list are used as argument names. If NULL, no legend is displayed.

Value

plot_rank() is called for its side-effects: it results in a graphic being displayed (invisibly returns object).

Author(s)

N. Frerebeau

References

Magurran, A. E. (1988). Ecological Diversity and its Measurement. Princeton, NJ: Princeton University Press. doi:10.1007/978-94-015-7358-0.

See Also

Other plot methods: matrigraph(), plot_bertin(), plot_diceleraas(), plot_ford(), plot_heatmap(), plot_spot(), seriograph()

Examples

## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## Plot rank vs abundance
plot_rank(cantabria)

## Change graphical parameters
plot_rank(cantabria, color = color("bright"), symbol = 15:19)

Spot Plot

Description

Plots a spot matrix.

Usage

plot_spot(object, ...)

## S4 method for signature 'matrix'
plot_spot(
  object,
  type = c("ring", "plain"),
  color = NULL,
  diag = TRUE,
  upper = TRUE,
  lower = TRUE,
  freq = FALSE,
  margin = 1,
  axes = TRUE,
  legend = TRUE,
  ...
)

## S4 method for signature 'data.frame'
plot_spot(
  object,
  type = c("ring", "plain"),
  color = NULL,
  diag = TRUE,
  upper = TRUE,
  lower = TRUE,
  freq = FALSE,
  margin = 1,
  axes = TRUE,
  legend = TRUE,
  ...
)

## S4 method for signature 'dist'
plot_spot(
  object,
  type = c("ring", "plain"),
  color = NULL,
  diag = FALSE,
  upper = FALSE,
  lower = !upper,
  axes = TRUE,
  legend = TRUE,
  ...
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table).

...

Currently not used.

type

A character string specifying the graph to be plotted. It must be one of "ring" (the default) or "plain". Any unambiguous substring can be given.

color

A vector of colors or a function that when called with a single argument (an integer specifying the number of colors) returns a vector of colors.

diag

A logical scalar indicating whether the diagonal of the matrix should be plotted. Only used if object is a symmetric matrix.

upper

A logical scalar indicating whether the upper triangle of the matrix should be plotted. Only used if object is a symmetric matrix.

lower

A logical scalar indicating whether the lower triangle of the matrix should be plotted. Only used if object is a symmetric matrix.

freq

A logical scalar indicating whether conditional proportions given margins should be used (i.e. entries of object, divided by the appropriate marginal sums).

margin

An integer vector giving the margins to split by: 1 indicates individuals/rows (the default), 2 indicates variables/columns. Only used if freq is TRUE.

axes

A logical scalar: should axes be drawn on the plot? It will omit labels where they would abut or overlap previously drawn labels.

legend

A logical scalar: should a legend be displayed?

Details

The spot matrix can be considered as a variant of the Bertin diagram where the data are first transformed to relative frequencies.

Value

plot_spot() is called for its side-effects: it results in a graphic being displayed (invisibly returns object).

Note

Adapted from Dan Gopstein's original idea.

Author(s)

N. Frerebeau

See Also

Other plot methods: matrigraph(), plot_bertin(), plot_diceleraas(), plot_ford(), plot_heatmap(), plot_rank(), seriograph()

Examples

## Data from Huntley 2004, 2008
data("pueblo")

## Plot spot diagram of count data
plot_spot(pueblo, type = "ring")
plot_spot(pueblo, type = "plain")

## Plot conditional proportions
plot_spot(pueblo, freq = TRUE, margin = 1)
plot_spot(pueblo, freq = TRUE, margin = 2)

Diversity Profiles

Description

Diversity Profiles

Usage

profiles(object, ...)

## S4 method for signature 'matrix'
profiles(
  object,
  alpha = seq(from = 0, to = 4, by = 0.04),
  color = NULL,
  symbol = FALSE,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  legend = list(x = "topright"),
  ...
)

## S4 method for signature 'data.frame'
profiles(
  object,
  alpha = seq(from = 0, to = 4, by = 0.04),
  color = NULL,
  symbol = FALSE,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  legend = list(x = "topright"),
  ...
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Further graphical parameters to be passed to graphics::lines()

alpha

A numeric vector giving the values of the alpha parameter.

color

A vector of colors (will be mapped to the rownames of object). If color is a named a named vector, then the colors will be associated with the rownames of object. Ignored if set to FALSE.

symbol

A specification for the line type (will be mapped to the rownames of object). If symbol is a named a named vector, then the line types will be associated with the rownames of object. Ignored if set to FALSE.

xlab, ylab

A character vector giving the x and y axis labels.

main

A character string giving a main title for the plot.

sub

A character string giving a subtitle for the plot.

ann

A logical scalar: should the default annotation (title and x, y and z axis labels) appear on the plot?

axes

A logical scalar: should axes be drawn on the plot?

frame.plot

A logical scalar: should a box be drawn around the plot?

panel.first

An an expression to be evaluated after the plot axes are set up but before any plotting takes place. This can be useful for drawing background grids.

panel.last

An expression to be evaluated after plotting has taken place but before the axes, title and box are added.

legend

A list of additional arguments to be passed to graphics::legend(); names of the list are used as argument names. If NULL, no legend is displayed.

Details

If the profiles cross, the diversities are non-comparable across samples.

Value

profiles() is called for its side-effects: it results in a graphic being displayed (invisibly returns object).

Author(s)

N. Frerebeau

References

Tóthmérész, B. (1995). Comparison of Different Methods for Diversity Ordering. Journal of Vegetation Science, 6(2), 283-290. doi:10.2307/3236223.

See Also

Other diversity measures: diversity(), evenness(), heterogeneity(), occurrence(), plot.DiversityIndex(), plot.RarefactionIndex(), rarefaction(), richness(), she(), similarity(), simulate(), turnover()

Examples

## Replicate fig. 1 of Tóthmérész 1995
spc <- matrix(
  data = c(33, 29, 28, 5, 5, 0, 0, 42, 30, 10,
           8, 5, 5, 0, 32, 21, 16, 12, 9, 6, 4),
  nrow = 3, byrow = TRUE, dimnames = list(c("Z", "B", "C"), NULL)
)

profiles(spc, color = color("bright"))

Pueblo IV Period Ceramics

Description

A dataset of ceramic counts from the Zuni region.

Usage

pueblo

Format

A data.frame with 9 rows and 5 variables (compositional groups).

Source

Huntley, D. L. (2004). Interaction, Boundaries, and Identities: A Multiscalar Approach to the Organizational Scale of Pueblo IV Zuni Society. Ph.D. Dissertation, Arizona State University.

Huntley, D. L. (2022). Ancestral Zuni Glaze-Decorated Pottery: Viewing Pueblo IV Regional Organization through Ceramic Production and Exchange. Anthropological Papers of the University of Arizona 72. Tucson: University of Arizona Press. doi:10.2307/j.ctv2ngx5n8.

See Also

Other datasets: aves, cantabria, woodland

Rarefaction

Description

Rarefaction

Usage

rarefaction(object, ...)

## S4 method for signature 'matrix'
rarefaction(object, sample = NULL, method = c("hurlbert", "baxter"), step = 1)

## S4 method for signature 'data.frame'
rarefaction(object, sample = NULL, method = c("hurlbert", "baxter"), step = 1)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Currently not used.

sample

A length-one numeric vector giving the sub-sample size. The size of sample should be smaller than total community size.

method

A character string or vector of strings specifying the index to be computed (see details). Any unambiguous substring can be given.

step

An integer giving the increment of the sample size.

Value

A RarefactionIndex object.

Rarefaction Measures

The following rarefaction measures are available for count data:

baxter

Baxter's rarefaction.

hurlbert

Hurlbert's unbiased estimate of Sander's rarefaction.

Details

The number of observed taxa, provides an instantly comprehensible expression of diversity. While the number of taxa within a sample is easy to ascertain, as a term, it makes little sense: some taxa may not have been seen, or there may not be a fixed number of taxa (e.g. in an open system; Peet 1974). As an alternative, richness (S) can be used for the concept of taxa number (McIntosh 1967).

It is not always possible to ensure that all sample sizes are equal and the number of different taxa increases with sample size and sampling effort (Magurran 1988). Then, rarefaction (E(S)) is the number of taxa expected if all samples were of a standard size (i.e. taxa per fixed number of individuals). Rarefaction assumes that imbalances between taxa are due to sampling and not to differences in actual abundances.

Author(s)

N. Frerebeau

See Also

index_baxter(), index_hurlbert(), plot()

Other diversity measures: diversity(), evenness(), heterogeneity(), occurrence(), plot.DiversityIndex(), plot.RarefactionIndex(), profiles(), richness(), she(), similarity(), simulate(), turnover()

Examples

## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## Replicate fig. 3 from Baxter 2011
rare <- rarefaction(cantabria, sample = 23, method = "baxter")
plot(rare, panel.first = graphics::grid())

## Change graphical parameters
plot(rare, color = color("bright")(5), symbol = 1:5)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

khroma

color, palette_color_continuous, palette_color_discrete, palette_color_picker

Richness

Description

Usage

richness(object, ...)

composition(object, ...)

## S4 method for signature 'matrix'
richness(object, ..., method = c("observed", "margalef", "menhinick"))

## S4 method for signature 'data.frame'
richness(object, ..., method = c("observed", "margalef", "menhinick"))

## S4 method for signature 'matrix'
composition(object, ..., method = c("chao1", "ace", "squares", "chao2", "ice"))

## S4 method for signature 'data.frame'
composition(object, ..., method = c("chao1", "ace", "squares", "chao2", "ice"))

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Further arguments to be passed to internal methods (see below).

method

A character string or vector of strings specifying the index to be computed (see details). Any unambiguous substring can be given.

Value

Details

The number of observed taxa, provides an instantly comprehensible expression of diversity. While the number of taxa within a sample is easy to ascertain, as a term, it makes little sense: some taxa may not have been seen, or there may not be a fixed number of taxa (e.g. in an open system; Peet 1974). As an alternative, richness (S) can be used for the concept of taxa number (McIntosh 1967).

It is not always possible to ensure that all sample sizes are equal and the number of different taxa increases with sample size and sampling effort (Magurran 1988). Then, rarefaction (E(S)) is the number of taxa expected if all samples were of a standard size (i.e. taxa per fixed number of individuals). Rarefaction assumes that imbalances between taxa are due to sampling and not to differences in actual abundances.

Richness Measures

The following richness measures are available for count data:

observed

Number of observed taxa/types.

margalef

Margalef richness index.

menhinick

Menhinick richness index.

Asymptotic Species Richness

The following measures are available for count data:

ace

Abundance-based Coverage Estimator.

chao1

(improved/unbiased) Chao1 estimator.

squares

Squares estimator.

The following measures are available for replicated incidence data:

ice

Incidence-based Coverage Estimator.

chao2

(improved/unbiased) Chao2 estimator.

Author(s)

N. Frerebeau

References

Kintigh, K. W. (1989). Sample Size, Significance, and Measures of Diversity. In Leonard, R. D. and Jones, G. T., Quantifying Diversity in Archaeology. New Directions in Archaeology. Cambridge: Cambridge University Press, p. 25-36.

Magurran, A. E. (1988). Ecological Diversity and its Measurement. Princeton, NJ: Princeton University Press. doi:10.1007/978-94-015-7358-0.

Magurran, A E. & Brian J. McGill (2011). Biological Diversity: Frontiers in Measurement and Assessment. Oxford: Oxford University Press.

McIntosh, R. P. (1967). An Index of Diversity and the Relation of Certain Concepts to Diversity. Ecology, 48(3), 392-404. doi:10.2307/1932674.

Peet, R. K. (1974). The Measurement of Species Diversity. Annual Review of Ecology and Systematics, 5(1), 285-307. doi:10.1146/annurev.es.05.110174.001441.

See Also

index_margalef(), index_menhinick(), index_ace(), index_chao1(), index_squares(), index_ice(), index_chao2()

plot()

Other diversity measures: diversity(), evenness(), heterogeneity(), occurrence(), plot.DiversityIndex(), plot.RarefactionIndex(), profiles(), rarefaction(), she(), similarity(), simulate(), turnover()

Examples

## Data from Magurran 1988, p. 128-129
trap <- matrix(data = c(9, 3, 0, 4, 2, 1, 1, 0, 1, 0, 1, 1,
                        1, 0, 1, 0, 0, 0, 1, 2, 0, 5, 3, 0),
               nrow = 2, byrow = TRUE, dimnames = list(c("A", "B"), NULL))

## Margalef and Menhinick index
richness(trap, method = "margalef") # 2.55 1.88
richness(trap, method = "menhinick") # 1.95 1.66

## Data from Chao & Chiu 2016
brazil <- matrix(
  data = rep(x = c(1:21, 23, 25, 27, 28, 30, 32, 34:37, 41,
                   45, 46, 49, 52, 89, 110, 123, 140),
             times = c(113, 50, 39, 29, 15, 11, 13, 5, 6, 6, 3, 4,
                       3, 5, 2, 5, 2, 2, 2, 2, 1, 2, 1, 1, 1, 1, 1,
                       0, 0, 2, 1, 1, 1, 1, 1, 0, 1, 1, 0, 0)),
  nrow = 1, byrow = TRUE
)

## Chao1-type estimators (asymptotic species richness)
composition(brazil, method = c("chao1"), unbiased = FALSE) # 461.625
composition(brazil, method = c("ace"), k = 10) # 445.822

Seriograph

Description

Usage

seriograph(object, ...)

eppm(object, ...)

## S4 method for signature 'matrix'
eppm(object)

## S4 method for signature 'data.frame'
eppm(object)

## S4 method for signature 'matrix'
seriograph(
  object,
  weights = FALSE,
  fill = "darkgrey",
  border = NA,
  axes = TRUE,
  ...
)

## S4 method for signature 'data.frame'
seriograph(
  object,
  weights = FALSE,
  fill = "darkgrey",
  border = NA,
  axes = TRUE,
  ...
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table).

...

Currently not used.

weights

A logical scalar: should the row sums be displayed?

fill

The color for filling the bars.

border

The color to draw the borders.

axes

A logical scalar: should axes be drawn on the plot? It will omit labels where they would abut or overlap previously drawn labels.

Details

The positive difference from the column mean percentage (in french "écart positif au pourcentage moyen", EPPM) represents a deviation from the situation of statistical independence. As independence can be interpreted as the absence of relationships between types and the chronological order of the assemblages, EPPM is a useful tool to explore significance of relationship between rows and columns related to seriation (Desachy 2004).

seriograph() superimposes the frequencies (grey) and EPPM values (black) for each row-column pair in a Ford diagram.

Value

Author(s)

N. Frerebeau

References

Desachy, B. (2004). Le sériographe EPPM: un outil informatisé de sériation graphique pour tableaux de comptages. Revue archéologique de Picardie, 3(1), 39-56. doi:10.3406/pica.2004.2396.

See Also

plot_ford()

Other plot methods: matrigraph(), plot_bertin(), plot_diceleraas(), plot_ford(), plot_heatmap(), plot_rank(), plot_spot()

Examples

## Data from Desachy 2004
data("compiegne", package = "folio")

## Seriograph
seriograph(compiegne)
seriograph(compiegne, weights = TRUE)

## Compute EPPM
counts_eppm <- eppm(compiegne)
plot_heatmap(counts_eppm, col = khroma::color("YlOrBr")(12))

SHE Analysis

Description

SHE Analysis

Usage

she(object, ...)

## S4 method for signature 'matrix'
she(
  object,
  unbiased = FALSE,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  legend = list(x = "right"),
  ...
)

## S4 method for signature 'data.frame'
she(
  object,
  unbiased = FALSE,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  legend = list(x = "right"),
  ...
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Further graphical parameters to be passed to graphics::lines() and graphics::points().

unbiased

A logical scalar: should the bias-corrected estimator be used (see index_shannon())?

xlab, ylab

A character vector giving the x and y axis labels.

main

A character string giving a main title for the plot.

sub

A character string giving a subtitle for the plot.

ann

A logical scalar: should the default annotation (title and x, y and z axis labels) appear on the plot?

axes

A logical scalar: should axes be drawn on the plot?

frame.plot

A logical scalar: should a box be drawn around the plot?

panel.first

An an expression to be evaluated after the plot axes are set up but before any plotting takes place. This can be useful for drawing background grids.

panel.last

An expression to be evaluated after plotting has taken place but before the axes, title and box are added.

legend

A list of additional arguments to be passed to graphics::legend(); names of the list are used as argument names. If NULL, no legend is displayed.

Details

If samples are taken along a gradient or stratigraphic section, breaks in the curve may be used to infer discontinuities.

This assumes that the order of the matrix rows (from 1 to n) follows the progression along the gradient/transect.

Value

she() is called for its side-effects: it results in a graphic being displayed (invisibly returns object).

Author(s)

N. Frerebeau

References

Buzas, M. A. & Hayek, L.-A. C. (1998). SHE analysis for biofacies identification. Journal of Foraminiferal Research, 1998, 28(3), 233-239.

Hayek, L.-A. C. & Buzas, M. A. (2010). Surveying Natural Populations: Quantitative Tools for Assessing Biodiversity. Second edition. New York: Columbia University Press.

See Also

Other diversity measures: diversity(), evenness(), heterogeneity(), occurrence(), plot.DiversityIndex(), plot.RarefactionIndex(), profiles(), rarefaction(), richness(), similarity(), simulate(), turnover()

Examples

## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## SHE analysis
she(cantabria)

Similarity

Description

Similarity

Usage

similarity(object, ...)

## S4 method for signature 'matrix'
similarity(
  object,
  method = c("brainerd", "bray", "jaccard", "morisita", "sorensen")
)

## S4 method for signature 'data.frame'
similarity(
  object,
  method = c("brainerd", "bray", "jaccard", "morisita", "sorensen")
)

Arguments

object

A m \times p numeric matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Currently not used.

method

A character string specifying the method to be used (see details). Any unambiguous substring can be given.

Details

\beta-diversity can be measured by addressing similarity between pairs of samples/cases.

bray, jaccard, morisita and sorensen indices provide a scale of similarity from 0-1 where 1 is perfect similarity and 0 is no similarity. brainerd is scaled between 0 and 200.

brainerd

Brainerd-Robinson quantitative index.

bray

Bray-Curtis similarity (a.k.a. Dice-Sorensen quantitative index).

jaccard

Jaccard qualitative index.

morisita

Morisita-Horn quantitative index.

sorensen

Dice-Sorensen qualitative index.

For jaccard and sorensen, data are standardized on a presence/absence scale (0/1) beforehand.

Value

A stats::dist object.

Author(s)

N. Frerebeau

References

Magurran, A. E. (1988). Ecological Diversity and its Measurement. Princeton, NJ: Princeton University Press. doi:10.1007/978-94-015-7358-0.

See Also

index_binomial(), index_brainerd(), index_bray(), index_jaccard(), index_morisita(), index_sorensen()

Other diversity measures: diversity(), evenness(), heterogeneity(), occurrence(), plot.DiversityIndex(), plot.RarefactionIndex(), profiles(), rarefaction(), richness(), she(), simulate(), turnover()

Examples

## Data from Huntley 2004, 2008
data("pueblo")

## Brainerd-Robinson measure
(C <- similarity(pueblo, "brainerd"))
plot_spot(C)

## Data from Magurran 1988, p. 166
data("aves")

## Jaccard measure (presence/absence data)
similarity(aves, "jaccard") # 0.46

# Bray and Curtis modified version of the Sorensen index (count data)
(sim <- similarity(aves, "bray")) # 0.44

# Bray and Curtis dissimilarity
1 - sim

Measure Diversity by Comparing to Simulated Assemblages

Description

Measure Diversity by Comparing to Simulated Assemblages

Usage

## S4 method for signature 'DiversityIndex'
simulate(
  object,
  nsim = 1000,
  seed = NULL,
  step = 1,
  level = 0.8,
  interval = "percentiles",
  progress = getOption("tabula.progress"),
  ...
)

Arguments

object

A DiversityIndex object.

nsim

A non-negative integer specifying the number of simulations.

seed

An object specifying if and how the random number generator should be initialized (see stats::simulate()).

step

An integer giving the increment of the sample size.

level

A length-one numeric vector giving the confidence level.

interval

A character string giving the type of confidence interval to be returned. Currently, only "percentiles" is supported (sample quantiles, as described in Kintigh 1984)..

progress

A logical scalar: should a progress bar be displayed?

...

Currently not used.

Value

Returns a DiversityIndex object.

Author(s)

N. Frerebeau

References

Baxter, M. J. (2001). Methodological Issues in the Study of Assemblage Diversity. American Antiquity, 66(4), 715-725. doi:10.2307/2694184.

Kintigh, K. W. (1984). Measuring Archaeological Diversity by Comparison with Simulated Assemblages. American Antiquity, 49(1), 44-54. doi:10.2307/280511.

See Also

bootstrap(), jackknife()

Other diversity measures: diversity(), evenness(), heterogeneity(), occurrence(), plot.DiversityIndex(), plot.RarefactionIndex(), profiles(), rarefaction(), richness(), she(), similarity(), turnover()

Examples


## Data from Conkey 1980, Kintigh 1989
data("cantabria")

## Assemblage diversity size comparison
## Warning: this may take a few seconds!
h <- heterogeneity(cantabria, method = "shannon")
h_sim <- simulate(h)
plot(h_sim)

r <- richness(cantabria, method = "observed")
r_sim <- simulate(r)
plot(r_sim)

Deprecated Functions in tabula

Description

These functions still work but will be removed (defunct) in the next version.

Usage

index_sorenson(x, y, ...)

## S4 method for signature 'logical,logical'
index_sorenson(x, y)

## S4 method for signature 'numeric,numeric'
index_sorenson(x, y)

resample(object, ...)

## S4 method for signature 'numeric'
resample(object, do, n, size = sum(object), ..., f = NULL)

Diversity Test

Description

Compares Shannon/Simpson diversity between samples.

Usage

test_shannon(x, y, ...)

test_simpson(x, y, ...)

## S4 method for signature 'numeric,numeric'
test_shannon(x, y, ...)

## S4 method for signature 'matrix,missing'
test_shannon(x, adjust = "holm", ...)

## S4 method for signature 'data.frame,missing'
test_shannon(x, adjust = "holm", ...)

## S4 method for signature 'numeric,numeric'
test_simpson(x, y, adjust = "holm", ...)

## S4 method for signature 'matrix,missing'
test_simpson(x, adjust = "holm", ...)

## S4 method for signature 'data.frame,missing'
test_simpson(x, adjust = "holm", ...)

Arguments

x, y

A numeric vector, a m \times p matrix or data.frame of count data (absolute frequencies giving the number of individuals for each category, i.e. a contingency table). A data.frame will be coerced to a numeric matrix via data.matrix().

...

Further arguments to be passed to internal methods.

adjust

A character string specifying the method for adjusting p values (see stats::p.adjust()).

Value

If x and y are numeric vectors, returns a list containing the following components:

statistic

The value of the t-statistic.

parameter

The degrees of freedom for the t-statistic.

p.value

The p-value for the test.

If x is a matrix or a data.frame, returns a table of adjusted p-values in lower triangular form.

Functions

Author(s)

N. Frerebeau

References

Magurran, A. E. (1988). Ecological Diversity and its Measurement. Princeton, NJ: Princeton University Press. doi:10.1007/978-94-015-7358-0.

Examples

## Data from Magurran 1988, p. 145-149
oakwood <- c(35, 26, 25, 21, 16, 11, 6, 5, 3, 3,
             3, 3, 3, 2, 2, 2, 1, 1, 1, 1, 0, 0)
spruce <- c(30, 30, 3, 65, 20, 11, 0, 4, 2, 14,
            0, 3, 9, 0, 0, 5, 0, 0, 0, 0, 1, 1)

test_shannon(oakwood, spruce)
test_simpson(oakwood, spruce)

## Data from Conkey 1980, Kintigh 1989
data("cantabria")

test_shannon(cantabria)
test_simpson(cantabria)

Turnover

Description

Returns the degree of turnover in taxa composition along a gradient or transect.

Usage

turnover(object, ...)

## S4 method for signature 'matrix'
turnover(
  object,
  ...,
  method = c("whittaker", "cody", "routledge1", "routledge2", "routledge3", "wilson")
)

## S4 method for signature 'data.frame'
turnover(
  object,
  ...,
  method = c("whittaker", "cody", "routledge1", "routledge2", "routledge3", "wilson")
)

Arguments

object

A m \times p numeric matrix or data.frame of count data or incidence data. A data.frame will be coerced to a numeric matrix via data.matrix().

...

Further arguments to be passed to internal methods.

method

A character string specifying the method to be used (see details). Any unambiguous substring can be given.

Details

The following methods can be used to ascertain the degree of turnover in taxa composition along a gradient (\beta-diversity) on qualitative (presence/absence) data:

cody

Cody measure.

routledge1

Routledge first measure.

routledge2

Routledge second measure.

routledge3

Routledge third measure (exponential form of the second measure).

whittaker

Whittaker measure.

wilson

Wilson measure.

This assumes that the order of the matrix rows (from 1 to n) follows the progression along the gradient/transect.

Data are standardized on a presence/absence scale (0/1) beforehand.

Value

A numeric vector.

Author(s)

N. Frerebeau

See Also

index_cody(), index_routledge1(), index_routledge2(), index_routledge3(), index_whittaker(), index_wilson()

Other diversity measures: diversity(), evenness(), heterogeneity(), occurrence(), plot.DiversityIndex(), plot.RarefactionIndex(), profiles(), rarefaction(), richness(), she(), similarity(), simulate()

Examples

## Data from Magurran 1988, p. 162
data("woodland")

## Whittaker's measure
turnover(woodland, "whittaker") # 1

## Cody's measure
turnover(woodland, "cody") # 3

## Routledge's measures
turnover(woodland, "routledge1") # 0.29
turnover(woodland, "routledge2") # 0.56
turnover(woodland, "routledge3") # 1.75

## Wilson and Shmida's measure
turnover(woodland, "wilson") # 1

Trees Incidences

Description

A dataset of presence or absence of trees in six (10 x 10 m) quadarts along a transect through a deciduous woodland.

Usage

woodland

Format

A data.frame with 6 rows (quadarts) and 6 variables (tree species).

Source

Magurran, A. E. (1988). Ecological Diversity and its Measurement. Princeton, NJ: Princeton University Press. doi:10.1007/978-94-015-7358-0.

See Also

Other datasets: aves, cantabria, pueblo

mirror server hosted at Truenetwork, Russian Federation.