Package for measuring and partitioning diversity
|Documentation||PackageEvaluator||Build Status of master|
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 uses the diversity measures described in the arXiv paper arXiv:1404.6520 (q-bio.QM), How to partition diversity. It also provides a series of other related and older diversity measures through sub-modules. Currently these are all ecological diversity measures, but this will be expanded, possibly through interfacing to BioJulia.
This package is in beta now, but is cross-validated against our R package boydorr/rdiversity, which is developed independently, so please raise an issue if you find any problems. The phylogenetics submodule in particular is currently under heavy development.
Version 0.3, which has been recently released, has significant breaking changes to the standard interface for calculating diversity and especially to the output format to provide consistency with our R package rdiversity. In particular, we now use a DataFrame as the common output format for all of the diversity calculations. The code is certainly not optimised for speed at the moment due to the substantial changes that have happened to it under the hood.
Older interfaces have been deprecated, and will be removed in v0.4.
Diversity is in
METADATA and can be installed via
The main package provides basic numbers-equivalent diversity measures (described in Hill, 1973), similarity-sensitive diversity measures (generalised from Hill, and described in Leinster and Cobbold, 2012), and related alpha, beta and gamma diversity measures at the level of the metacommunity and its component subcommunities (generalised in turn from Leinster and Cobbold, and described in arXiv:1404.6520 (q-bio.QM)). 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 for 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 R 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;
# First, calculate the normalised alpha component component = NormalisedAlpha(meta)
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
# 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:
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 included in the Diversity.Phylogenetics submodule. 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:
julia> using Diversity, Phylo, Diversity.Phylogenetics julia> communities = [4 1; 3 2; 1 0; 0 1] / 12; julia> nt = rand(Nonultrametric(4)) NamedTree phylogenetic tree with 7 nodes and 6 branches Leaf names: String["tip 1", "tip 2", "tip 3", "tip 4"] julia> metaphylo = Metacommunity(communities, PhyloTypes(nt)); julia> raw_meta_rho(metaphylo, [1, 2]) 2×7 DataFrames.DataFrame │ Row │ measure │ q │ type_level │ type_name │ partition_level │ ├─────┼──────────┼───┼────────────┼───────────┼─────────────────┤ │ 1 │ "RawRho" │ 1 │ "types" │ "" │ "metacommunity" │ │ 2 │ "RawRho" │ 2 │ "types" │ "" │ "metacommunity" │ │ Row │ partition_name │ diversity │ ├─────┼────────────────┼───────────┤ │ 1 │ "" │ 1.66187 │ │ 2 │ "" │ 1.51391 │
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.
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 branch is here.
The online documentation for the latest master (unreleased) branch is here.
8 days ago