Diversity

Documentation	Build Status	DOI

Diversity is a Julia package that provides functionality for measuring alpha, beta and gamma diversity of metacommunities (e.g. ecosystems) and their constituent subcommunities. It implements the framework described in the arXiv paper arXiv:1404.6520 (q-bio.QM), How to partition diversity, which generalises Hill numbers and the similarity-sensitive measures of Leinster and Cobbold so that the diversity of a community can be partitioned among its subcommunities. Similarity between individuals may be of any kind - taxonomic, phylogenetic, genetic, functional or phenotypic - and the package provides a series of older ecological diversity measures through sub-modules as well.

The framework page of the documentation explains what each measure means and where it comes from; it is the place to start if the names below are unfamiliar.

The package is cross-validated against our R package boydorr/rdiversity, which is developed independently, so please raise an issue if you find any problems. We use a DataFrame as the common output format for all of the diversity calculations to provide consistency with rdiversity.

The package is registered in the General registry on v1.x and so can be installed with add. For example on Julia v1.10:

(@v1.13) pkg> add Diversity
    Resolving package versions...
    Updating `~/.julia/environments/v1.13/Project.toml`
  [d3d5718d] + Diversity v0.6.5
    Updating `~/.julia/environments/v1.13/Manifest.toml`
  [d3d5718d] + Diversity v0.6.5
  
(@v1.13) pkg>

The package is confirmed to build and work against Julia v1.10 (the current LTS) and the current release, on Linux, macOS and Windows. It is also tested against nightly.

Contributions are very welcome, as are feature requests and suggestions. Please open an issue if you encounter any problems or would just like to ask a question.

The main package provides numbers-equivalent diversity measures (Hill numbers), similarity-sensitive diversity measures generalising them (from Leinster and Cobbold, 2012), and the alpha, beta and gamma measures that partition those across the subcommunities of a metacommunity. See the framework for what each measure means.

The diversity functions exist both with unicode names (e.g. ᾱ()), which are not automatically exported as we feel they are too short, and with matching ascii names (e.g. NormalisedAlpha()), which are. We also provide a general function to extract any diversity measure for a series of subcommunity relative abundances.

Before calculating diversity a Metacommunity object must be created. This object contains all the information needed to calculate diversity.

# Load the package into Julia
using Diversity

# Example population
pop = [1 1 0; 2 0 0; 3 1 4]
pop = pop / sum(pop)

# Create Metacommunity object
meta = Metacommunity(pop)

First we need to calculate the low-level diversity component seperately, by passing a metacommunity object to the appropriate function; RawAlpha(), NormalisedAlpha(), RawBeta(), NormalisedBeta(), RawRho(), NormalisedRho(), or Gamma().

# First, calculate the normalised alpha component
component = NormalisedAlpha(meta)

Afterwhich, subdiv() or metadiv() are used to calculate subcommunity or metacommunity diversity, respectively (since both subcommunity and metacommunity diversity measures are transformations of the same low-level components, this is computationally more efficient).

# Then, calculate species richness of the subcommunities
subdiv(component, 0)

# or the average (alpha) species richness across the whole population
metadiv(component, 0)

# We can also generate a diversity profile by calculating multiple q-values simultaneously
df = subdiv(component, 0:30)

In some instances, it may be useful to calculate all subcommunity (or metacommunity) measures. In which case, a Metacommunity object may be passed directly to subdiv() or metadiv():

# To calculate all subcommunity diversity measures
subdiv(meta, 0:2)

# To calculate all metacommunity diversity measures
metadiv(meta, 0:2)

Alternatively, if computational efficiency is not an issue, a single measure of diversity may be calculated directly by calling a wrapper function:

norm_sub_alpha(meta, 0:2)

A complete list of these functions is shown below:

• raw_sub_alpha() : per-subcommunity estimate of naive-community metacommunity diversity
• norm_sub_alpha() : similarity-sensitive diversity of each subcommunity in isolation
• raw_sub_rho() : redundancy of individual subcommunities
• norm_sub_rho() : representativeness of individual subcommunities
• raw_sub_beta() : distinctiveness of individual subcommunities
• norm_sub_beta() : per-subcommunity estimate of effective number of distinct subcommunities
• sub_gamma() : contribution per individual in a subcommunity toward metacommunity diversity
• raw_meta_alpha() : naive-community metacommunity diversity
• norm_meta_alpha() : average similarity-sensitive diversity of subcommunities
• raw_meta_rho() : average redundancy of subcommunities
• norm_meta_rho() : average representativeness of subcommunities
• raw_meta_beta() : average distinctiveness of subcommunities
• norm_meta_beta() : effective number of distinct subcommunities
• meta_gamma() : metacommunity similarity-sensitive diversity

Phylogenetic diversity (described here) is automatically included in the Diversity module when the Phylo package is loaded. Documentation for these diversity measures can be found here. The phylogenetics code relies on the Phylo package to generate trees to incorporate into the diversity code, and the ppropriate code will be created when both main packages are loaded:

julia> using Diversity, Phylo

julia> communities = [4 1; 3 2; 1 0; 0 1] / 12;

julia> nt = rand(Nonultrametric(4))
RootedTree with 4 tips, 7 nodes and 6 branches.
Leaf names are tip 1, tip 2, tip 4 and tip 3


julia> metaphylo = Metacommunity(communities, PhyloBranches(nt));

julia> raw_meta_rho(metaphylo, [1, 2])
2×8 DataFrame
│ Row │ div_type            │ measure │ q     │ type_level │ type_name │ partition_level │ partition_name │ diversity │
│     │ String              │ String  │ Int64 │ String     │ String    │ String          │ String         │ Float64   │
├─────┼─────────────────────┼─────────┼───────┼────────────┼───────────┼─────────────────┼────────────────┼───────────┤
│ 1   │ Phylogenetic Branch │ RawRho  │ 1     │ types      │           │ metacommunity   │                │ 1.7787    │
│ 2   │ Phylogenetic Branch │ RawRho  │ 2     │ types      │           │ metacommunity   │                │ 1.66749   │

Genetic diversity is provided by two lightweight extensions, so you only load what your data needs: BioSequences for a vector of aligned sequences, and PopGen for a PopData object read from a VCF file. Similarity between types is derived from pairwise genetic distances, mirroring the gen2dist() / dist2sim() pipeline in rdiversity. Documentation for these measures can be found here.

julia> using Diversity, BioSequences

julia> seqs = [dna"ACGTACGT", dna"ACGAACGT", dna"TTTTTTTT"];

julia> gt = GeneticType(seqs; names = ["a", "b", "c"]);

julia> meta_gamma(Metacommunity([0.3, 0.3, 0.4], gt), 0).diversity
1-element Vector{Float64}:
 1.930059437936407

The package also provides some other sub-modules for related measures:

Many existing ecological diversity measures can be derived from our diversity measures, and so we provide them in the Diversity.Ecology submodule along with generalised versions of them that relate to our general measures of alpha, beta and gamma diversity at subcommunity and metacommunity levels. The generalisations of species richness, Shannon entropy and Simpson's index are the only standard measures we are aware of whose subcommunity components sum directly to the corresponding metacommunity measure (although note that Simpson's index decreases for increased diversity, so small components are more diverse). Documentation for these diversity measures can be found here.

Hill numbers are found in the Diversity.Hill sub-module. Documentation for these diversity measures can be found here.

Lou Jost's diversity measures are found in the Diversity.Jost sub-module. Documentation for these diversity measures is here.

Documentation is generated by the Base documentation in Julia and online via the Documenter package.

Accessing the documentation in Julia is easy:

using Diversity

# Returns any documentation for the subdiv() function
?subdiv

The documentation is also available online.

The online documentation for the current stable release is here.

The online documentation for the latest dev (unreleased) branch is here.