API Reference

Abstract supertype for diversity, similarity, and dissimilarity indices.

Abstract supertype for single-assemblage diversity, entropy, and richness indices.

Abstract supertype for pairwise similarity, dissimilarity, and distance indices.

counts(x)

Return a Dict mapping each category to its count or validated abundance.

When x is a vector, each element is treated as an observation and the result maps each unique value to the number of times it appears, with type Dict{eltype(x), Int64}. When x is a Dict, it is treated as a category => abundance mapping: abundances are validated to be non-negative and finite, and returned as Float64 values without changing the key type.

julia> using DiversityAndDissimilarity

julia> sort(collect(counts(["oak", "ash", "oak"])), by=first)
2-element Vector{Pair{String, Int64}}:
 "ash" => 1
 "oak" => 2

julia> sort(collect(counts(Dict(:oak => 3, :ash => 1))), by=first)
2-element Vector{Pair{Symbol, Float64}}:
 :ash => 1.0
 :oak => 3.0

community_matrix(data; species=nothing)

Return a numeric community matrix with samples/sites in rows and species/taxa in columns.

Matrices are returned as Float64 copies. All abundances must be non-negative and finite, and each row must have positive total abundance; otherwise an ArgumentError is thrown.

Tables.jl-compatible inputs, including DataFrames, are converted column-wise. By default, numeric columns are used as species columns. Pass species as a collection of column names to choose species columns explicitly, which is recommended when a table also contains numeric site identifiers or metadata.

julia> using DiversityAndDissimilarity

julia> community_matrix([1 2 3; 4 5 6])
2×3 Matrix{Float64}:
 1.0  2.0  3.0
 4.0  5.0  6.0

proportions(x; frequencies=true)

Return relative abundances for x as a probability vector or matrix.

Numeric vectors are interpreted as abundance/frequency vectors by default; zero entries are discarded and the returned vector contains only the positive-abundance proportions. Pass frequencies=false to treat a numeric vector as raw observations instead. Non-numeric vectors are always treated as observations.

Community matrices (samples in rows, taxa in columns) are normalized row-wise: the returned matrix has the same shape as the input, each row sums to one, and zero entries are preserved.

julia> using DiversityAndDissimilarity

julia> proportions([3, 1])
2-element Vector{Float64}:
 0.75
 0.25

julia> proportions([3 1; 2 2])
2×2 Matrix{Float64}:
 0.75  0.25
 0.5   0.5

Validated(data)

A thin wrapper asserting that data has already been validated as a community matrix. Pass a Validated value to diversity and dissimilarity functions to skip per-call input validation.

Obtain a Validated wrapper from raw data using validate, which runs all the usual checks and returns a type-stable Float64 copy. Constructing Validated(data) directly bypasses all checks entirely.

validate(data; species=nothing)

Validate data and return a Validated wrapper.

Checks that all abundances are non-negative and finite and that each row has positive total abundance. Matrices are returned as Float64 copies. The returned Validated object can be passed to diversity and dissimilarity functions to skip per-call validation overhead, which is useful when the same matrix is consumed by many functions in a pipeline.

The safe default pathway validates on every call:

richness(community)        # validates, then computes
shannon_entropy(community) # validates independently

With validate, validation runs once and the result is reused:

v = validate(community)    # validates once
richness(v)                # computation only
shannon_entropy(v)         # computation only
bray_curtis_distance(v)    # computation only

julia> using DiversityAndDissimilarity

julia> v = validate([1 1 0; 0 1 1]);

julia> richness(v)
2-element Vector{Int64}:
 2
 2

julia> dissimilarity(BrayCurtis(), v)
2×2 Matrix{Float64}:
 0.0  0.5
 0.5  0.0

alpha_diversity(data; frequencies=true, species=nothing, base=2, estimator=Plugin(),
                support=nothing, threshold=10)

Return a compact alpha-diversity summary for common exploratory workflows.

For one assemblage, the result is a named tuple containing observed richness, Shannon entropy, Shannon effective diversity, Simpson concentration, Gini-Simpson diversity, inverse Simpson diversity, Chao1, ACE, and sample coverage. For community matrices and Tables.jl-compatible inputs, the result is one named tuple per row/sample.