Skip to contents

Squared Chord distance

Source: R/beta_div.r
squared_chord.Rd

The squared version of the Chord distance.

Usage

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

Arguments

counts

A numeric matrix of count data (samples \(\times\) features). Typically contains absolute abundances (integer counts), though proportions are also accepted.

margin

The margin containing samples. 1 if samples are rows, 2 if samples are columns. Ignored when counts is a special object class (e.g. phyloseq). Default: 1

pairs

Which combinations of samples should distances be calculated for? The default value (NULL) calculates all-vs-all. Provide a numeric or logical vector specifying positions in the distance matrix to calculate. See examples.

cpus

How many parallel processing threads should be used. The default, n_cpus(), will use all logical CPU cores.

Details

The Squared Chord distance is defined as: $$\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)
sum((sqrt(x) - sqrt(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.

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(), euclidean(), gower(), hellinger(), horn(), jensen(), jsd(), lorentzian(), manhattan(), matusita(), minkowski(), morisita(), motyka(), psym_chisq(), soergel(), squared_chisq(), squared_euclidean(), topsoe(), wave_hedges()

Examples

    squared_chord(ex_counts)
#>          Saliva      Gums      Nose
#> Gums  0.2368872                    
#> Nose  1.6731536 1.6210892          
#> Stool 1.7347018 1.7617761 1.8002844