GitHub

Dissimilarity Indices

Pairwise indices compare two assemblages. Some are naturally similarities, some are dissimilarities or distances, and some are information divergences. DiversityAndDissimilarity.jl exposes the convention explicitly through similarity, dissimilarity, and distance.

julia> using DiversityAndDissimilarity

julia> left = Dict(:oak => 12, :ash => 5);

julia> right = Dict(:ash => 4, :elm => 7);

julia> similarity(Jaccard(), left, right)
0.3333333333333333

julia> dissimilarity(BrayCurtis(), left, right)
0.7142857142857143

Available Methods

FamilyTypes and helpersMain optionsTypical use
IncidenceJaccard, SorensenDice, OverlapfrequenciesPresence/absence overlap and turnover.
AbundanceBrayCurtis, Ruzicka, Canberra, MorisitaHornfrequenciesEcological abundance comparisons with aligned taxa.
Probability distancesTotalVariation, Manhattan, Euclidean, Hellinger, Chord, BhattacharyyafrequenciesComparisons of normalized composition.
Information divergencesKullbackLeibler, ShannonDifference, JensenDifference, JensenShannonbase, estimator, support, distanceDirectional KL, entropy differences, and Jensen-Shannon divergence/distance.
Matrix helperslabeled_distance, labeled_dissimilarity, labeled_similaritylabels, label, speciesPairwise matrices with sample labels.

Choosing A Measure

  • Use Jaccard for simple presence/absence turnover.
  • Use SorensenDice when shared presences should receive more weight than in Jaccard.
  • Use Overlap when asking whether a smaller assemblage is nested in a larger one.
  • Use BrayCurtis as a robust default for ecological abundance data.
  • Use Ruzicka when you want an abundance analogue of Jaccard.
  • Use Hellinger or Chord before Euclidean-style workflows on transformed relative abundances.
  • Use TotalVariation for a bounded probability-composition difference with direct mass interpretation.
  • Use JensenShannon for a symmetric information-theoretic metric.
  • Use KullbackLeibler only when the direction left || right is scientifically meaningful.

Incidence Examples

Incidence comparisons use species presence or absence:

\[J(A,B) = \frac{|A \cap B|}{|A \cup B|}, \qquad S(A,B) = \frac{2|A \cap B|}{|A| + |B|}.\]

julia> a = [1, 1, 0, 1];

julia> b = [1, 0, 1, 1];

julia> similarity(Jaccard(), a, b)
0.5

julia> dissimilarity(Jaccard(), a, b)
0.5

julia> similarity(SorensenDice(), a, b)
0.6666666666666666

Abundance Examples

Abundance comparisons use aligned abundance vectors. For dictionaries, taxa are aligned by key. For numeric vectors, positions are corresponding taxa.

\[BC(x,y) = \frac{\sum_i |x_i-y_i|}{\sum_i (x_i+y_i)}.\]

julia> x = [1, 2, 3];

julia> y = [2, 2, 0];

julia> bray_curtis_dissimilarity(x, y)
0.4

julia> ruzicka_similarity(x, y)
0.42857142857142855

julia> canberra_distance(x, y)
0.4444444444444444

MorisitaHorn is an abundance-overlap similarity dominated by shared common taxa:

morisita_horn_similarity(x, y)
morisita_horn_distance(x, y)

Probability And Information Examples

Probability comparisons normalize aligned abundances to p and q.

\[TV(p,q) = \frac{1}{2}\sum_i |p_i-q_i|.\]

\[D_{KL}(p \Vert q) = \sum_i p_i \log_b\frac{p_i}{q_i}.\]

\[JS(p,q) = \frac{1}{2}D_{KL}(p \Vert m) + \frac{1}{2}D_{KL}(q \Vert m), \qquad m = \frac{p+q}{2}.\]

julia> total_variation_distance([1, 0, 0], [0, 1, 0])
1.0

julia> hellinger_distance([1, 0, 0], [0, 1, 0])
1.0

julia> jensen_shannon_distance([1, 0], [0, 1])
1.0

julia> dissimilarity(KullbackLeibler(), [1, 0], [0, 1])
Inf

KullbackLeibler is asymmetric, so pairwise matrices are not forced to be symmetric. JensenShannon returns the square-root distance by default; use JensenShannon(; distance=false) or JensenDifference for the raw divergence.

Low-Sample Divergence Corrections

KL, Jensen difference, and Jensen-Shannon divergence/distance accept the same estimator objects used for Shannon entropy:

kullback_leibler_divergence(left, right; estimator=MillerMadow())
kullback_leibler_divergence(left, right; estimator=AddGamma(1))    # Laplace
kullback_leibler_divergence(left, right; estimator=AddGamma(0.5))  # Jeffreys
kullback_leibler_divergence(left, right; estimator=HausserStrimmer())
kullback_leibler_divergence(left, right; estimator=ChaoShen())

jensen_shannon_divergence(left, right; estimator=AddGamma(0.5), support=10)
jensen_shannon_distance(left, right; estimator=ChaoShen())

Use support when the finite category universe is known. AddGamma(1) is Laplace smoothing; AddGamma(0.5) is Jeffreys smoothing. ChaoShen() applies sample-coverage logic for unseen mass.

Community Matrices

Passing a community matrix (rows = samples, columns = taxa) computes all pairwise comparisons across rows and returns a square matrix. See Data Input Formats for orientation rules, table inputs, and keyword parameters.

julia> community = [
           1 1 2 0 5
           3 0 1 1 0
       ];

julia> distance(BrayCurtis(), community)
2×2 Matrix{Float64}:
 0.0       0.714286
 0.714286  0.0

julia> labeled_distance(BrayCurtis(), community; labels=["plot-a", "plot-b"]).labels
2-element Vector{String}:
 "plot-a"
 "plot-b"

For Tables.jl-compatible inputs, use species to select taxa columns and label to carry sample identifiers.

Availability Checklist

Legend: [x] is available directly; [~] is available indirectly or with a different convention; [ ] is not documented as available in the checked source. Last checked: 2026-05-15.

Index or featureDiversityAndDissimilarity.jlDiversity.jlveganiNEXTscikit-bioEcoPyMicrobiome.jlSciPySpadeRentropart / hill packagesNotes
Jaccard incidence similarity/distance[x][ ][x][ ][~][x][x][x][x][ ]Jaccard() / jaccard_index; vegan vegdist(method="jaccard"); SciPy boolean jaccard.
Sorensen-Dice incidence similarity/distance[x][ ][~][ ][~][x][ ][x][x][ ]SorensenDice(); SciPy boolean dice; related vegan forms exist through binary transformations.
Overlap / Szymkiewicz-Simpson[x][ ][~][ ][~][ ][ ][ ][ ][ ]Overlap() / overlap_similarity; nestedness-sensitive incidence overlap.
Simple matching / Sokal-Michener[ ][ ][ ][ ][~][x][ ][x][ ][ ]Requires meaningful shared absences and a fixed species universe.
Russell-Rao[ ][ ][ ][ ][~][ ][ ][x][ ][ ]Shared-absence-sensitive boolean coefficient.
Kulczynski / Mountford / Raup-Crick incidence[ ][ ][x][ ][~][ ][ ][ ][~][ ]Available in vegan or specialist packages; conventions vary.
Chao-Jaccard / Chao-Sorensen[ ][ ][x][ ][ ][ ][ ][ ][x][~]Adjusts overlap for unseen shared species.
Bray-Curtis dissimilarity[x][ ][x][ ][~][x][x][x][~][ ]BrayCurtis(); vegan vegdist(method="bray"); SciPy braycurtis.
Quantitative Sorensen / Bray-Curtis similarity[~][ ][~][ ][~][x][~][~][~][ ]Derivable as 1 - bray_curtis_distance; naming conventions vary.
Ruzicka / quantitative Jaccard[x][ ][~][ ][~][ ][ ][ ][ ][ ]Ruzicka() / ruzicka_similarity; abundance version of Jaccard.
Percentage similarity / Renkonen[ ][ ][~][ ][ ][ ][ ][ ][~][ ]Probability overlap sum(min(p,q)); complement is total variation.
Total variation distance[x][ ][~][ ][~][ ][ ][~][ ][ ]TotalVariation() / total_variation_distance; equals Bray-Curtis for normalized probabilities.
Manhattan / L1 distance[x][ ][x][ ][~][x][ ][x][ ][ ]Manhattan(); for probabilities equals 2 * total variation.
Euclidean / L2 distance[x][ ][x][ ][~][x][ ][x][ ][ ]General distance frequently used on transformed data.
Chord distance[x][ ][x][ ][ ][ ][ ][ ][ ][ ]Chord() / chord_distance.
Hellinger distance[x][ ][x][ ][~][~][x][ ][ ][ ]Hellinger() / hellinger_distance; vegan and Microbiome.jl document related workflows.
Bhattacharyya coefficient / distance[x][ ][~][ ][~][ ][ ][~][ ][ ]Bhattacharyya(); probability-overlap family related to Hellinger.
Morisita / Morisita-Horn[x][ ][x][ ][ ][ ][ ][ ][~][~]MorisitaHorn() / morisita_horn_similarity; vegan morisita and horn.
Canberra distance[x][ ][x][ ][~][x][ ][x][ ][ ]Canberra() / canberra_distance; denominator convention varies.
Clark / Cao / binomial / Gower / chi-square[ ][ ][x][ ][~][~][ ][ ][ ][ ]Ecological dissimilarities available elsewhere; not core here.
Kullback-Leibler divergence[x][ ][ ][ ][~][ ][ ][~][ ][x]KullbackLeibler(); asymmetric with low-sample correction options.
Jeffreys divergence[ ][ ][ ][ ][~][ ][ ][ ][ ][~]Symmetrized KL; not currently implemented.
Shannon entropy difference[x][ ][ ][ ][~][ ][ ][ ][ ][~]ShannonDifference() compares entropy values, not shared taxa.
Jensen / Jensen-Shannon divergence / distance[x][ ][ ][ ][~][ ][ ][x][ ][~]JensenDifference() and JensenShannon(); square root of JS divergence is a metric.
Aitchison / robust Aitchison[ ][ ][ ][ ][~][ ][~][ ][ ][~]Compositional-data distance after CLR-style transforms; requires zero handling.
Wasserstein / earth mover's[ ][ ][ ][ ][~][ ][ ][x][ ][ ]Requires a ground distance among taxa/features.
UniFrac and phylogenetic pairwise distances[ ][x][ ][ ][x][ ][~][ ][ ][~]Out of scope here; Diversity.jl and scikit-bio are stronger phylogenetic options.
Multiple-site beta diversity[ ][x][x][~][~][x][ ][ ][~][x]Multi-community rather than pairwise-only comparison.

Reference

DiversityAndDissimilarity.Chord — Type

Chord distance between square-root transformed probability vectors.

\[d_c(p,q) = \sqrt{\sum_i (\sqrt{p_i} - \sqrt{q_i})^2}\]

DiversityAndDissimilarity.KullbackLeibler — Type

Kullback-Leibler divergence between probability vectors.

dissimilarity(KullbackLeibler(), left, right) returns $D_{KL}(p \Vert q)$:

\[D_{KL}(p \Vert q) = \sum_i p_i \log_b \frac{p_i}{q_i}\]

This divergence is asymmetric: dissimilarity(KullbackLeibler(), a, b) and dissimilarity(KullbackLeibler(), b, a) are generally different, and a full community distance matrix will not be symmetric. See is_symmetric.

Use estimator for low-sample corrections. Supported options mirror Shannon entropy estimation: MillerMadow, AddGamma for pseudocounts (AddGamma(1) is Laplace and AddGamma(0.5) is Jeffreys), HausserStrimmer for shrinkage, and ChaoShen for a Good-Turing unseen-mass correction. Without smoothing or unseen-mass correction this divergence returns Inf when p_i > 0 and q_i == 0 for any coordinate.

The MillerMadow correction subtracts the standard entropy bias correction $(S-1)/(2n \log b)$ from the plugin divergence estimate, where $S$ is the number of observed positive-probability categories in left and $n$ is its total count. This is a first-order correction for the bias in $H(p)$; the cross-entropy term $H(p,q)$ is left uncorrected.

DiversityAndDissimilarity.ShannonDifference — Type

Absolute Shannon entropy difference between probability vectors.

\[|H_b(p) - H_b(q)|\]

Does not measure distributional divergence

This index compares the scalar entropy magnitudes of two assemblages; it does not measure how different the distributions themselves are. Two assemblages with completely disjoint species but identical species-abundance profiles will score zero. Use JensenShannon or KullbackLeibler when you want a proper distributional divergence.

DiversityAndDissimilarity.JensenDifference — Type

Jensen difference of Shannon entropy between probability vectors.

\[J_H(p,q) = H_b\left(\frac{p+q}{2}\right) - \frac{H_b(p)+H_b(q)}{2}\]

For Shannon entropy this equals the Jensen-Shannon divergence. It returns the raw divergence value. Use JensenShannon when you want the metric square-root form (i.e. dissimilarity(JensenShannon(), ...) with distance=true). Use estimator for the same low-sample corrections available to KullbackLeibler.

DiversityAndDissimilarity.JensenShannon — Type

Jensen-Shannon divergence or distance between probability vectors.

JensenShannon(; base=2, distance=true) returns the square root of the Jensen-Shannon divergence, which is a proper metric. Set distance=false for the divergence itself (identical to JensenDifference). Use estimator for low-sample corrections such as MillerMadow(), AddGamma(1) for Laplace smoothing, AddGamma(0.5) for Jeffreys smoothing, HausserStrimmer() shrinkage, and ChaoShen() / Good-Turing unseen-mass correction.

See also JensenDifference, which returns the raw divergence value without taking a square root.

DiversityAndDissimilarity.MorisitaHorn — Type

Morisita-Horn abundance similarity.

\[MH(x,y) = \frac{2\sum_i x_i y_i}{(\lambda_x + \lambda_y) N_x N_y}, \qquad \lambda_x = \frac{\sum_i x_i^2}{N_x^2}\]

DiversityAndDissimilarity.similarity — Function
similarity(index, left, right; frequencies=true)

Compare two assemblages using an incidence or abundance similarity index.

similarity(index, data; frequencies=true, species=nothing)

Return a pairwise similarity matrix across rows of a community matrix or Tables.jl-compatible table.

DiversityAndDissimilarity.dissimilarity — Function
dissimilarity(index, left, right; frequencies=true)

Compare two assemblages using a dissimilarity or distance form of an index.

dissimilarity(index, data; frequencies=true, species=nothing)

Return a pairwise dissimilarity matrix across rows of a community matrix or Tables.jl-compatible table.

DiversityAndDissimilarity.distance — Function
distance(index, left, right; frequencies=true)

Alias for dissimilarity.

distance(index, data; frequencies=true, species=nothing)

Return a pairwise distance/dissimilarity matrix across rows of a community matrix or Tables.jl-compatible table.

DiversityAndDissimilarity.labeled_distance — Function
labeled_distance(index, data; labels=nothing, label=nothing, frequencies=true, species=nothing)

Return pairwise distances with sample labels as a named tuple (labels=..., matrix=...).

Pass labels explicitly for matrices. For Tables.jl-compatible inputs, pass label as the column name containing sample/site identifiers.

DiversityAndDissimilarity.kullback_leibler_divergence — Function
kullback_leibler_divergence(left, right; frequencies=true, base=2, estimator=Plugin(), support=nothing)

Return Kullback-Leibler divergence $D_{KL}(left \Vert right)$ between normalized abundance/probability vectors. This divergence is asymmetric and returns Inf when right has zero probability where left has positive probability.

DiversityAndDissimilarity.shannon_difference — Function
shannon_difference(left, right; frequencies=true, base=2, estimator=Plugin(), support=nothing)

Return the absolute difference between Shannon entropies of two assemblages.

DiversityAndDissimilarity.jensen_difference — Function
jensen_difference(left, right; frequencies=true, base=2, estimator=Plugin(), support=nothing)

Return the Jensen difference of Shannon entropy. This equals Jensen-Shannon divergence for Shannon entropy.

DiversityAndDissimilarity.jensen_shannon_similarity — Function
jensen_shannon_similarity(left, right; frequencies=true, base=2, distance=true, estimator=Plugin(), support=nothing)

Return one minus normalized Jensen-Shannon dissimilarity. By default the normalization uses the square-root Jensen-Shannon distance; pass distance=false to normalize the divergence instead.