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).

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

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)

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)

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)

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

Calculates Gower's dissimarity of up to two columns representing independent subcommunity counts.

Arguments:

• proportions: population proportions; or
• count: population counts; or
• asm: Abstract Assemblage
• ``

Returns:

• Gower dissimilarity of the subcommunities

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

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)

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

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

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

Diversity.ShortNames submodule

We do not directly export ᾱ, α, β̄, β, ρ̄, ρ, γ as they're too short. γ actually can't be exported like this - it'll always just be Shortnames.γ, so we export Γ instead.

All of these can only be accessed via Diversity.ShortNames.

Diversity.Jost submodule

Lou Jost's diversity measures are found in the Diversity.Jost module.

jostalpha(proportions::AbstractMatrix, qs)

Calculates Jost's alpha diversity of a series of columns representing independent community counts, for a series of orders, repesented as a vector of qs. This is just the naive-community ecosystem diversity divided by the naive-community beta diversity.

Arguments:

• proportions relative proportions of different individuals / species in population (vector, or matrix where columns are for individual sub-communities)

• qs single number or vector of orders of diversity measurement

Returns:

• DataFrame of diversities

jostbeta(proportions::AbstractMatrix, qs)

Calculates Jost's beta diversity of a series of columns representing independent community counts, for a series of orders, repesented as a vector of qs. This is just the naive gamma diversity divided by Jost's alpha diversity

Arguments:

• proportions relative proportions of different individuals / species in population (vector, or matrix where columns are for individual sub-communities)

• qs single number or vector of orders of diversity measurement

Returns:

• DataFrame of diversities

Diversity.API submodule

The Diversity.API submodule should be imported if you want to create a new type, partition or metacommunity subtype. Otherwise it can be ignored.

AbstractMetacommunity{FP <: AbstractFloat,
                      ARaw <: AbstractArray,
                      AProcessed <: AbstractMatrix{FP},
                      Sim <: AbstractTypes,
                      Part <: AbstractPartition}

AbstractMetacommunity is the abstract supertype of all metacommunity types. AbstractMetacommunity subtypes allow you to define how to partition your total metacommunity (e.g. an ecosystem) into smaller components (e.g. subcommunities), and how to assess similarity between individuals within it.

AbstractPartition

Abstract supertype for all partitioning types. AbstractPartition subtypes allow you to define how to partition your total metacommunity (e.g. an ecosystem) into smaller components (e.g. subcommunities).

AbstractTypes

Abstract supertype for all similarity types. Its subtypes allow you to define how similarity is measured between individuals.

_addedoutputcols(::AbstractTypes)

Returns the name of any additional columns needed to be added to outputs.

_calcabundance(t::AbstractTypes, a::AbstractArray)

Calculates the abundance a for AbstractTypes, t (if necessary). May be implemented by each AbstractTypes subtype.

_calcordinariness(t::AbstractTypes, a::AbstractArray, scale::Real)

Calculates the ordinariness of abundance a from AbstractTypes, t. May be implemented by each AbstractTypes subtype.

_calcsimilarity(t::AbstractTypes, scale::Real)

Retrieves (and possibly calculates) a similarity matrix from t. Must be implemented by each AbstractTypes subtype.

_countsubcommunities(::AbstractPartition)

Returns number of subcommunities in a partition, p. May be implemented by each AbstractPartition subtype. Default is to count length of subcommunity name vector.

_counttypes(::AbstractTypes, raw::Bool)

Returns number of types in an AbstractTypes object, t. May be implemented by each AbstractTypes subtype. raw determines whether to count the number of raw or processed types, which varies, for instance, when the types are determined by a phylogeny. Default is to count length of corresponding types name vector.

_getabundance(m::AbstractMetacommunity, raw::Bool)

Returns the abundances array of the metacommunity. Must be implemented by each AbstractMetacommunity subtype.

_getaddedoutput(::AbstractTypes)

Returns the name of any additional columns needed to be added to outputs.

_getdiversityname(::AbstractTypes)

Returns the name of the diversity type used to calculate.

_getmetaabundance(m::AbstractMetacommunity, raw::Bool)

Returns the metacommunity abundances of the metacommunity. May be implemented by each AbstractMetacommunity subtype.

_getmetaordinariness!(m::AbstractMetacommunity)

Returns (and possibly calculates) the ordinariness of the metacommunity as a whole. May be implemented by each AbstractMetacommunity subtype.

_getordinariness!(m::AbstractMetacommunity)

Returns (and possibly calculates) the ordinariness array of the subcommunities. May be implemented by each AbstractMetacommunity subtype.

_getpartition(::AbstractMetacommunity)

Returns the AbstractPartition component of the metacommunity. Must be implemented by each AbstractMetacommunity subtype.

_getscale(m::AbstractMetacommunity)

Returns a scaling factor for the metacommunity (needed for phylogenetics). Normally ignored. Must be implemented by each AbstractMetacommunity subtype.

_getsubcommunitynames(p::AbstractPartition)

Returns the names of the subcommunities in the partition object. Must be implemented by each AbstractPartition subtype.

_gettypenames(t::AbstractTypes, raw::Bool)

Returns the names of the types in an AbstractTypes object. Must be implemented by each AbstractTypes subtype. raw determines whether to count the number of raw or processed types, which varies, for instance, when the types are determined by a phylogeny.

_gettypes(::AbstractMetacommunity)

Returns the AbstractTypes component of the metacommunity. Must be implemented by each AbstractMetacommunity subtype.

_getweight(m::AbstractMetacommunity)

Returns the subcommunity weights of the metacommunity. May be implemented by each AbstractMetacommunity subtype.

floattypes(t)

This function returns a set containing the floating point types that are compatible with the Diversity-related object, t.

mcmatch(procm::AbstractArray, sim::AbstractTypes, part::AbstractPartition)

Checks for type and size compatibility for elements contributing to a Metacommunity

typematch(args...)

Checks whether the types of a variety of Diversity-related objects have compatible types (using floattypes()).

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.

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.

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.

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.

Enumeration of levels that can exist / be calculated for a metacommunity.

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.

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

GeneralTypes{FP, M, LABELS}

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.

• names Vector of type names.

GeneralTypes(zmatrix::M)
GeneralTypes(zmatrix::M, names::LABELS)

Constructors for GeneralTypes. Creates an instance of the GeneralTypes class, with an arbitrary zmatrix similarity matrix and an optional vector of type names.

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.

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

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

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

Onecommunity

AbstractPartition subtype containing only one subcommunity.

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.

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

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

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

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.

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.

Subcommunities(num)

AbstractPartition subtype with multiple subcommunities.

Taxonomy

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

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.

_getmeta(dm::DiversityMeasure)

Return the metacommunity belonging to the DiversityMeasure.

addedoutputcols(m::AbstractAssemblage)
addedoutputcols(t::AbstractTypes)

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

calcsimilarity(t::AbstractTypes, scale::Real)

Retrieves (and possibly calculates) a similarity matrix from t.

countsubcommunities(m::AbstractAssemblage)
countsubcommunities(p::AbstractPartition)

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

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.

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.

getASCIIName(dm::DiversityMeasure)

Return the ASCII name of the DiversityMeasure

Arguments:

• dm: DiversityMeasure

Returns:

• String containing simple ASCII name of DiversityMeasure

getFullName(dm::DiversityMeasure)

Return the full name of the DiversityMeasure.

Arguments:

• dm: DiversityMeasure

Returns:

• String containing full descriptive name of DiversityMeasure

getName(dm::DiversityMeasure)

Return the character corresponding to the DiversityMeasure.

Arguments:

• dm: DiversityMeasure

Returns:

• String containing unicode (greek) name of DiversityMeasure.

getabundance(m::AbstractAssemblage, raw::Bool)

Returns the abundances array of the metacommunity.

getaddedoutput(::AbstractTypes)

Returns the contents of any additional columns to be added to outputs.

getdiversityname(m::AbstractAssemblage)
getdiversityname(t::AbstractTypes)

Returns the name of the diversity type used.

getmetaabundance(m::AbstractAssemblage)

Returns the metacommunity abundances of the metacommunity.

getmetaordinariness!(m::AbstractAssemblage)

Returns (and possibly calculates) the ordinariness of the metacommunity as a whole.

getordinariness!(m::AbstractAssemblage)

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

getpartition(m::AbstractAssemblage)

Returns the AbstractPartition component of the metacommunity.

getsubcommunitynames(m::AbstractAssemblage)
getsubcommunitynames(p::AbstractPartition)

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

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.

gettypes(m::AbstractAssemblage)

Returns the AbstractTypes component of the metacommunity.

getweight(m::AbstractAssemblage)

Returns the subcommunity weights of the metacommunity.

hassimilarity(t::AbstractAssemblage)
hassimilarity(t::AbstractThings)

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

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.

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.

powermean

Calculates the weighted powermean of a series of numbers

Calculates orderth power mean of values, weighted by weights. By default, weights are equal and order is 1, so this is just the arithmetic mean.

Arguments:

• values: values for which to calculate mean
• order[s]: order[s] of power mean
• weights: weights of elements, normalised to 1 inside function

Returns:

• weighted power mean(s)

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)

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)

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.

Diversity.Hill submodule

Hill numbers are found in the Diversity.Hill package.

hillnumber(proportions, qs)

Calculate the Hill number (or naive diversity) of order q of population(s) with given relative proportions

Arguments:

• proportions: relative proportions of different individuals / species in population (vector, or matrix where columns are individual populations)

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

Returns:

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