Skip to content

Diversity.jl

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×7 DataFrames.DataFrame
│ Row │ measure           │ q   │ type_level │ type_name │ partition_level │
├─────┼───────────────────┼─────┼────────────┼───────────┼─────────────────┤
│ 1   │ "NormalisedAlpha" │ 0.0 │ "types"    │ ""        │ "metacommunity" │
│ 2   │ "NormalisedAlpha" │ 1.0 │ "types"    │ ""        │ "metacommunity" │
│ 3   │ "NormalisedAlpha" │ 2.0 │ "types"    │ ""        │ "metacommunity" │
│ 4   │ "NormalisedAlpha" │ Inf │ "types"    │ ""        │ "metacommunity" │

│ Row │ partition_name │ diversity │
├─────┼────────────────┼───────────┤
│ 1   │ ""             │ 2.16667   │
│ 2   │ ""             │ 1.86121   │
│ 3   │ ""             │ 1.63636   │
│ 4   │ ""             │ 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×7 DataFrames.DataFrame
│ Row │ measure  │ q │ type_level │ type_name │ partition_level │
├─────┼──────────┼───┼────────────┼───────────┼─────────────────┤
│ 1   │ "RawRho" │ 2 │ "types"    │ ""        │ "subcommunity"  │
│ 2   │ "RawRho" │ 2 │ "types"    │ ""        │ "subcommunity"  │
│ 3   │ "RawRho" │ 2 │ "types"    │ ""        │ "subcommunity"  │

│ Row │ partition_name │ diversity │
├─────┼────────────────┼───────────┤
│ 1   │ "1"            │ 2.0       │
│ 2   │ "2"            │ 3.0       │
│ 3   │ "3"            │ 3.0       │

# Diversity — Module.

The main Diversity module 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.individualDiversity — Constant.

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.metacommunityDiversity — Constant.

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.subcommunityDiversity — Constant.

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.DiversityLevel — Type.

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

source

# Diversity.DiversityMeasure — Type.

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.Gamma — Type.

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.GeneralTypes — Type.

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.Metacommunity — Type.

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.NormalisedAlpha — Type.

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.NormalisedBeta — Type.

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.NormalisedRho — Type.

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.Onecommunity — Type.

Onecommunity

AbstractPartition subtype containing only one subcommunity.

source

# Diversity.PowerMeanMeasure — Type.

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.RawAlpha — Type.

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.RawBeta — Type.

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.RawRho — Type.

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.RelativeEntropyMeasure — Type.

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.Species — Type.

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.Subcommunities — Type.

Subcommunities(num)

AbstractPartition subtype with multiple subcommunities.

source

# Diversity.Taxonomy — Type.

Taxonomy

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

source

# Diversity.UniqueTypes — Type.

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.calcsimilarity — Method.

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

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

source

# Diversity.countsubcommunities — Function.

countsubcommunities(m::AbstractMetacommunity)
countsubcommunities(p::AbstractPartition)

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

source

# Diversity.counttypes — Function.

counttypes(m::AbstractMetacommunity[, raw::Bool = false])
counttypes(t::AbstractTypes[, raw::Bool = false])

Returns number of types in an AbstractTypes object or the AbstractMetacommunity 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.diversity — Method.

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.getASCIIName — Method.

getASCIIName(dm::DiversityMeasure)

Return the ASCII name of the DiversityMeasure

Arguments:

  • dm: DiversityMeasure

Returns:

  • String containing simple ASCII name of DiversityMeasure

source

# Diversity.getFullName — Function.

getFullName(dm::DiversityMeasure)

Return the full name of the DiversityMeasure.

Arguments:

  • dm: DiversityMeasure

Returns:

  • String containing full descriptive name of DiversityMeasure

source

# Diversity.getName — Function.

getName(dm::DiversityMeasure)

Return the character corresponding to the DiversityMeasure.

Arguments:

  • dm: DiversityMeasure

Returns:

  • String containing unicode (greek) name of DiversityMeasure.

source

# Diversity.getabundance — Function.

getabundance(m::AbstractMetacommunity)

Returns the abundances array of the metacommunity.

source

# Diversity.getmetaabundance — Function.

getmetaabundance(m::AbstractMetacommunity)

Returns the metacommunity abundances of the metacommunity.

source

# Diversity.getmetaordinariness! — Method.

getmetaordinariness!(m::AbstractMetacommunity)

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

source

# Diversity.getordinariness! — Method.

getordinariness!(m::AbstractMetacommunity)

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

source

# Diversity.getpartition — Method.

getpartition(m::AbstractMetacommunity)

Returns the AbstractPartition component of the metacommunity.

source

# Diversity.getsubcommunitynames — Function.

getsubcommunitynames(m::AbstractMetacommunity)
getsubcommunitynames(p::AbstractPartition)

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

source

# Diversity.gettypenames — Function.

gettypenames(m::AbstractMetacommunity[, raw::Bool = false])
gettypenames(t::AbstractTypes[, raw::Bool = false])

Returns the names of the types of the AbstractTypes object or the AbstractMetacommunity 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.gettypenames — Method.

gettypenames(dm::DiversityMeasure)

Return the names of the types of the metacommunity being analysed

Arguments:

  • dm: DiversityMeasure

Returns:

  • Vector of Strings of names of types.

source

# Diversity.gettypes — Method.

gettypes(m::AbstractMetacommunity)

Returns the AbstractTypes component of the metacommunity.

source

# Diversity.getweight — Method.

getweight(m::AbstractMetacommunity)

Returns the subcommunity weights of the metacommunity.

source

# Diversity.inddiv — Function.

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.metadiv — Function.

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.qD — Function.

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.qDZ — Function.

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.subdiv — Function.

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