Diversity.Ecology

In the Diversity.Ecology submodule, we replicate old ecological diversity measures and generalised versions of them that relate to our general measures of alpha, beta and gamma diversity at subcommunity and ecosystem measures. The generalisations of the richness, Shannon and Simpson are the only standard measures we are aware of whose subcommunity components sum directly to the corresponding ecosystem measure (although note that Simpson's index decreases for increased diversity, so small components are more diverse).

Usage

Accessing the functionality in the package is simple. Note that the submodule provides the ecological measures themselves, while Metacommunity and the DiversityLevels come from Diversity, so both are loaded here:

julia> using Diversity
julia> using Diversity.Ecology
julia> community = [10, 20, 20]3-element Vector{Int64}:
 10
 20
 20
julia> community = community ./ sum(community)3-element Vector{Float64}:
 0.2
 0.4
 0.4
julia> simpson(community)1×7 DataFrame
 Row │ div_type  measure  type_level  type_name  partition_level  partition_na ⋯
     │ String    String   String      String     String           String       ⋯
─────┼──────────────────────────────────────────────────────────────────────────
   1 │ Unique    Simpson  types                  subcommunity     1            ⋯
                                                               2 columns omitted
julia> shannon(community)1×7 DataFrame
 Row │ div_type  measure  type_level  type_name  partition_level  partition_na ⋯
     │ String    String   String      String     String           String       ⋯
─────┼──────────────────────────────────────────────────────────────────────────
   1 │ Unique    Shannon  types                  subcommunity     1            ⋯
                                                               2 columns omitted
julia> richness(community)1×8 DataFrame
 Row │ div_type  measure   q      type_level  type_name  partition_level  part ⋯
     │ String    String    Int64  String      String     String           Stri ⋯
─────┼──────────────────────────────────────────────────────────────────────────
   1 │ Unique    Richness      0  types                  subcommunity     1    ⋯
                                                               2 columns omitted

Two subcommunities can be compared with the Jaccard index, either directly or — since it is a special case of our general measures — through a Metacommunity, with or without a similarity matrix:

julia> using LinearAlgebra
julia> ecosystem = [2 2 0; 0 2 2]'3×2 adjoint(::Matrix{Int64}) with eltype Int64:
 2  0
 2  2
 0  2
julia> ecosystem = ecosystem ./ sum(ecosystem)3×2 Matrix{Float64}:
 0.25  0.0
 0.25  0.25
 0.0   0.25
julia> jaccard(ecosystem)1×7 DataFrame
 Row │ div_type  measure  type_level  type_name  partition_level  partition_na ⋯
     │ String    String   String      String     String           String       ⋯
─────┼──────────────────────────────────────────────────────────────────────────
   1 │ Unique    Jaccard  types                  metacommunity                 ⋯
                                                               2 columns omitted
julia> generalisedjaccard(Metacommunity(ecosystem))1×7 DataFrame
 Row │ div_type  measure  type_level  type_name  partition_level  partition_na ⋯
     │ String    String   String      String     String           String       ⋯
─────┼──────────────────────────────────────────────────────────────────────────
   1 │ Unique    Jaccard  types                  metacommunity                 ⋯
                                                               2 columns omitted
julia> generalisedjaccard(ecosystem, Matrix(1.0I, 3, 3))1×7 DataFrame
 Row │ div_type     measure  type_level  type_name  partition_level  partition ⋯
     │ String       String   String      String     String           String    ⋯
─────┼──────────────────────────────────────────────────────────────────────────
   1 │ Arbitrary Z  Jaccard  types                  metacommunity              ⋯
                                                               2 columns omitted

Pielou's evenness measures how equally the individuals are spread across the types, from zero to one:

julia> pielou([0.7, 0.2, 0.1])1×7 DataFrame
 Row │ div_type  measure  type_level  type_name  partition_level  partition_na ⋯
     │ String    String   String      String     String           String       ⋯
─────┼──────────────────────────────────────────────────────────────────────────
   1 │ Unique    Pielou   types                  subcommunity     1            ⋯
                                                               2 columns omitted
julia> communitymat = [10 20 30 20 0;   # 5 subcommunities (columns), 6 species (rows)
                       10  0 50 80 10;
                       60 10 90  0  0;
                       10 10 10 10 10;
                       70 70 70 70 70;
                       10  0  0 90  0]6×5 Matrix{Int64}:
 10  20  30  20   0
 10   0  50  80  10
 60  10  90   0   0
 10  10  10  10  10
 70  70  70  70  70
 10   0   0  90   0
julia> Diversity.Ecology.generalisedpielou(subcommunityDiversity, communitymat)5×7 DataFrame
 Row │ div_type  measure  type_level  type_name  partition_level  partition_na ⋯
     │ String    String   String      String     String           String       ⋯
─────┼──────────────────────────────────────────────────────────────────────────
   1 │ Unique    Pielou   types                  subcommunity     1            ⋯
   2 │ Unique    Pielou   types                  subcommunity     2
   3 │ Unique    Pielou   types                  subcommunity     3
   4 │ Unique    Pielou   types                  subcommunity     4
   5 │ Unique    Pielou   types                  subcommunity     5            ⋯
                                                               2 columns omitted
julia> Diversity.Ecology.generalisedpielou(metacommunityDiversity, communitymat)1×7 DataFrame
 Row │ div_type  measure  type_level  type_name  partition_level  partition_na ⋯
     │ String    String   String      String     String           String       ⋯
─────┼──────────────────────────────────────────────────────────────────────────
   1 │ Unique    Pielou   types                  metacommunity                 ⋯
                                                               2 columns omitted

Note

generalisedpielou is not exported, so it must be qualified as above (or imported explicitly with using Diversity.Ecology: generalisedpielou). Every other measure on this page is exported by the submodule.

Faith's PD

faith_pd and generalisedfaith_pd are the exception on this page, in two ways. The measures above are the classical ones for wholly distinct types, and refuse to run when similarity is present; Faith's phylogenetic diversity is the opposite — it is meaningless without a tree, so it is defined only for a metacommunity built over the PhyloBranches that the Phylo extension supplies, and therefore appears only once Phylo is loaded. See Phylogenetic diversity.

It is also the one measure here that ignores abundances entirely: PD is the total length of the branches spanned by the types that are present, so it answers "how much evolutionary history is here?" rather than "how is it distributed?".

Diversity.Ecology — Module

Diversity.Ecology submodule

The Diversity.Ecology module replicates old ecological diversity measures and generalised versions of them that relate to our general measures of alpha, beta and gamma diversity at subcommunity and metacommunity levels. The generalisations of the richness, Shannon and Simpson are the only standard measures we are aware of whose subcommunity components sum directly to the corresponding ecosystem measure (although note that Simpson's index decreases for increased diversity, so small components are more diverse).

source

Diversity.Ecology.faith_pd — Function

faith_pd(mc::AbstractMetacommunity)

Calculates Faith's phylogenetic diversity (PD) of each subcommunity of mc in isolation — the total length of the branches of the tree spanned by the types present in it. See generalisedfaith_pd for the metacommunity as a whole, for why there is no q argument, and for why this needs a PhyloBranches specifically.

Arguments:

mc: a metacommunity built over a PhyloBranches

Returns:

PDs of the subcommunities

source

Diversity.Ecology.generalisedfaith_pd — Function

generalisedfaith_pd(level::DiversityLevel, mc::AbstractMetacommunity)

Calculates Faith's phylogenetic diversity (PD) — the total length of the branches of the tree spanned by the types present — at the level requested.

Unlike the other measures here, this one needs a tree, and is defined only for a metacommunity built over the PhyloBranches supplied by the Phylo extension — not for phylogenetic types in general, since the calculation relies on how that type in particular maps leaf abundances onto branches. It is therefore available only once Phylo is loaded.

It also takes no q: Faith's PD is the q = 0 case by definition, so there is no profile to ask for, and PD depends on which types are present and not at all on their abundances.

Arguments:

level: the diversity level to calculate at — subcommunityDiversity for the PD of each subcommunity in isolation, metacommunityDiversity for the PD of the whole tree spanned by the metacommunity
mc: a metacommunity built over a PhyloBranches

Returns:

PD of the metacommunity, or PDs of the subcommunities

source

Diversity.Ecology.generalisedjaccard — Function

generalisedjaccard(proportions::AbstractArray, qs, Z::AbstractMatrix)
generalisedjaccard(proportions::AbstractArray, qs, sim::AbstractTypes)
generalisedjaccard(meta::AbstractAssemblage, qs)

Calculates a generalisation of the Jaccard similarity of two columns representing the counts of two subcommunities. This evaluates to raw alpha / gamma - 1 for a series of orders, repesented as a vector of qs (or a single number). It also includes an optional similarity matrix for the species. This gives a measure of the distinctness of the subcommunities, though we believe that beta and normalised beta have better properties.

Arguments:

proportions: population proportions
meta: metacommunity / assemblage
Z: similarity matrix or
sim: instance of AbstractTypes

Returns:

Jaccard-related distinctivess measures

source

Diversity.Ecology.generalisedrichness — Function

generalisedrichness(level::DiversityLevel, proportions::AbstractArray,
                    Z::AbstractMatrix)
generalisedrichness(level::DiversityLevel, proportions::AbstractArray,
                    sim::AbstractTypes)

Calculates species richness (diversity at q = 0) of a series of columns representing subcommunity counts, allowing a similarity matrix for the types / species.

Arguments:

level: DiversityLevel to calculate at (e.g. subcommunityDiversity)
proportions: population proportions
Z: similarity matrix or
sim: instance of AbstractTypes

Returns:

diversity (at ecosystem level) or diversities (of subcommunities)

source

Diversity.Ecology.generalisedshannon — Function

generalisedshannon(level::DiversityLevel, proportions::AbstractArray,
                   Z::AbstractMatrix)
generalisedshannon(level::DiversityLevel, proportions::AbstractArray,
                   sim::AbstractTypes)

Calculates Shannon entropy (log of diversity at q = 1) of a series of columns representing independent subcommunity counts, allowing a similarity matrix for the types / species.

Arguments:

level: DiversityLevel to calculate at (e.g. subcommunityDiversity)
proportions: population proportions
Z: similarity matrix or
sim: instance of AbstractTypes

Returns:

entropy (at metacommunity level) or entropies (of subcommunities)

source

Diversity.Ecology.generalisedsimpson — Function

generalisedsimpson(level::DiversityLevel, proportions::AbstractArray,
                   Z::AbstractMatrix)
generalisedsimpson(level::DiversityLevel, proportions::AbstractArray,
                   sim::AbstractTypes)

Calculates Simpson's index (1 / diversity at q = 2) of a series of columns representing independent subcommunity counts, allowing a similarity matrix for the types / species.

Arguments:

level: DiversityLevel to calculate at (e.g. subcommunityDiversity)
proportions: population proportions
Z: similarity matrix or
sim: instance of AbstractTypes

Returns:

concentration (at ecosystem level) or concentrations (of subcommunities)

source

Diversity.Ecology.gower — Function

gower(proportions::AbstractMatrix; countzeros::Bool = false, logscale::Bool = true)
gower(asm::AbstractAssemblage; countzeros::Bool = false, logscale::Bool = true)

Calculates Gower's dissimilarity between exactly two subcommunities. Unlike the other measures here this is a genuinely pairwise index, so it needs a metacommunity of two subcommunities and no more.

Arguments:

proportions: population proportions; or
asm: an AbstractAssemblage of exactly two subcommunities

Keyword arguments:

countzeros: which of the two published conventions to use, and not a free choice — it selects the denominator. true divides by the total number of types, so types absent from both subcommunities still count; this is classic Gower (1971), and matches R vegan's gower. false divides only by the types actually present, matching vegan's altGower. Defaults to false.
logscale: take log10 of the abundances first, so that differences are proportional rather than absolute. Defaults to false.
normalise: count each type as differing or not, rather than by how much it differs — a presence/absence reading. Defaults to whatever countzeros is.

Returns:

Gower dissimilarity of the two subcommunities, as a single-row DataFrame

Note: R vegan 2.7 changed its gower to range-standardise columns first and drop tied columns from the denominator, which returns NA for identical samples. This package keeps the classic reading, so gower(countzeros = true) matches old vegan; see test/run_rcall.jl.

source

Diversity.Ecology.jaccard — Method

jaccard(proportions::AbstractMatrix)
jaccard(asm::AbstractAssemblage)

Calculates Jaccard similarity coefficient of two columns representing independent subcommunity counts

Arguments:

proportions: population proportions
asm: assemblage / metacommunity

Returns:

the Jaccard index

source

Diversity.Ecology.pielou — Method

pielou(proportions::AbstractMatrix)
pielou(asm::AbstractAssemblage)

Calculates Pielou's evenness of a series of columns representing independent subcommunity counts.

Arguments:

proportions: population proportions

Returns:

evenness of subcommunities

Example:

communitymat = [10 20 30 20 0;
                10 0 50 80 10;
                60 10 90 0 0; 
                10 10 10 10 10;
                70 70 70 70 70;
                10 0 0 90 0];

pielou(communitymat)

source

Diversity.Ecology.richness — Method

richness(proportions::AbstractMatrix)

Calculates species richness (diversity at q = 0) of a series of columns representing independent subcommunity counts.

Arguments:

proportions: population proportions

Returns:

diversities of subcommunities

source

Diversity.Ecology.shannon — Method

shannon(proportions::AbstractVecOrMat)

Calculates shannon entropy (log of diversity at q = 1) of a series of columns representing independent subcommunity counts.

Arguments:

proportions: population proportions

Returns:

entropies of subcommunities

source

Diversity.Ecology.simpson — Method

simpson(proportions::AbstractMatrix)

Calculates Simpson's index (1 / diversity at q = 2) of a series of columns representing independent subcommunity counts.

Arguments:

proportions: population proportions

Returns:

concentrations of subcommunities

source