Package 'ecodive'

Description

A non-parametric estimator of species richness that separates features into abundant and rare groups.

Usage

ace(counts, cutoff = 10L, margin = 1L, cpus = n_cpus())

Arguments

Details

The ACE metric separates features into "abundant" and "rare" groups based on a cutoff (usually 10 counts). It assumes that the presence of abundant species is certain, while the true number of rare species must be estimated.

Equations:

$C_{ace} = 1 - \frac{F_1}{X_{rare}}$

$\gamma_{ace}^2 = \max\left[\frac{F_{rare} \sum_{i=1}^{r}i(i-1)F_i}{C_{ace}X_{rare}(X_{rare} - 1)} - 1, 0\right]$

$D_{ace} = F_{abund} + \frac{F_{rare}}{C_{ace}} + \frac{F_1}{C_{ace}}\gamma_{ace}^2$

Where:

• $r$ : Rare cutoff (default 10). Features with $\le r$ counts are considered rare.

• $F_i$ : Number of features with exactly $i$ counts.

• $F_1$ : Number of features where $X_i = 1$ (singletons).

• $F_{rare}$ : Number of rare features where $X_i \le r$.

• $F_{abund}$ : Number of abundant features where $X_i > r$.

• $X_{rare}$ : Total counts belonging to rare features.

• $C_{ace}$ : The sample abundance coverage estimator.

• $\gamma_{ace}^2$ : The estimated coefficient of variation.

Parameter: cutoff The integer threshold distinguishing rare from abundant species. Standard practice is to use 10.

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

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

alpha_div(), vignette('adiv')

Other Richness metrics: chao1(), margalef(), menhinick(), observed(), squares()

Examples

ace(ex_counts)

Description

Calculates the Euclidean distance between centered log-ratio (CLR) transformed abundances.

Usage

aitchison(
  counts,
  margin = 1L,
  pseudocount = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

The Aitchison distance is defined as:

$\sqrt{\sum_{i=1}^{n} [(\ln{X_i} - X_L) - (\ln{Y_i} - Y_L)]^2}$

Where:

• $X_i$, $Y_i$ : Absolute counts for the $i$-th feature.

• $X_L$, $Y_L$ : Mean log of abundances. $X_L = \frac{1}{n}\sum_{i=1}^{n} \ln{X_i}$.

• $n$ : The number of features.

Base R Equivalent:

x <- log((x + pseudocount) / exp(mean(log(x + pseudocount))))
y <- log((y + pseudocount) / exp(mean(log(y + pseudocount))))
sqrt(sum((x-y)^2)) # Euclidean distance

Pseudocount

Zeros are undefined in the Aitchison (CLR) transformation. If pseudocount is NULL (the default) and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Aitchison, J. (1986). The statistical analysis of compositional data. Chapman and Hall. doi:10.1002/bimj.4710300705

Aitchison, J. (1982). The statistical analysis of compositional data. Journal of the Royal Statistical Society: Series B (Methodological), 44(2), 139-160. doi:10.1111/j.2517-6161.1982.tb01195.x

Costea, P. I., Zeller, G., Sunagawa, S., & Bork, P. (2014). A fair comparison. Nature Methods, 11(4), 359. doi:10.1038/nmeth.2897

Gloor, G. B., Macklaim, J. M., Pawlowsky-Glahn, V., & Egozcue, J. J. (2017). Microbiome datasets are compositional: and this is not optional. Frontiers in Microbiology, 8, 2224. doi:10.3389/fmicb.2017.02224

Kaul, A., Mandal, S., Davidov, O., & Peddada, S. D. (2017). Analysis of microbiome data in the presence of excess zeros. Frontiers in Microbiology, 8, 2114. doi:10.3389/fmicb.2017.02114

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: bhattacharyya(), bray(), canberra(), chebyshev(), chord(), clark(), divergence(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

aitchison(ex_counts, pseudocount = 1)

Description

Alpha Diversity Wrapper Function

Usage

alpha_div(
  counts,
  metric,
  norm = "percent",
  cutoff = 10L,
  digits = 3L,
  tree = NULL,
  margin = 1L,
  cpus = n_cpus()
)

Arguments

Details

Integer Count Requirements

A frequent and critical error in alpha diversity analysis is providing the wrong type of data to a metric's formula. Some indices are mathematically defined based on counts of individuals and require raw, integer abundance data. Others are based on proportional abundances and can accept either integer counts (which are then converted to proportions) or pre-normalized proportional data. Using proportional data with a metric that requires integer counts will return an error message.

Requires Integer Counts Only

• Chao1

• ACE

• Squares Richness Estimator

• Margalef's Index

• Menhinick's Index

• Fisher's Alpha

• Brillouin Index

Can Use Proportional Data

• Observed Features

• Shannon Index

• Gini-Simpson Index

• Inverse Simpson Index

• Berger-Parker Index

• McIntosh Index

• Faith's PD

Value

A numeric vector.

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Examples

# Example counts matrix
    ex_counts
    
    # Shannon diversity values
    alpha_div(ex_counts, 'Shannon')
    
    # Chao1 diversity values
    alpha_div(ex_counts, 'c')
    
    # Faith PD values
    alpha_div(ex_counts, 'faith', tree = ex_tree)

Description

A measure of the numerical importance of the most abundant species.

Usage

berger(counts, margin = 1L, cpus = n_cpus())

Arguments

Details

The Berger-Parker index is defined as the proportional abundance of the most dominant feature:

$\max(P_i)$

Where:

• $P_i$ : Proportional abundance of the $i$-th feature.

Base R Equivalent:

x <- ex_counts[1,]
p <- x / sum(x)
max(p)

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

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

alpha_div(), vignette('adiv')

Other Dominance metrics: mcintosh()

Examples

berger(ex_counts)

Description

Beta Diversity Wrapper Function

Usage

beta_div(
  counts,
  metric,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  power = 1.5,
  alpha = 0.5,
  tree = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

List of Beta Diversity Metrics

Flexible name matching

Case insensitive and partial matching. Any runs of non-alpha characters are converted to underscores. E.g. ⁠metric = 'Weighted UniFrac⁠ selects weighted_unifrac.

UniFrac names can be shortened to the first letter plus "unifrac". E.g. uunifrac, w_unifrac, or ⁠V UniFrac⁠. These also support partial matching.

Finished code should always use the full primary option name to avoid ambiguity with future additions to the metrics list.

Value

A numeric vector.

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Pseudocount

The pseudocount parameter is only relevant when norm = 'clr'.

Zeros are undefined in the centered log-ratio (CLR) transformation. If norm = 'clr', pseudocount is NULL (the default), and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

See aitchison for references.

Examples

# Example counts matrix
    ex_counts
    
    # Bray-Curtis distances
    beta_div(ex_counts, 'bray')
    
    # Generalized UniFrac distances
    beta_div(ex_counts, 'GUniFrac', tree = ex_tree)

Description

Measures the similarity of two probability distributions.

Usage

bhattacharyya(counts, margin = 1L, pairs = NULL, cpus = n_cpus())

Arguments

Details

The Bhattacharyya distance is defined as:

$-\ln{\sum_{i=1}^{n}\sqrt{P_{i}Q_{i}}}$

Where:

• $P_i$, $Q_i$ : Proportional abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]; p <- x / sum(x)
y <- ex_counts[2,]; q <- y / sum(y)
-log(sum(sqrt(p * q)))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Bhattacharyya, A. (1943). On a measure of divergence between two statistical populations defined by their probability distributions. Bulletin of the Calcutta Mathematical Society, 35, 99-109.

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bray(), canberra(), chebyshev(), chord(), clark(), divergence(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

bhattacharyya(ex_counts)

Description

A standard ecological metric quantifying the dissimilarity between communities.

Usage

bray(
  counts,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

The Bray-Curtis dissimilarity is defined as:

$\frac{\sum_{i=1}^{n} |X_i - Y_i|}{\sum_{i=1}^{n} (X_i + Y_i)}$

Where:

• $X_i$, $Y_i$ : Absolute abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
sum(abs(x-y)) / sum(x+y)

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Pseudocount

The pseudocount parameter is only relevant when norm = 'clr'.

Zeros are undefined in the centered log-ratio (CLR) transformation. If norm = 'clr', pseudocount is NULL (the default), and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

See aitchison for references.

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

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), canberra(), chebyshev(), chord(), clark(), divergence(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

bray(ex_counts)

Description

A diversity index derived from information theory, appropriate for fully censused communities.

Usage

brillouin(counts, margin = 1L, cpus = n_cpus())

Arguments

Details

The Brillouin index is defined as:

$\frac{\ln{[(\sum_{i = 1}^{n} X_i)!]} - \sum_{i = 1}^{n} \ln{(X_i!)}}{\sum_{i = 1}^{n} X_i}$

Where:

• $n$ : The number of features.

• $X_i$ : Integer count of the $i$-th feature.

Base R Equivalent:

x <- ex_counts[1,]
# note: lgamma(x + 1) == log(x!)
(lgamma(sum(x) + 1) - sum(lgamma(x + 1))) / sum(x)

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

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

See Also

alpha_div(), vignette('adiv')

Other Diversity metrics: fisher(), inv_simpson(), shannon(), simpson()

Examples

brillouin(ex_counts)

Description

A weighted version of the Manhattan distance, sensitive to differences when both values are small.

Usage

canberra(
  counts,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

The Canberra distance is defined as:

$\sum_{i=1}^{n} \frac{|X_i - Y_i|}{X_i + Y_i}$

Where:

• $X_i$, $Y_i$ : Absolute abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
sum(abs(x-y) / (x+y))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Pseudocount

The pseudocount parameter is only relevant when norm = 'clr'.

Zeros are undefined in the centered log-ratio (CLR) transformation. If norm = 'clr', pseudocount is NULL (the default), and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

See aitchison for references.

References

Lance, G. N., & Williams, W. T. (1966). Computer programs for hierarchical polythetic classification ("similarity analyses"). The Computer Journal, 9(1), 60-64. doi:10.1093/comjnl/9.1.60

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), chebyshev(), chord(), clark(), divergence(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

canberra(ex_counts)

Description

A non-parametric estimator of the lower bound of species richness.

Usage

chao1(counts, margin = 1L, cpus = n_cpus())

Arguments

Details

The Chao1 estimator uses the ratio of singletons to doubletons to estimate the number of missing species:

$n + \frac{(F_1)^2}{2 F_2}$

Where:

• $n$ : The number of observed features.

• $F_1$ : Number of features observed once (singletons).

• $F_2$ : Number of features observed twice (doubletons).

Base R Equivalent:

x <- ex_counts[1,]
sum(x>0) + (sum(x == 1) ** 2) / (2 * sum(x == 2))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Chao, A. (1984). Nonparametric estimation of the number of classes in a population. Scandinavian Journal of Statistics, 11, 265-270.

See Also

alpha_div(), vignette('adiv')

Other Richness metrics: ace(), margalef(), menhinick(), observed(), squares()

Examples

chao1(ex_counts)

Description

The maximum difference between any single feature across two samples.

Usage

chebyshev(
  counts,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

The Chebyshev distance is defined as:

$\max(|X_i - Y_i|)$

Where:

• $X_i$, $Y_i$ : Absolute abundances of the $i$-th feature.

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
max(abs(x-y))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Pseudocount

The pseudocount parameter is only relevant when norm = 'clr'.

Zeros are undefined in the centered log-ratio (CLR) transformation. If norm = 'clr', pseudocount is NULL (the default), and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

See aitchison for references.

References

Cantrell, C. D. (2000). Modern mathematical methods for physicists and engineers. Cambridge University Press.

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chord(), clark(), divergence(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

chebyshev(ex_counts)

Description

Euclidean distance between normalized vectors.

Usage

chord(counts, margin = 1L, pairs = NULL, cpus = n_cpus())

Arguments

Details

The Chord distance is defined as:

$\sqrt{\sum_{i=1}^{n} \left(\frac{X_i}{\sqrt{\sum_{j=1}^{n} X_j^2}} - \frac{Y_i}{\sqrt{\sum_{j=1}^{n} Y_j^2}}\right)^2}$

Where:

• $X_i$, $Y_i$ : Absolute counts of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
sqrt(sum(((x / sqrt(sum(x ^ 2))) - (y / sqrt(sum(y ^ 2))))^2))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Orlóci, L. (1967). An agglomerative method for classification of plant communities. Journal of Ecology, 55(1), 193-206. doi:10.2307/2257725

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), clark(), divergence(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

chord(ex_counts)

Description

Also known as the coefficient of divergence.

Usage

clark(
  counts,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

Clark's divergence distance is defined as:

$\sqrt{\sum_{i=1}^{n}\left(\frac{X_i - Y_i}{X_i + Y_i}\right)^{2}}$

Where:

• $X_i$, $Y_i$ : Absolute abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
sqrt(sum((abs(x - y) / (x + y)) ^ 2))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Pseudocount

The pseudocount parameter is only relevant when norm = 'clr'.

Zeros are undefined in the centered log-ratio (CLR) transformation. If norm = 'clr', pseudocount is NULL (the default), and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

See aitchison for references.

References

Clark, P. J. (1952). An extension of the coefficient of divergence for use with multiple characters. Copeia, 1952(2), 61-64. doi:10.2307/1438598

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), chord(), divergence(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

clark(ex_counts)

Description

A probabilistic divergence metric.

Usage

divergence(
  counts,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

Divergence is defined as:

$2\sum_{i=1}^{n} \frac{(P_i - Q_i)^2}{(P_i + Q_i)^2}$

Where:

• $P_i$, $Q_i$ : Proportional abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]; p <- x / sum(x)
y <- ex_counts[2,]; q <- y / sum(y)
2 * sum((p - q)^2 / (p + q)^2)

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Pseudocount

The pseudocount parameter is only relevant when norm = 'clr'.

Zeros are undefined in the centered log-ratio (CLR) transformation. If norm = 'clr', pseudocount is NULL (the default), and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

See aitchison for references.

References

Cha, S.-H. (2007). Comprehensive survey on distance/similarity measures between probability density functions. International Journal of Mathematical Models and Methods in Applied Sciences, 1(4), 300–307.

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), chord(), clark(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

divergence(ex_counts)

Description

The straight-line distance between two points in multidimensional space.

Usage

euclidean(
  counts,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

The Euclidean distance is defined as:

$\sqrt{\sum_{i=1}^{n} (X_i - Y_i)^2}$

Where:

• $X_i$, $Y_i$ : Absolute abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
sqrt(sum((x-y)^2))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Pseudocount

The pseudocount parameter is only relevant when norm = 'clr'.

Zeros are undefined in the centered log-ratio (CLR) transformation. If norm = 'clr', pseudocount is NULL (the default), and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

See aitchison for references.

References

Legendre, P., & Legendre, L. (2012). Numerical ecology. Elsevier.

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), chord(), clark(), divergence(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

euclidean(ex_counts)

Description

Genera found on four human body sites.

Usage

ex_counts

Format

A matrix of 4 samples (columns) x 6 genera (rows).

Source

Derived from The Human Microbiome Project dataset.

Description

Companion tree for ex_counts.

Usage

ex_tree

Format

A phylo object.

Details

ex_tree encodes this tree structure:

      +----------44---------- Haemophilus
  +-2-|
  |   +----------------68---------------- Bacteroides  
  |                      
  |             +---18---- Streptococcus
  |      +--12--|       
  |      |      +--11-- Staphylococcus
  +--11--|              
         |      +-----24----- Corynebacterium
         +--12--|
                +--13-- Propionibacterium

Description

Calculates the sum of the branch lengths for all species present in a sample.

Usage

faith(counts, tree = NULL, margin = 1L, cpus = n_cpus())

Arguments

Details

Faith's PD is defined as:

$\sum_{i = 1}^{n} L_i A_i$

Where:

• $n$ : The number of branches in the phylogenetic tree.

• $L_i$ : The length of the $i$-th branch.

• $A_i$ : A binary value (1 if any descendants of branch $i$ are present in the sample, 0 otherwise).

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Faith, D. P. (1992). Conservation evaluation and phylogenetic diversity. Biological Conservation, 61(1), 1-10. doi:10.1016/0006-3207(92)91201-3

See Also

alpha_div(), vignette('adiv')

Other Phylogenetic metrics: generalized_unifrac(), normalized_unifrac(), unweighted_unifrac(), variance_adjusted_unifrac(), weighted_unifrac()

Examples

faith(ex_counts, tree = ex_tree)

Description

A parametric diversity index assuming species abundances follow a log-series distribution.

Usage

fisher(counts, digits = 3L, margin = 1L, cpus = n_cpus())

Arguments

Details

Fisher's Alpha ($\alpha$) is the parameter in the equation:

$\frac{n}{\alpha} = \ln{\left(1 + \frac{X_T}{\alpha}\right)}$

Where:

• $n$ : The number of features.

• $X_T$ : Total of all counts (sequencing depth).

The value of $\alpha$ is solved for iteratively.

Parameter: digits

The precision (number of decimal places) to use when solving the equation.

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Fisher, R. A., Corbet, A. S., & Williams, C. B. (1943). The relation between the number of species and the number of individuals in a random sample of an animal population. Journal of Animal Ecology, 12, 42-58. doi:10.2307/1411

See Also

alpha_div(), vignette('adiv')

Other Diversity metrics: brillouin(), inv_simpson(), shannon(), simpson()

Examples

fisher(ex_counts)

Description

A unified UniFrac distance that balances the weight of abundant and rare lineages.

Usage

generalized_unifrac(
  counts,
  tree = NULL,
  alpha = 0.5,
  margin = 1L,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

The Generalized UniFrac distance is defined as:

$\frac{\sum_{i=1}^{n} L_i(P_i + Q_i)^{\alpha}\left|\frac{P_i - Q_i}{P_i + Q_i}\right|}{\sum_{i=1}^{n} L_i(P_i + Q_i)^{\alpha}}$

Where:

• $n$ : The number of branches in the tree.

• $L_i$ : The length of the $i$-th branch.

• $P_i$, $Q_i$ : The proportion of the community descending from branch $i$ in sample P and Q.

• $\alpha$ : A scalable weighting factor.

Parameter: alpha

The alpha parameter controls the weight given to abundant lineages. $\alpha = 1$ corresponds to Weighted UniFrac, while $\alpha = 0$ corresponds to Unweighted UniFrac.

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Chen, J., Bittinger, K., Charlson, E. S., Hoffmann, C., Lewis, J., Wu, G. D., ... & Li, H. (2012). Associating microbiome composition with environmental covariates using generalized UniFrac distances. Bioinformatics, 28(16), 2106-2113. doi:10.1093/bioinformatics/bts342

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Phylogenetic metrics: faith(), normalized_unifrac(), unweighted_unifrac(), variance_adjusted_unifrac(), weighted_unifrac()

Examples

generalized_unifrac(ex_counts, tree = ex_tree, alpha = 0.5)

Description

A distance metric that normalizes differences by the range of the feature.

Usage

gower(
  counts,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

The Gower distance is defined as:

$\frac{1}{n}\sum_{i=1}^{n}\frac{|X_i - Y_i|}{R_i}$

Where:

• $X_i$, $Y_i$ : Absolute abundances of the $i$-th feature.

• $R_i$ : The range of the $i$-th feature across all samples (max - min).

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
r <- abs(x - y)
n <- length(x)
sum(abs(x-y) / r) / n

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Pseudocount

The pseudocount parameter is only relevant when norm = 'clr'.

Zeros are undefined in the centered log-ratio (CLR) transformation. If norm = 'clr', pseudocount is NULL (the default), and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

See aitchison for references.

References

Gower, J. C. (1971). A general coefficient of similarity and some of its properties. Biometrics, 27(4), 857-871. doi:10.2307/2528823

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), chord(), clark(), divergence(), euclidean(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

gower(ex_counts)

Description

Measures the minimum number of substitutions required to change one string into the other.

Usage

hamming(counts, margin = 1L, pairs = NULL, cpus = n_cpus())

Arguments

Details

The Hamming distance is defined as:

$(A + B) - 2J$

Where:

• $A$, $B$ : Number of features in each sample.

• $J$ : Number of features in common (intersection).

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
sum(xor(x, y))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Hamming, R. W. (1950). Error detecting and error correcting codes. Bell System Technical Journal, 29(2), 147-160. doi:10.1002/j.1538-7305.1950.tb00463.x

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Presence/Absence metrics: jaccard(), ochiai(), sorensen()

Examples

hamming(ex_counts)

Description

A distance metric related to the Bhattacharyya distance, often used for community data with many zeros.

Usage

hellinger(counts, margin = 1L, pairs = NULL, cpus = n_cpus())

Arguments

Details

The Hellinger distance is defined as:

$\sqrt{\sum_{i=1}^{n}(\sqrt{P_i} - \sqrt{Q_i})^{2}}$

Where:

• $P_i$, $Q_i$ : Proportional abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]; p <- x / sum(x)
y <- ex_counts[2,]; q <- y / sum(y)
sqrt(sum((sqrt(p) - sqrt(q)) ^ 2))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Rao, C. R. (1995). A review of canonical coordinates and an alternative to correspondence analysis using Hellinger distance. Qüestiió, 19, 23-63.

Hellinger, E. (1909). Neue Begründung der Theorie quadratischer Formen von unendlichvielen Veränderlichen. Journal für die reine und angewandte Mathematik, 136, 210–271. doi:10.1515/crll.1909.136.210

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), chord(), clark(), divergence(), euclidean(), gower(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

hellinger(ex_counts)

Description

A similarity index based on Simpson's diversity index, suitable for abundance data.

Usage

horn(
  counts,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

The Horn-Morisita dissimilarity is defined as:

$1 - \frac{2\sum_{i=1}^{n}P_{i}Q_{i}}{\sum_{i=1}^{n}P_i^2 + \sum_{i=1}^{n}Q_i^2}$

Where:

• $P_i$, $Q_i$ : Proportional abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
z <- sum(x^2) / sum(x)^2 + sum(y^2) / sum(y)^2
1 - ((2 * sum(x * y)) / (z * sum(x) * sum(y)))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Pseudocount

The pseudocount parameter is only relevant when norm = 'clr'.

Zeros are undefined in the centered log-ratio (CLR) transformation. If norm = 'clr', pseudocount is NULL (the default), and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

See aitchison for references.

References

Horn, H. S. (1966). Measurement of "overlap" in comparative ecological studies. The American Naturalist, 100(914), 419-424. doi:10.1086/282436

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), chord(), clark(), divergence(), euclidean(), gower(), hellinger(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

horn(ex_counts)

Description

A transformation of the Simpson index that represents the "effective number of species".

Usage

inv_simpson(counts, margin = 1L, cpus = n_cpus())

Arguments

Details

The Inverse Simpson index is defined as:

$1 / \sum_{i = 1}^{n} P_i^2$

Where:

• $n$ : The number of features.

• $P_i$ : Proportional abundance of the $i$-th feature.

Base R Equivalent:

x <- ex_counts[1,]
p <- x / sum(x)
1 / sum(p ** 2)

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

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

See Also

alpha_div(), vignette('adiv')

Other Diversity metrics: brillouin(), fisher(), shannon(), simpson()

Examples

inv_simpson(ex_counts)

Description

Measures dissimilarity between sample sets.

Usage

jaccard(counts, margin = 1L, pairs = NULL, cpus = n_cpus())

Arguments

Details

The Jaccard distance is defined as:

$1 - \frac{J}{(A + B - J)}$

Where:

• $A$, $B$ : Number of features in each sample.

• $J$ : Number of features in common (intersection).

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
1 - sum(x & y) / sum(x | y)

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Jaccard, P. (1912). The distribution of the flora in the alpine zone. New Phytologist, 11(2), 37-50. doi:10.1111/j.1469-8137.1912.tb05611.x

Jaccard, P. (1908). Nouvelles recherches sur la distribution florale. Bulletin de la Societe Vaudoise des Sciences Naturelles, 44(163), 223-270. doi:10.5169/seals-268384

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Presence/Absence metrics: hamming(), ochiai(), sorensen()

Examples

jaccard(ex_counts)

Description

The square root of the Jensen-Shannon divergence.

Usage

jensen(counts, margin = 1L, pairs = NULL, cpus = n_cpus())

Arguments

Details

The Jensen-Shannon distance is defined as:

$\sqrt{\frac{1}{2}\left[\sum_{i=1}^{n}P_i\ln\left(\frac{2P_i}{P_i + Q_i}\right) + \sum_{i=1}^{n}Q_i\ln\left(\frac{2Q_i}{P_i + Q_i}\right)\right]}$

Where:

• $P_i$, $Q_i$ : Proportional abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]; p <- x / sum(x)
y <- ex_counts[2,]; q <- y / sum(y)
sqrt(sum(p * log(2 * p / (p+q)), q * log(2 * q / (p+q))) / 2)

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Endres, D. M., & Schindelin, J. E. (2003). A new metric for probability distributions. IEEE Transactions on Information Theory, 49(7), 1858-1860. doi:10.1109/TIT.2003.813506

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), chord(), clark(), divergence(), euclidean(), gower(), hellinger(), horn(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

jensen(ex_counts)

Description

A symmetrized and smoothed version of the Kullback-Leibler divergence.

Usage

jsd(counts, margin = 1L, pairs = NULL, cpus = n_cpus())

Arguments

Details

The Jensen-Shannon divergence (JSD) is defined as:

$\frac{1}{2}\left[\sum_{i=1}^{n}P_i\ln\left(\frac{2P_i}{P_i + Q_i}\right) + \sum_{i=1}^{n}Q_i\ln\left(\frac{2Q_i}{P_i + Q_i}\right)\right]$

Where:

• $P_i$, $Q_i$ : Proportional abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]; p <- x / sum(x)
y <- ex_counts[2,]; q <- y / sum(y)
sum(p * log(2 * p / (p+q)), q * log(2 * q / (p+q))) / 2

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Lin, J. (1991). Divergence measures based on the Shannon entropy. IEEE Transactions on Information Theory, 37(1), 145-151. doi:10.1109/18.61115

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), chord(), clark(), divergence(), euclidean(), gower(), hellinger(), horn(), jensen(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

jsd(ex_counts)

Description

Programmatic access to the lists of available metrics, and their associated functions.

Usage

list_metrics(
  div = c(NA, "alpha", "beta"),
  val = c("data.frame", "list", "func", "id", "name", "div", "phylo", "weighted",
    "int_only", "true_metric"),
  nm = c(NA, "id", "name"),
  phylo = NULL,
  weighted = NULL,
  int_only = NULL,
  true_metric = NULL
)

match_metric(
  metric,
  div = NULL,
  phylo = NULL,
  weighted = NULL,
  int_only = NULL,
  true_metric = NULL
)

Arguments

Value

match_metric()

A list with the following elements.

• name : Metric name, e.g. "Faith's Phylogenetic Diversity"

• id : Metric ID - also the name of the function, e.g. "faith"

• div : Either "alpha" or "beta".

• phylo : TRUE if metric requires a phylogenetic tree; FALSE otherwise.

• weighted : TRUE if metric takes relative abundance into account; FALSE if it only uses presence/absence.

• int_only : TRUE if metric requires integer counts; FALSE otherwise.

• true_metric : TRUE if metric is a true metric and satisfies the triangle inequality; FALSE if it is a non-metric dissimilarity; NA for alpha diversity metrics.

• func : The function for this metric, e.g. ecodive::faith

• params : Formal args for func, e.g. c("counts", "norm", "tree", "cpus")

list_metrics()

The returned object's type and values are controlled with the val and nm arguments.

• val = "data.frame" : The data.frame from which the below options are sourced.

• val = "list" : A list of objects as returned by match_metric() (above).

• val = "func" : A list of functions.

• val = "id" : A character vector of metric IDs.

• val = "name" : A character vector of metric names.

• val = "div" : A character vector "alpha" and/or "beta".

• val = "phylo" : A logical vector indicating which metrics require a tree.

• val = "weighted" : A logical vector indicating which metrics take relative abundance into account (as opposed to just presence/absence).

• val = "int_only" : A logical vector indicating which metrics require integer counts.

• val = "true_metric" : A logical vector indicating which metrics are true metrics and satisfy the triangle inequality, which work better for ordinations such as PCoA.

If nm is set, then the names of the vector or list will be the metric ID (nm="id") or name (nm="name"). When val="data.frame", the names will be applied to the rownames() property of the data.table.

Examples

# A data.frame of all available metrics.
    head(list_metrics())
    
    # All alpha diversity function names.
    list_metrics('alpha', val = 'id')
    
    # Try to find a metric named 'otus'.
    m <- match_metric('otus')
    
    # The result is a list that includes the function.
    str(m)

Description

A log-based distance metric that is robust to outliers.

Usage

lorentzian(
  counts,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

The Lorentzian distance is defined as:

$\sum_{i=1}^{n}\ln{(1 + |X_i - Y_i|)}$

Where:

• $X_i$, $Y_i$ : Absolute abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
sum(log(1 + abs(x - y)))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Pseudocount

The pseudocount parameter is only relevant when norm = 'clr'.

Zeros are undefined in the centered log-ratio (CLR) transformation. If norm = 'clr', pseudocount is NULL (the default), and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

See aitchison for references.

References

Cha, S.-H. (2007). Comprehensive survey on distance/similarity measures between probability density functions. International Journal of Mathematical Models and Methods in Applied Sciences, 1(4), 300–307.

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), chord(), clark(), divergence(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

lorentzian(ex_counts)

Description

The sum of absolute differences, also known as the taxicab geometry.

Usage

manhattan(
  counts,
  margin = 1L,
  norm = "none",
  pseudocount = NULL,
  pairs = NULL,
  cpus = n_cpus()
)

Arguments

Details

The Manhattan distance is defined as:

$\sum_{i=1}^{n} |X_i - Y_i|$

Where:

• $X_i$, $Y_i$ : Absolute abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]
y <- ex_counts[2,]
sum(abs(x-y))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

Pseudocount

The pseudocount parameter is only relevant when norm = 'clr'.

Zeros are undefined in the centered log-ratio (CLR) transformation. If norm = 'clr', pseudocount is NULL (the default), and zeros are detected, the function uses half the minimum non-zero value (min(x[x>0]) / 2) and issues a warning.

To suppress the warning, provide an explicit value (e.g., 1).

Why this matters: The choice of pseudocount is not neutral; it acts as a weighting factor that can significantly distort downstream results, especially for sparse datasets. See Gloor et al. (2017) and Kaul et al. (2017) for open-access discussions on the mathematical implications, or Costea et al. (2014) for the impact on community clustering.

See aitchison for references.

References

Krause, E. F. (1987). Taxicab geometry: An adventure in non-Euclidean geometry. Dover Publications.

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), chord(), clark(), divergence(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

manhattan(ex_counts)

Description

A richness metric that normalizes the number of species by the log of the total sample size.

Usage

margalef(counts, margin = 1L, cpus = n_cpus())

Arguments

Details

Margalef's index is defined as:

$\frac{n - 1}{\ln{X_T}}$

Where:

• $n$ : The number of features.

• $X_T$ : Total of all counts (sequencing depth).

Base R Equivalent:

x <- ex_counts[1,]
(sum(x > 0) - 1) / log(sum(x))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Margalef, R. (1958). Information theory in ecology. General Systems, 3, 36-71.

Gamito, S. (2010). Caution is needed when applying Margalef diversity index. Ecological Indicators, 10(2), 550-551. doi:10.1016/j.ecolind.2009.07.006

See Also

alpha_div(), vignette('adiv')

Other Richness metrics: ace(), chao1(), menhinick(), observed(), squares()

Examples

margalef(ex_counts)

Description

A distance measure closely related to the Hellinger distance.

Usage

matusita(counts, margin = 1L, pairs = NULL, cpus = n_cpus())

Arguments

Details

The Matusita distance is defined as:

$\sqrt{\sum_{i=1}^{n}\left(\sqrt{P_i} - \sqrt{Q_i}\right)^2}$

Where:

• $P_i$, $Q_i$ : Proportional abundances of the $i$-th feature.

• $n$ : The number of features.

Base R Equivalent:

x <- ex_counts[1,]; p <- x / sum(x)
y <- ex_counts[2,]; q <- y / sum(y)
sqrt(sum((sqrt(p) - sqrt(q)) ^ 2))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Matusita, K. (1955). Decision rules, based on the distance, for problems of fit, two samples, and estimation. The Annals of Mathematical Statistics, 26(4), 631-640. doi:10.1214/aoms/1177728422

See Also

beta_div(), vignette('bdiv'), vignette('bdiv_guide')

Other Abundance metrics: aitchison(), bhattacharyya(), bray(), canberra(), chebyshev(), chord(), clark(), divergence(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), minkowski(), morisita(), motyka(), psym_chisq(), robust_aitchison(), soergel(), squared_chisq(), squared_chord(), squared_euclidean(), topsoe(), wave_hedges()

Examples

matusita(ex_counts)

Description

A dominance index based on the Euclidean distance from the origin.

Usage

mcintosh(counts, margin = 1L, cpus = n_cpus())

Arguments

Details

The McIntosh index is defined as:

$\frac{X_T - \sqrt{\sum_{i = 1}^{n} (X_i)^2}}{X_T - \sqrt{X_T}}$

Where:

• $n$ : The number of features.

• $X_i$ : Integer count of the $i$-th feature.

• $X_T$ : Total of all counts.

Base R Equivalent:

x <- ex_counts[1,]
(sum(x) - sqrt(sum(x^2))) / (sum(x) - sqrt(sum(x)))

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

• phyloseq

• rbiom

• SummarizedExperiment

• TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

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

alpha_div(), vignette('adiv')

Other Dominance metrics: berger()

Examples

mcintosh(ex_counts)

Description

A richness metric that normalizes the number of species by the square root of the total sample size.

Usage

menhinick(counts, margin = 1L, cpus = n_cpus())