Diversity.jl

A package for measuring and partitioning diversity

The main Diversity 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 Reeve et al, 2014). 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 longer ASCII names (e.g. NormalisedAlpha()), which are. We also provide functions to calculate appropriate subdiv() and metadiv() values for each measure, a general diversity() function for extract any diversity measure at a series of scales.

Accessing the main functionality in the package is simple:

julia> # Load the package into R
       using Diversity

julia> # Example population
       pop = [1 1 0; 2 0 0; 3 1 4];

julia> pop = pop / sum(pop);

julia> # Create Metacommunity object
       meta = Metacommunity(pop);

julia> diversities = norm_meta_alpha(meta, [0, 1, 2, Inf])
4×8 DataFrame
│ Row │ div_type │ measure         │ q       │ type_level │ type_name │ partition_level │ partition_name │ diversity │
│     │ String   │ String          │ Float64 │ String     │ String    │ String          │ String         │ Float64   │
├─────┼──────────┼─────────────────┼─────────┼────────────┼───────────┼─────────────────┼────────────────┼───────────┤
│ 1   │ Unique   │ NormalisedAlpha │ 0.0     │ types      │           │ metacommunity   │                │ 2.16667   │
│ 2   │ Unique   │ NormalisedAlpha │ 1.0     │ types      │           │ metacommunity   │                │ 1.86121   │
│ 3   │ Unique   │ NormalisedAlpha │ 2.0     │ types      │           │ metacommunity   │                │ 1.63636   │
│ 4   │ Unique   │ NormalisedAlpha │ Inf     │ types      │           │ metacommunity   │                │ 1.0       │

julia> Z = [1.0 0 0; 0 1 1; 1 1 1];

julia> meta_z = Metacommunity(pop, Z);

julia> rho = RawRho(meta_z);

julia> redundancies = subdiv(rho, 2)
3×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   │ Arbitrary Z │ RawRho  │ 2     │ types      │           │ subcommunity    │ 1              │ 2.0       │
│ 2   │ Arbitrary Z │ RawRho  │ 2     │ types      │           │ subcommunity    │ 2              │ 3.0       │
│ 3   │ Arbitrary Z │ RawRho  │ 2     │ types      │           │ subcommunity    │ 3              │ 3.0       │
Diversity.DiversityModule
Diversity package

The main Diversity 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 Reeve et al, 2014). 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 longer ASCII names (e.g. NormalisedAlpha()), which are. We also provide functions to calculate appropriate subcommunityDiversity() and metacommunityDiversity() values for each measure, a general diversity() function for extract any diversity measure at a series of scales.

source
Diversity.individualDiversityConstant

Generates the function to calculate individual diversities

Generates the function to calculate individual diversities for a series of orders, represented as a vector of qs.

Arguments:

  • dm: DiversityMeasure

Returns:

  • Function which takes a single number or vector of values of parameter q, and returns the individual diversities for those values.
source
Diversity.metacommunityDiversityConstant

Generates the function to calculate metacommunity diversity

Generates the function to calculate metacommunity diversity for a series of orders, represented as a vector of qs.

Arguments:

  • dm: DiversityMeasure

Returns:

  • Function which takes a single number or vector of values of parameter q, and returns the metacommunity diversities for those values.
source
Diversity.subcommunityDiversityConstant

Generates the function to calculate subcommunity diversity

Generates the function to calculate subcommunity diversity for a series of orders, represented as a vector of qs.

Arguments:

  • dm: DiversityMeasure

Returns:

  • Function which takes a single number or vector of values of parameter q, and returns the subcommunity diversities for those values.
source
Diversity.DiversityMeasureType
DiversityMeasure

This type is the abstract supertype of all diversity measure types. DiversityMeasure subtypes allow you to calculate and cache any kind of diversity of a metacommunity.

source
Diversity.GammaType
Gamma

Calculates gamma diversity (γ) of all of the individuals in a metacommunity, and caches them for subsequent analysis. This is a subtype of PowerMeanMeasure, meaning that all composite diversity measures are simple powermeans of the individual measures.

Constructor arguments:

  • meta: a Metacommunity
source
Diversity.GeneralTypesType
GeneralTypes{FP, M}

An AbstractTypes subtype with a general similarity matrix. This subtype simply holds a matrix with similarities between individuals.

Members:

  • z A two-dimensional matrix representing similarity between

individuals.

source
Diversity.MetacommunityType
Metacommunity{FP, ARaw, AProcessed, Part, Sim}

Metacommunity type, representing a whole metacommunity containing a single community or a collection of subcommunities. The metacommunity of individuals may be further partitioned into smaller groups. For instance this may be an ecosystem, which consists of a series of subcommunities. The AbstractPartition subtype within it stores relative abundances of different types, e.g. species, and also allows for similarity between individuals.

Constructor:

Metacommunity(abundances::AbstractArray, part::AbstractPartition, types::AbstractTypes)

Members:

  • abundances the abundance matrix for the metacommunity.

  • partition the instance of the AbstractPartition subtype, containing the subcommunities.

  • types The instance of the AbstractTypes subtype, from which similarities between individuals can be calculated.

  • ordinariness A cache of the ordinariness of the individuals in the Partition. Should only be accessed through getordinariness!(::Metacommunity), which will populate the cache if it has not yet been calculated.

source
Diversity.NormalisedAlphaType
NormalisedAlpha

Calculates normalised alpha diversity (ᾱ) of all of the individuals in a metacommunity, and caches them for subsequent analysis. This is a subtype of PowerMeanMeasure, meaning that all composite diversity measures are simple powermeans of the individual measures.

Constructor arguments:

  • meta: a Metacommunity
source
Diversity.NormalisedBetaType
NormalisedBeta

Calculates normalised beta diversity (β̄) of all of the individuals in a metacommunity, and caches them for subsequent analysis. This is a subtype of RelativeEntropyMeasure, meaning that subcommunity and type composite diversity measures are relative entropies, and their composite types are powermeans of those measures.

Constructor arguments:

  • meta: a Metacommunity
source
Diversity.NormalisedRhoType
NormalisedRho

Calculates redundancy (ρ̄, normalised beta diversity) of all of the individuals in a metacommunity, and caches them for subsequent analysis. This is a subtype of PowerMeanMeasure, meaning that all composite diversity measures are simple powermeans of the individual measures.

Constructor arguments:

  • meta: a Metacommunity
source
Diversity.PowerMeanMeasureType
PowerMeanMeasure

This abstract DiversityMeasure subtype is the supertype of all diversity measures which are straight power means. PowerMeanMeasure subtypes allow you to calculate and cache any kind of diversity of a metacommunity.

source
Diversity.RawAlphaType
RawAlpha

Calculates raw alpha diversity (α) of all of the individuals in a metacommunity, and caches them for subsequent analysis. This is a subtype of PowerMeanMeasure, meaning that all composite diversity measures are simple powermeans of the individual measures.

Constructor arguments:

  • meta: a Metacommunity
source
Diversity.RawBetaType
RawBeta

Calculates distinctiveness (β, raw beta diversity) of all of the individuals in a metacommunity, and caches them for subsequent analysis. This is a subtype of RelativeEntropyMeasure, meaning that subcommunity and type composite diversity measures are relative entropies, and their composite types are powermeans of those measures.

Constructor arguments:

  • meta: a Metacommunity
source
Diversity.RawRhoType
RawRho

Calculates redundancy (ρ, raw beta diversity) of all of the individuals in a metacommunity, and caches them for subsequent analysis. This is a subtype of PowerMeanMeasure, meaning that all composite diversity measures are simple powermeans of the individual measures.

Constructor arguments:

  • meta: a Metacommunity
source
Diversity.RelativeEntropyMeasureType
RelativeEntropyMeasure

This abstract DiversityMeasure subtype is the supertype of all diversity measures which are relative entropy-based diversity measures. RelativeEntropyMeasure subtypes allow you to calculate and cache any kind of diversity of a metacommunity.

source
Diversity.SpeciesType
Species

A subtype of AbstractTypes where all species are completely distinct. This type is the simplest AbstractTypes subtype, which identifies all species as unique and completely distinct from each other.

source
Diversity.TaxonomyType
Taxonomy

A subtype of AbstractTypes with similarity between related taxa, creating taxonomic similarity matrices.

source
Diversity.UniqueTypesType
UniqueTypes

A subtype of AbstractTypes where all individuals are completely distinct. This type is the simplest AbstractTypes subtype, which identifies all individuals as unique and completely distinct from each other.

source
Diversity.addedoutputcolsFunction
addedoutputcols(m::AbstractAssemblage)
addedoutputcols(t::AbstractTypes)

Returns the name of any additional columns needed to disambiguate the diversity type used.

source
Diversity.countsubcommunitiesFunction
countsubcommunities(m::AbstractAssemblage)
countsubcommunities(p::AbstractPartition)

Returns number of subcommunities in an AbstractPartition object or the AbstractAssemblage containing it.

source
Diversity.counttypesFunction
counttypes(m::AbstractAssemblage[, raw::Bool = false])
counttypes(t::AbstractTypes[, raw::Bool = false])

Returns number of types in an AbstractTypes object or the AbstractAssemblage containing it. raw determines whether to count the number of raw or processed types, which varies, for instance, when the types are determined by a phylogeny.

source
Diversity.diversityMethod

Calculates subcommunity and metacommunity diversities

Calculates any diversity of a Metacommunity for a series of orders, repesented as one or a vector of qs.

Arguments:

  • dls: an iterable collection of DiversityLevels
  • dms: an iterable collection of DiversityMeasures
  • meta: a Metacommunity
  • qs: single number or vector of values of parameter q

Returns:

A vector containing all of the diversity levels of all of the requested diversities.

source
Diversity.getASCIINameMethod
getASCIIName(dm::DiversityMeasure)

Return the ASCII name of the DiversityMeasure

Arguments:

  • dm: DiversityMeasure

Returns:

  • String containing simple ASCII name of DiversityMeasure
source
Diversity.getFullNameFunction
getFullName(dm::DiversityMeasure)

Return the full name of the DiversityMeasure.

Arguments:

  • dm: DiversityMeasure

Returns:

  • String containing full descriptive name of DiversityMeasure
source
Diversity.getNameFunction
getName(dm::DiversityMeasure)

Return the character corresponding to the DiversityMeasure.

Arguments:

  • dm: DiversityMeasure

Returns:

  • String containing unicode (greek) name of DiversityMeasure.
source
Diversity.getdiversitynameFunction
getdiversityname(m::AbstractAssemblage)
getdiversityname(t::AbstractTypes)

Returns the name of the diversity type used.

source
Diversity.getordinariness!Method
getordinariness!(m::AbstractAssemblage)

Returns (and possibly calculates) the ordinariness array of the subcommunities.

source
Diversity.getsubcommunitynamesFunction
getsubcommunitynames(m::AbstractAssemblage)
getsubcommunitynames(p::AbstractPartition)

Returns the names of the subcommunities in an AbstractPartition object or the AbstractAssemblage containing it.

source
Diversity.gettypenamesFunction
gettypenames(m::AbstractAssemblage[, raw::Bool = false])
gettypenames(t::AbstractTypes[, raw::Bool = false])

Returns the names of the types of the AbstractTypes object or the AbstractAssemblage containing it. raw determines whether to count the number of raw or processed types, which varies, for instance, when the types are determined by a phylogeny.

source
Diversity.gettypesMethod
gettypes(m::AbstractAssemblage)

Returns the AbstractTypes component of the metacommunity.

source
Diversity.hassimilarityFunction
hassimilarity(t::AbstractAssemblage)
hassimilarity(t::AbstractThings)

Is there similarity of some non-trivial type in the object?

source
Diversity.inddivFunction
inddiv(measure::DiversityMeasure, q::Real)
inddiv(measure::DiversityMeasure, qs::AbstractVector{Real})

Takes a diversity measure and single order or vector of orders, and returns a DataFrame containing the individual diversities for those values.

Arguments:

  • dm: DiversityMeasure
  • q / qs: a single order or a vector of orders

Returns:

  • Returns individual diversities of dm for a single order q or a vector of order qs.
source
Diversity.metadivFunction
metadiv(measure::DiversityMeasure, q::Real)
metadiv(measure::DiversityMeasure, qs::AbstractVector{Real})

Takes a diversity measure and single order or vector of orders, and calculates and returns the metacommunity diversities for those values.

Arguments:

  • dm: DiversityMeasure
  • q / qs: a single order or a vector of orders

Returns:

  • Returns metacommunity diversities of dm for a single order q or a vector of order qs.
source
Diversity.qDFunction
qD

Calculates Hill / naive-similarity diversity of order(s) qs of a population with given relative proportions.

Arguments:

  • proportions: relative proportions of different types in population

  • qs: single number or vector of orders of diversity measurement

Returns:

  • Diversity of order qs (single number or vector of diversities)
source
Diversity.qDZFunction
qDZ

Calculates Leinster-Cobbold / similarity-sensitive diversity of >= 1 order(s) qs of a population with given relative proportions, and similarity matrix Z.

Arguments:

  • proportions: relative proportions of different types in a population

  • qs: single number or vector of orders of diversity measurement

  • Z: similarity matrix

Returns:

  • Diversity of order qs (single number or vector of diversities)

source
Diversity.subdivFunction
subdiv(measure::DiversityMeasure, q::Real)
subdiv(measure::DiversityMeasure, qs::AbstractVector{Real})

Takes a diversity measure and single order or vector of orders, and calculates and returns the subcommunity diversities for those values.

Arguments:

  • dm: DiversityMeasure
  • q / qs: a single order or a vector of orders

Returns:

  • Returns subcommunity diversities of dm for a single order q or a vector of order qs.
source