Help for package rdiversity

Type:

Package

Title:

Measurement and Partitioning of Similarity-Sensitive Biodiversity

Version:

2.3.0

Date:

2026-07-15

Maintainer:

Richard Reeve <richard.reeve@glasgow.ac.uk>

URL:

https://github.com/boydorr/rdiversity

BugReports:

https://github.com/boydorr/rdiversity/issues

Description:

Provides a framework for the measurement and partitioning of the (similarity-sensitive) biodiversity of a metacommunity and its constituent subcommunities. Richard Reeve, et al. (2016) <doi:10.48550/arXiv.1404.6520>.

License:

GPL-3

Depends:

R (≥ 3.5.0)

Imports:

methods, stats, stringdist, utils

Suggests:

ape, testthat, knitr, markdown, rmarkdown, covr

Encoding:

UTF-8

VignetteBuilder:

knitr

Collate:

'ancestral_nodes.R' 'bits.R' 'chainsaw.R' 'check_partition.R' 'check_phypartition.R' 'check_similarity.R' 'class-distance.R' 'class-metacommunity.R' 'class-powermean.R' 'class-relativeentropy.R' 'class-similarity.R' 'descendant_tips.R' 'similarity.R' 'dist2sim.R' 'distance.R' 'metadiv.R' 'subdiv.R' 'metacommunity.R' 'diversity-components.R' 'diversity-measures.R' 'gen2dist.r' 'geneid.R' 'genevec.R' 'hs_parameters.R' 'inddiv.R' 'melt_matrix.R' 'phy2branch.R' 'phy2dist.R' 'phy_abundance.R' 'phy_struct.R' 'power_mean.R' 'powermean.R' 'rdiversity-package.R' 'relativeentropy.R' 'repartition.R' 'smatrix.R' 'summarise.R' 'tax2dist.R' 'taxfac.R' 'taxid.R' 'taxmask.R' 'taxvec.R' 'tbar.R' 'zmatrix.R'

Config/roxygen2/version:

8.0.0

NeedsCompilation:

Packaged:

2026-07-15 20:51:55 UTC; richard.reeve

Author:

Sonia Mitchell

[aut], Richard Reeve

[cre, aut, ths], Tom White

[ctb]

Repository:

CRAN

Date/Publication:

2026-07-15 21:10:02 UTC

rdiversity: diversity measurement in R

Description

rdiversity is an R package based around a framework for measuring and partitioning biodiversity using similarity-sensitive diversity measures. It provides functionality for measuring alpha, beta and gamma diversity of metacommunities (e.g. ecosystems) and their constituent subcommunities, where similarity may be defined as taxonomic, phenotypic, genetic, phylogenetic, functional, and so on. It uses the diversity measures described in the arXiv paper, 'How to partition diversity'.

Details

For more information go to our GitHub page; https://github.com/boydorr/rdiversity
Please raise an issue if you find any problems; https://github.com/boydorr/rdiversity/issues
This package is cross-validated against our Julia package; https://github.com/EcoJulia/Diversity.jl

Author(s)

Sonia Mitchell
Richard Reeve <richard.reeve@glasgow.ac.uk> (maintainer)

References

Reeve, R., T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. (https://arxiv.org/abs/1404.6520)

Function to cut the phylogeny to a specified depth from the tip with the greatest distance from the root.

Description

Function to cut the phylogeny to a specified depth from the tip with the greatest distance from the root.

Usage

chainsaw(partition, ps, depth)

Arguments

partition

two-dimensional matrix of mode numeric with rows as types (species), columns as subcommunities, and each element containing the relative abundance of types in each subcommunity relative to the metacommunity as a whole. In the phylogenetic case, this corresponds to the proportional abundance of historical species, which is calculated from the proportional abundance of terminal taxa

ps

phy_struct() output

depth

proportion of total tree height to be conserved (taken as a proportion from the highest tip). Describes how far back we go in the tree, with 0 marking the date of the most recent tip, and 1 marking the most recent common ancestor. Numbers greater than 1 extend the root of the tree

Value

chainsaw() returns an object of class metacommunity

Distance to similarity

Description

Converts distance objects into similarity objects.

Usage

dist2sim(dist, transform, k = 1, normalise = TRUE, max_d)

Arguments

dist

object of class distance

transform

object of class character, can be either "linear" or "exponential"

k

scaling parameter

normalise

object of class logical, which when TRUE will normalise distances to one

max_d

object of class numeric

Details

Distances can be transformed either *linearly* or *exponentially*. That is 1 - k * dist for non-negative values, or exp(-k * dist), respectively. If normalise is true, then dist = dist/max_d.

Value

dist2sim(x) returns an object of class similarity.

Generate distance object

Description

Container for class distance.

Usage

distance(distance, dat_id)

## S4 method for signature 'matrix,character'
distance(distance, dat_id)

## S4 method for signature 'matrix,missing'
distance(distance, dat_id)

Arguments

distance

distance matrix

dat_id

object of class character denoting the type of diversity being calculated. This can be "naive", "genetic", "taxonomic", and so on

Value

distance() returns an object of class distance.

distance-class

Description

Container for class distance.

Usage

## S4 method for signature 'distance'
show(object)

Arguments

object

object of class distance

Fields

distance: two-dimensional matrix of mode numeric with rows as types, columns as types, and elements containing the pairwise distance of types
dat_id: object of class character describing the class of distance / similarity being used, e.g. "naive", "taxonomic", and so on
components: list containing the components necessary to calculate similarity. This list is empty when precompute_dist = TRUE when calculating distance. When a pairwise distance matrix is too large and precompute_dist = FALSE, this list contains all the information required to calculate pairwise distance between types

Genetic distance matrix

Description

Converts variant-call (VCF) genotype data into a matrix of pairwise genetic distances between samples.

Usage

gen2dist(vcf, biallelic = FALSE)

Arguments

vcf

object of class data.frame laid out like the body of a VCF file: a column named FORMAT followed by one column per sample, whose entries begin with the genotype (e.g. "0|0", "0|1", "1|1"). Such a data.frame can be obtained, for example, from the gt element of a vcfR object read in with vcfR::read.vcfR().

biallelic

logical describing whether the data is biallelic or not (default).

Value

gen2dist(x) returns an object of class distance containing a matrix of pairwise genetic distances.

Calculate individual-level diversity

Description

Generic function for calculating individual-level diversity.

Usage

inddiv(data, qs)

## S4 method for signature 'powermean'
inddiv(data, qs)

## S4 method for signature 'relativeentropy'
inddiv(data, qs)

## S4 method for signature 'metacommunity'
inddiv(data, qs)

Arguments

data

matrix of mode numeric; containing diversity components

qs

vector of mode numeric containing q values

Details

data may be input as three different classes:

power_mean: calculates raw and normalised subcommunity alpha, rho or gamma diversity by taking the powermean of diversity components
relativeentropy: calculates raw or normalised subcommunity beta diversity by taking the relative entropy of diversity components
metacommunity: calculates all subcommunity measures of diversity

Value

inddiv() returns a standard output of class rdiv

References

Reeve, R., T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

# Define metacommunity
pop <- cbind.data.frame(A = c(1, 1), B = c(2, 0), C = c(3, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate subcommunity gamma diversity (takes the power mean)
g <- raw_gamma(meta)
inddiv(g, 0:2)

# Calculate subcommunity beta diversity (takes the relative entropy)
b <- raw_beta(meta)
inddiv(b, 0:2)

# Calculate all measures of individual diversity
inddiv(meta, 0:2)

Metacommunity gamma diversity

Description

Calculates similarity-sensitive metacommunity gamma diversity (the metacommunity similarity-sensitive diversity). This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

meta_gamma(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

meta_gamma returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate metacommunity gamma diversity
meta_gamma(meta, 0:2)

Metacommunity

Description

Functions to generate a metacommunity object.

Usage

metacommunity(partition, similarity)

## S4 method for signature 'data.frame,missing'
metacommunity(partition)

## S4 method for signature 'numeric,missing'
metacommunity(partition)

## S4 method for signature 'matrix,missing'
metacommunity(partition)

## S4 method for signature 'missing,similarity'
metacommunity(partition, similarity)

## S4 method for signature 'numeric,similarity'
metacommunity(partition, similarity)

## S4 method for signature 'data.frame,similarity'
metacommunity(partition, similarity)

## S4 method for signature 'matrix,similarity'
metacommunity(partition, similarity)

Arguments

partition

two-dimensional matrix of mode numeric with rows as types, columns as subcommunities, and elements containing the relative abundances of types in subcommunities. For phylogenetic diversity, see Details

similarity

(optional) object of class similarity

Value

metacommunity() returns an object of class metacommunity (see Fields).

Fields

type_abundance: two-dimensional matrix of mode numeric with rows as types (species), columns as subcommunities, and each element containing the relative abundance of types in each subcommunity relative to the metacommunity as a whole. In the phylogenetic case, this corresponds to the proportional abundance of historical species, which is calculated from the proportional abundance of terminal taxa
similarity: two-dimensional matrix of mode numeric with rows as types, columns as types, and elements containing pairwise similarities between types
similarity_components: list containing the components necessary to calculate similarity. This list is empty when precompute_dist = TRUE when calculating distance. When a pairwise distance matrix is too large and precompute_dist = FALSE, this list contains all the information required to calculate pairwise distance between types
similarity_parameters: list containing parameters associated with converting pairwise distances to similarities (the dist2sim() arguments)
ordinariness: two-dimensional matrix of mode numeric with rows as types, columns as subcommunities, and elements containing the ordinariness of types within subcommunities
subcommunity_weights: vector of mode numeric containing subcommunity weights
type_weights: two-dimensional matrix of mode numeric, with rows as types, columns as subcommunities, and elements containing weights of types within a subcommunity
dat_ID: object of class character denoting the type of diversity being calculated. This can be "naive", "genetic", "taxonomic", and so on
raw_abundance: [Phylogenetic] two-dimensional matrix of mode numeric with rows as types, columns as subcommunities, and elements containing the relative abundance of present day species
raw_structure: [Phylogenetic] two-dimensional matrix of mode numeric with rows as historical species, columns as present day species, and elements containing historical species lengths within lineages
parameters: [Phylogenetic] data.frame containing parameters associated with each historic species in the phylogeny

Examples

# Naive-type
partition <- cbind(a = c(1, 1, 1, 0, 0), b = c(0, 1, 0, 1, 1))
row.names(partition) <- paste0("sp", 1:5)
partition <- partition / sum(partition)
meta <- metacommunity(partition)

metacommunity-class

Description

Container for class metacommunity.

Usage

## S4 method for signature 'metacommunity'
show(object)

Arguments

object

object of class metacommunity

Fields

type_abundance: two-dimensional matrix of mode numeric with rows as types (species), columns as subcommunities, and each element containing the relative abundance of types in each subcommunity relative to the metacommunity as a whole. In the phylogenetic case, this corresponds to the proportional abundance of historical species, which is calculated from the proportional abundance of terminal taxa
similarity: two-dimensional matrix of mode numeric with rows as types, columns as types, and elements containing the pairwise similarity of types
similarity_components: list containing the components necessary to calculate similarity. This list is empty when precompute_dist = TRUE when calculating distance. When a pairwise distance matrix is too large and precompute_dist = FALSE, this list contains all the information required to calculate pairwise distance between types
similarity_parameters: list containing parameters associated with converting pairwise distances to similarities (the dist2sim() arguments)
ordinariness: two-dimensional matrix of mode numeric with rows as types, columns as subcommunities, and elements containing the ordinariness of types within subcommunities
subcommunity_weights: vector of mode numeric containing subcommunity weights
type_weights: two-dimensional matrix of mode numeric, with rows as types, columns as subcommunities, and elements containing weights of types within a subcommunity
dat_id: object of class character describing the class of distance / similarity being used, e.g. "naive", "taxonomic", and so on
raw_abundance: [Phylogenetic] two-dimensional matrix of mode numeric with rows as types, columns as subcommunities, and elements containing the relative abundance of present day species
raw_structure: [Phylogenetic] two-dimensional matrix of mode numeric with rows as historical species, columns as present day species, and elements containing historical species lengths within lineages
parameters: [Phylogenetic] data.frame containing parameters associated with each historic species in the phylogeny

Metacommunity-level diversity

Description

Generic function for calculating metacommunity-level diversity.

Usage

metadiv(data, qs)

## S4 method for signature 'powermean'
metadiv(data, qs)

## S4 method for signature 'relativeentropy'
metadiv(data, qs)

## S4 method for signature 'metacommunity'
metadiv(data, qs)

Arguments

data

matrix of mode numeric; containing diversity components

qs

vector of mode numeric containing q values

Details

data may be input as one of three different classes:

powermean: raw or normalised metacommunity alpha, rho or gamma diversity components; will calculate metacommunity-level raw or normalised metacommunity alpha, rho or gamma diversity
relativeentropy: raw or normalised metacommunity beta diversity components; will calculate metacommunity-level raw or normalised metacommunity beta diversity
metacommunity: will calculate all metacommunity measures of diversity

Value

metadiv() returns a standard output of class rdiv

References

Reeve, R., T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

# Define metacommunity
pop <- data.frame(a = c(1, 3), b = c(1, 1))
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate metacommunity gamma diversity (takes the power mean)
g <- raw_gamma(meta)
metadiv(g, 0:2)

# Calculate metacommunity beta diversity (takes the relative entropy)
b <- raw_beta(meta)
metadiv(b, 0:2)

# Calculate all measures of metacommunity diversity
metadiv(meta, 0:2)

Normalised alpha (low level diversity component)

Description

Calculates the low-level diversity component necessary for calculating normalised alpha diversity.

Usage

norm_alpha(meta)

Arguments

meta

object of class metacommunity

Details

Values generated from norm_alpha() may be input into subdiv() and metadiv() to calculate normalised subcommunity and metacommunity alpha diversity.

Value

norm_alpha returns an object of class powermean

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate normalised alpha component
a <- norm_alpha(meta)
subdiv(a, 1)
metadiv(a, 1)

Normalised beta (low level diversity component)

Description

Calculates the low-level diversity component necessary for calculating normalised beta diversity.

Usage

norm_beta(meta)

Arguments

meta

object of class metacommunity

Details

Values generated from norm_beta() may be input into subdiv() and metadiv() to calculate normalised subcommunity and metacommunity beta diversity.

Value

norm_beta returns an object of class relativeentropy

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate normalised beta component
b <- norm_beta(meta)
subdiv(b, 1)
metadiv(b, 1)

Normalised metacommunity alpha diversity

Description

Calculates similarity-sensitive normalised metacommunity alpha diversity (the average similarity-sensitive diversity of subcommunities). This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

norm_meta_alpha(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

norm_meta_alpha returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate normalised metacommunity alpha diversity
norm_meta_alpha(meta, 0:2)

Normalised metacommunity beta diversity

Description

Calculates similarity-sensitive normalised metacommunity beta diversity (the effective number of distinct subcommunities. This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

norm_meta_beta(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

norm_meta_beta returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate normalised metacommunity beta diversity
norm_meta_beta(meta, 0:2)

Normalised metacommunity rho diversity

Description

Calculates similarity-sensitive normalised metacommunity rho diversity (the average representativeness of subcommunities. This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

norm_meta_rho(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

norm_meta_rho returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate normalised metacommunity rho diversity
norm_meta_rho(meta, 0:2)

Normalised rho (low level diversity component)

Description

Calculates the low-level diversity component necessary for calculating normalised rho diversity.

Usage

norm_rho(meta)

Arguments

meta

object of class metacommunity

Details

Values generated from norm_rho() may be input into subdiv() and metadiv() to calculate normalised subcommunity and metacommunity rho diversity.

Value

norm_rho returns an object of class powermean

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate normalised rho component
r <- norm_rho(meta)
subdiv(r, 1)
metadiv(r, 1)

Normalised subcommunity alpha diversity

Description

Calculates similarity-sensitive normalised subcommunity alpha diversity (the diversity of subcommunity j in isolation. This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

norm_sub_alpha(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

norm_sub_alpha returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate normalised subcommunity alpha diversity
norm_sub_alpha(meta, 0:2)

Normalised subcommunity beta diversity

Description

Calculates similarity-sensitive normalised subcommunity beta diversity (an estimate of the effective number of distinct subcommunities). This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

norm_sub_beta(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

norm_sub_beta returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate normalised subcommunity beta diversity
norm_sub_beta(meta, 0:2)

Normalised subcommunity rho diversity

Description

Calculates similarity-sensitive normalised subcommunity rho diversity (the representativeness of subcommunity j). This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

norm_sub_rho(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

norm_sub_rho returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate normalised subcommunity rho diversity
norm_sub_rho(meta, 0:2)

Phylogenetic similarity

Description

Packages all inputs into an object of class similarity.

Usage

phy2branch(tree, partition, depth = 1)

Arguments

tree

object of class phylo.

partition

two-dimensional matrix of mode numeric with rows as types (terminal taxa), columns as subcommunities, and each element containing the relative abundance of types in each subcommunity relative to the metacommunity as a whole.

depth

proportion of total tree height to be conserved (taken as a proportion from the highest tip). Describes how much evolutionary history should be retained, with 0 marking the date of the most recent tip, and 1 (the default) marking the most recent common ancestor. Numbers greater than 1 extend the root of the tree.

Value

phy2branch() returns an object of class similarity.

Phylogenetic pairwise tip distance matrix

Description

Converts any phylo object to a matrix of pairwise tip-to-tip distances.

Usage

phy2dist(tree, precompute_dist = TRUE)

Arguments

tree

object of class phylo.

precompute_dist

object of class logical or numeric. When TRUE (by default) a distance matrix is generated and stored in slot distance, when FALSE no distance matrix is generated, and when numeric a distance matrix is generated until the number of species exceeds the defined value.

Value

phy2sim(x) returns an object of class distance containing a matrix of pairwise tip-to-tip distances.

Relative abundance of historical species

Description

Calculates the relative abundance of historical species.

Usage

phy_abundance(partition, structure_matrix)

Arguments

partition

structure_matrix

output$structure of phy_struct().

Calculate phylogenetic structure matrix

Description

Converts an object into class phylo into class phy_struct.

Usage

phy_struct(tree, partition)

Arguments

tree

object of class phylo

partition

Value

phy_struct() returns a list containing:

`$structure`	- each row denotes historical species, columns denote terminal taxa, and elements contain 'branch lengths'
`$tbar` - the average distance from root to tip for all terminal taxa
`$parameters`	- information associated with each historical species
`$tree`	- object of class `phylo`

Power mean of vector elements

Description

power_mean() calculates the power mean of a set of values.

Usage

power_mean(values, order = 1, weights = rep(1, length(values)))

Arguments

values

Values for which to calculate mean.

order

Order of power mean.

weights

Weights of elements, normalised to 1 inside function.

Details

Calculates the order-th power mean of a single set of non-negative values, weighted by weights; by default, weights are equal and order is 1, so this is just the arithmetic mean. Equal weights and a order of 0 gives the geometric mean, and an order of -1 gives the harmonic mean.

Value

Weighted power mean

Examples

values <- sample(1:50, 5)
power_mean(values)

powermean-class

Description

Container for class powermean.

Fields

results: data.frame containing rdiversity output
measure: object of class character naming the diversity measure being calculated
type_abundance: two-dimensional matrix of mode numeric with rows as types (species), columns as subcommunities, and each element containing the relative abundance of types in each subcommunity relative to the metacommunity as a whole. In the phylogenetic case, this corresponds to the proportional abundance of historical species, which is calculated from the proportional abundance of terminal taxa
ordinariness: two-dimensional matrix of mode numeric with rows as types, columns as subcommunities, and elements containing the ordinariness of types within subcommunities
subcommunity_weights: vector of mode numeric containing subcommunity weights
type_weights: two-dimensional matrix of mode numeric, with rows as types, columns as subcommunities, and elements containing weights of types within a subcommunity
dat_id: object of class character describing the class of distance / similarity being used, e.g. "naive", "taxonomic", and so on
similarity_components: list containing the components necessary to calculate similarity. This list is empty when precompute_dist = TRUE when calculating distance. When a pairwise distance matrix is too large and precompute_dist = FALSE, this list contains all the information required to calculate pairwise distance between types
similarity_parameters: list containing parameters associated with converting pairwise distances to similarities (the dist2sim() arguments)

Raw alpha (low level diversity component)

Description

Calculates the low-level diversity component necessary for calculating alpha diversity.

Usage

raw_alpha(meta)

Arguments

meta

object of class metacommunity

Details

Values generated from raw_alpha() may be input into subdiv() and metadiv() to calculate raw subcommunity and metacommunity alpha diversity.

Value

raw_alpha returns an object of class powermean

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate raw alpha component
a <- raw_alpha(meta)
subdiv(a, 1)
metadiv(a, 1)

Raw beta (low level diversity component)

Description

Calculates the low-level diversity component necessary for calculating raw beta diversity.

Usage

raw_beta(meta)

Arguments

meta

object of class metacommunity

Details

Values generated from raw_beta() may be input into subdiv() and metadiv() to calculate raw subcommunity and metacommunity beta diversity.

Value

raw_beta returns an object of class relativeentropy

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate raw beta component
b <- raw_beta(meta)
subdiv(b, 1)
metadiv(b, 1)

Gamma (low level diversity component)

Description

Calculates the low-level diversity component necessary for calculating gamma diversity.

Usage

raw_gamma(meta)

Arguments

meta

object of class metacommunity

Details

Values generated from raw_gamma() may be input into subdiv() and metadiv() to calculate subcommunity and metacommunity gamma diversity.

Value

raw_gamma returns an object of class powermean

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- cbind.data.frame(A = c(1, 1), B = c(2, 0), C = c(3, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate gamma component
g <- raw_gamma(meta)
subdiv(g, 1)
metadiv(g, 1)

Raw metacommunity alpha diversity

Description

Calculates similarity-sensitive raw metacommunity alpha diversity (the naive-community metacommunity diversity). This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

raw_meta_alpha(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

raw_meta_alpha returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate raw metacommunity alpha diversity
raw_meta_alpha(meta, 0:2)

Raw metacommunity beta diversity

Description

Calculates similarity-sensitive raw metacommunity beta diversity (the average distinctiveness of subcommunities). This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

raw_meta_beta(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

raw_meta_beta returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate raw metacommunity beta diversity
raw_meta_beta(meta, 0:2)

Raw metacommunity rho diversity

Description

Calculates similarity-sensitive raw metacommunity rho diversity (the average redundancy of subcommunities. This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

raw_meta_rho(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

raw_meta_rho returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate metacommunity rho diversity
raw_meta_rho(meta, 0:2)

Raw rho (low level diversity component)

Description

Calculates the low-level diversity component necessary for calculating raw rho diversity.

Usage

raw_rho(meta)

Arguments

meta

object of class metacommunity

Details

Values generated from raw_rho() may be input into subdiv() and metadiv() to calculate raw subcommunity and metacommunity rho diversity.

Value

raw_rho returns an object of class powermean

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate raw rho component
r <- raw_rho(meta)
subdiv(r, 1)
metadiv(r, 1)

Raw subcommunity alpha diversity

Description

Calculates similarity sensitive raw subcommunity alpha diversity (an estimate of naive-community metacommunity diversity). This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

raw_sub_alpha(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

raw_sub_alpha returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate raw subcommunity alpha diversity
raw_sub_alpha(meta, 0:2)

Raw subcommunity beta diversity

Description

Calculates similarity-sensitive raw subcommunity beta diversity (the distinctiveness of subcommunity j). This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

raw_sub_beta(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

raw_sub_beta returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate raw subcommunity beta diversity
raw_sub_beta(meta, 0:2)

Raw subcommunity rho diversity

Description

Calculates similarity-sensitive raw subcommunity rho diversity (the redundancy of subcommunity j. This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

raw_sub_rho(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

raw_sub_rho returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate raw subcommunity rho diversity
raw_sub_rho(meta, 0:2)

relativeentropy-class

Description

Container for class relativeentropy.

Fields

results: data.frame containing rdiversity output
measure: object of class character naming the diversity measure being calculated
type_abundance: two-dimensional matrix of mode numeric with rows as types (species), columns as subcommunities, and each element containing the relative abundance of types in each subcommunity relative to the metacommunity as a whole. In the phylogenetic case, this corresponds to the proportional abundance of historical species, which is calculated from the proportional abundance of terminal taxa
ordinariness: two-dimensional matrix of mode numeric with rows as types, columns as subcommunities, and elements containing the ordinariness of types within subcommunities
subcommunity_weights: vector of mode numeric containing subcommunity weights
type_weights: two-dimensional matrix of mode numeric, with rows as types, columns as subcommunities, and elements containing weights of types within a subcommunity
dat_id: object of class character describing the class of distance / similarity being used, e.g. "naive", "taxonomic", and so on
similarity_components: list containing the components necessary to calculate similarity. This list is empty when precompute_dist = TRUE when calculating distance. When a pairwise distance matrix is too large and precompute_dist = FALSE, this list contains all the information required to calculate pairwise distance between types
similarity_parameters: list containing parameters associated with converting pairwise distances to similarities (the dist2sim() arguments)

Repartition metacommunity

Description

Randomly reshuffles the relative abundance of types (e.g. species) in a metacommunity (whilst maintaining the relationship between the relative abundance of a particular species across subcommunities). In the case of a phylogenetic metacommunity, the relative abundance of terminal taxa are randomly reshuffled and the relative abundance of types (historical species) are calculated from the resulting partition.

Usage

repartition(meta, new_partition)

Arguments

meta

object of class metacommunity.

new_partition

two-dimensional matrix of mode numeric with rows as types (species), columns as subcommunities, and each element containing the relative abundance of types in each subcommunity relative to the metacommunity as a whole. In the phylogenetic case, this corresponds to the proportional abundance of terminal taxa. If this argument is missing, all species / tips will be shuffled

Value

repartition() returns an object of class metacommunity

Generate similarity object

Description

Container for class similarity.

Usage

similarity(similarity, dat_id)

## S4 method for signature 'matrix,character'
similarity(similarity, dat_id)

## S4 method for signature 'matrix,missing'
similarity(similarity, dat_id)

Arguments

similarity

similarity matrix

dat_id

object of class character denoting the type of diversity being calculated. This can be "naive", "genetic", "taxonomic", and so on

Value

similarity() returns an object of class similarity.

similarity-class

Description

Container for class similarity.

Usage

## S4 method for signature 'similarity'
show(object)

Arguments

object

object of class similarity

Fields

similarity: two-dimensional matrix of mode numeric with rows as types, columns as types, and elements containing the pairwise similarity of types
dat_id: object of class character describing the class of distance / similarity being used, e.g. "naive", "taxonomic", and so on
components: list containing the components necessary to calculate similarity. This list is empty when precompute_dist = TRUE when calculating distance. When a pairwise distance matrix is too large and precompute_dist = FALSE, this list contains all the information required to calculate pairwise distance between types
parameters: list containing parameters associated with converting pairwise distances to similarities (the dist2sim() arguments)

Subcommunity gamma diversity

Description

Calculates similarity-sensitive subcommunity gamma diversity (the contribution per individual toward metacommunity diversity). This measure may be calculated for a series of orders, represented as a vector of qs.

Usage

sub_gamma(meta, qs)

Arguments

meta

object of class metacommunity

qs

vector of mode numeric containing q values

Value

sub_gamma returns a standard output of class rdiv

References

R. Reeve, T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate subcommunity gamma diversity
sub_gamma(meta, 0:2)

Calculate subcommunity-level diversity

Description

Generic function for calculating subcommunity-level diversity.

Usage

subdiv(data, qs)

## S4 method for signature 'powermean'
subdiv(data, qs)

## S4 method for signature 'relativeentropy'
subdiv(data, qs)

## S4 method for signature 'metacommunity'
subdiv(data, qs)

Arguments

data

matrix of mode numeric; containing diversity components

qs

vector of mode numeric containing q values

Details

data may be input as one of three different classes:

powermean: raw or normalised metacommunity alpha, rho or gamma diversity components; will calculate subcommunity-level raw or normalised metacommunity alpha, rho or gamma diversity
relativeentropy: raw or normalised metacommunity beta diversity components; will calculate subcommunity-level raw or normalised metacommunity beta diversity
metacommunity: will calculate all subcommunity measures of diversity

Value

subdiv() returns a standard output of class rdiv

References

Reeve, R., T. Leinster, C. Cobbold, J. Thompson, N. Brummitt, S. Mitchell, and L. Matthews. 2016. How to partition diversity. arXiv 1404.6520v3:1–9.

Examples

# Define metacommunity
pop <- data.frame(a = c(1, 3), b = c(1, 1))
row.names(pop) <- paste0("sp", 1:2)
pop <- pop / sum(pop)
meta <- metacommunity(pop)

# Calculate subcommunity gamma diversity (takes the power mean)
g <- raw_gamma(meta)
subdiv(g, 0:2)

# Calculate subcommunity beta diversity (takes the relative entropy)
b <- raw_beta(meta)
subdiv(b, 0:2)

# Calculate all measures of subcommunity diversity
subdiv(meta, 0:2)

Generate taxonomic distance matrix

Description

Calculates taxonomic distances between species.

Usage

tax2dist(lookup, tax_distance, precompute_dist = TRUE)

Arguments

lookup

data.frame with colnames corresponding to nested taxonomic levels, e.g. c('Species', 'Genus', 'Family', 'Subclass')

tax_distance

vector with the distances attributed to taxonomic levels defined in lookup. The highest distance is the distance attributed to species that are not the same at any recorded taxonomic level. e.g. c(Species = 0, Genus = 1, Family = 2, Subclass = 3, Other = 4) from Shimatani.

precompute_dist

Value

tax2dist() returns an object of class distance containing a matrix of pairwise taxonomic distances

References

Shimatani, K. 2001. On the measurement of species diversity incorporating species differences. Oikos 93:135–147.

Examples

# Create Lookup table
Species <- c("tenuifolium", "asterolepis", "simplex var.grandiflora", "simplex var.ochnacea")
Genus <- c("Protium", "Quararibea", "Swartzia", "Swartzia")
Family <- c("Burseraceae", "Bombacaceae", "Fabaceae", "Fabaceae")
Subclass <- c("Sapindales", "Malvales", "Fabales", "Fabales")
lookup <- cbind.data.frame(Species, Genus, Family, Subclass)

# Assign values for each level (Shimatani's taxonomic distance)
tax_distance <- c(Species = 0, Genus = 1, Family = 2, Subclass = 3, Other = 4)

# Generate pairwise distances
distance <- tax2dist(lookup, tax_distance)
similarity <- dist2sim(distance, "linear")

Package {rdiversity}

rdiversity: diversity measurement in R

Description

Details

Author(s)

References

See Also

Function to cut the phylogeny to a specified depth from the tip with the greatest distance from the root.

Description

Usage

Arguments

Value

Distance to similarity

Description

Usage

Arguments

Details

Value

Generate distance object

Description

Usage

Arguments

Value

distance-class

Description

Usage

Arguments

Fields

Genetic distance matrix

Description

Usage

Arguments

Value

Calculate individual-level diversity

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Metacommunity gamma diversity

Description

Usage

Arguments

Value

References

Examples

Metacommunity

Description

Usage

Arguments

Value

Fields

See Also

Examples

metacommunity-class

Description

Usage

Arguments

Fields

Metacommunity-level diversity

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Normalised alpha (low level diversity component)

Description

Usage

Arguments

Details

Value

References

Examples

Normalised beta (low level diversity component)