Title: Easy Computation of Functional Diversity Indices
Version: 1.1.1
Description: Computes six functional diversity indices. These are namely, Functional Divergence (FDiv), Function Evenness (FEve), Functional Richness (FRic), Functional Richness intersections (FRic_intersect), Functional Dispersion (FDis), and Rao's entropy (Q) (reviewed in Villéger et al. 2008 <doi:10.1890/07-1206.1>). Provides efficient, modular, and parallel functions to compute functional diversity indices (preprint: <doi:10.32942/osf.io/dg7hw>).
License: GPL-3
Language: en
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.2.2
Depends: R (≥ 2.10)
Imports: future.apply, geometry, Matrix, vegan
Suggests: future, knitr, memoise, rmarkdown, testthat (≥ 3.0.0)
URL: https://funecology.github.io/fundiversity/, https://github.com/funecology/fundiversity
BugReports: https://github.com/funecology/fundiversity/issues
Config/testthat/edition: 3
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2022-11-21 13:08:00 UTC; ke76dimu
Author: Matthias Grenié ORCID iD [aut, cre], Hugo Gruson ORCID iD [aut]
Maintainer: Matthias Grenié <matthias.grenie@gmail.com>
Repository: CRAN
Date/Publication: 2022-11-21 13:30:02 UTC

fundiversity: Easy Computation of Functional Diversity Indices

Description

logo

Computes six functional diversity indices. These are namely, Functional Divergence (FDiv), Function Evenness (FEve), Functional Richness (FRic), Functional Richness intersections (FRic_intersect), Functional Dispersion (FDis), and Rao's entropy (Q) (reviewed in Villéger et al. 2008 doi:10.1890/07-1206.1). Provides efficient, modular, and parallel functions to compute functional diversity indices (preprint: doi:10.32942/osf.io/dg7hw).

Author(s)

Maintainer: Matthias Grenié matthias.grenie@gmail.com (ORCID)

Authors:

See Also

Useful links:

Compute Functional Dispersion (FDis)

Description

This function computes Functional Dispersion (FDis) following Laliberté & Legendre (2010). NB: when a site contains no species FDis is equal to 0.

Usage

fd_fdis(traits, sp_com)

Arguments

traits

Trait matrix with species as rows and traits as columns. It has to contain exclusively numerical values. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

sp_com

Site-species matrix with sites as rows and species as columns if not provided, the function considers all species with equal abundance in a single site. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

Value

a data.frame with two columns:

NB: when a site contains no species FDis is equal to 0.

Parallelization

The computation of this function can be parallelized thanks to future::plan(). To get more information on how to parallelize your computation please refer to the parallelization vignette with: vignette("fundiversity_1-parallel", package = "fundiversity")

References

Laliberté, E., & Legendre, P. (2010). A distance-based framework for measuring functional diversity from multiple traits. Ecology, 91(1), 299–305. doi:10.1890/08-2244.1

Examples

data(traits_birds)
data(site_sp_birds)
fd_fdis(traits_birds, site_sp_birds)

Compute Functional Divergence (FDiv)

Description

This function computes Functional Divergence (FDiv) following Villéger et al. (2008). NB: when a site contains no species FDiv is equal to 0. If for a site there are less traits than species, then FDiv is equal to NaN.

Usage

fd_fdiv(traits, sp_com)

Arguments

traits

Trait matrix with species as rows and traits as columns. It has to contain exclusively numerical values. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

sp_com

Site-species matrix with sites as rows and species as columns if not provided, the function considers all species with equal abundance in a single site. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

Details

By default, when loading fundiversity, the functions to compute convex hulls are memoised through the memoise package if it is installed. To deactivate this behavior you can set the option fundiversity.memoise to FALSE by running the following line: options(fundiversity.memoise = FALSE). If you use it interactively it will only affect your current session. Add it to your script(s) or .Rprofile file to avoid toggling it each time.

Value

a data.frame with two columns:

NB: when a site contains no species FDiv is equal to 0. If for a site there are less traits than species, then FDiv is equal to NaN.

Parallelization

The computation of this function can be parallelized thanks to future::plan(). To get more information on how to parallelize your computation please refer to the parallelization vignette with: vignette("fundiversity_1-parallel", package = "fundiversity")

References

Villéger S., Mason N. W. H., Mouillot D. (2008), New multidimensional functional diversity indices for a multifaceted framework in functional ecology, Ecology 89(8), doi:10.1890/07-1206.1

Examples

data(traits_birds)
fd_fdiv(traits_birds)

Compute Functional Evenness (FEve)

Description

This function computes Functional Evenness (FEve) following Villéger et al. (2008). NB: By definition FEve is equal to NA when the number of species per site is strictly lower than 3.

Usage

fd_feve(traits = NULL, sp_com, dist_matrix = NULL)

Arguments

traits

Trait matrix with species as rows and traits as columns. It has to contain exclusively numerical values. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

sp_com

Site-species matrix with sites as rows and species as columns if not provided, the function considers all species with equal abundance in a single site. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

dist_matrix

A dissimilarity matrix that can be provided instead of a trait data.frame (default: NULL). This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

Value

a data.frame with two columns:

NB: By definition FEve is equal to NA when the number of species per site is strictly lower than 3.

Parallelization

The computation of this function can be parallelized thanks to future::plan(). To get more information on how to parallelize your computation please refer to the parallelization vignette with: vignette("fundiversity_1-parallel", package = "fundiversity")

References

Villéger, S., Mason, N.W.H., Mouillot, D., 2008. New Multidimensional Functional Diversity Indices for a Multifaceted Framework in Functional Ecology. Ecology 89, 2290–2301. doi:10.1890/07-1206.1

Examples

data(traits_birds)
fd_feve(traits_birds)

Compute Functional Richness (FRic)

Description

Functional Richness is computed as the volume of the convex hull from all included traits following Villéger et al. (2008). NB: FRic is equal to NA when there are strictly less species in a site than the number of provided traits.

Usage

fd_fric(traits, sp_com, stand = FALSE)

Arguments

traits

Trait matrix with species as rows and traits as columns. It has to contain exclusively numerical values. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

sp_com

Site-species matrix with sites as rows and species as columns if not provided, the function considers all species with equal abundance in a single site. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

stand

a boolean indicating whether to standardize FRic values over the observed maximum over all species (default: FALSE). This scales FRic between 0 and 1. NB: The maximum FRic values only considers species that are present in both site-species and trait matrices. If you want to consider species that are absent in the site-species matrix, add corresponding columns of 0s.

Details

By default, when loading fundiversity, the functions to compute convex hulls are memoised through the memoise package if it is installed. To deactivate this behavior you can set the option fundiversity.memoise to FALSE by running the following line: options(fundiversity.memoise = FALSE). If you use it interactively it will only affect your current session. Add it to your script(s) or .Rprofile file to avoid toggling it each time.

Value

a data.frame with two columns:

NB: FRic is equal to NA when there are strictly less species in a site than the number of provided traits. Note that only species with strictly different trait combinations are considered unique, species that share the exact same trait values across all traits are considered as one species.

Parallelization

The computation of this function can be parallelized thanks to future::plan(). To get more information on how to parallelize your computation please refer to the parallelization vignette with: vignette("fundiversity_1-parallel", package = "fundiversity")

References

Cornwell W. K., Schwilk D. W., Ackerly D. D. (2006), A trait-based test for habitat filtering; convex hull volume, Ecology 84(6), doi:10.1890/0012-9658(2006)87[1465:ATTFHF]2.0.CO;2

Examples

data(traits_birds)
fd_fric(traits_birds)

Intersection between convex hulls of pairs of sites

Description

Compute volume of the intersection of the convex hulls of all pairs of sites (including self-intersection, which corresponds to their convex hull). Note that when standardizing convex hulls of intersections, this function uses the convex hull of all provided traits, thus standardized volume of self-intersection hulls can be lower than one. NB: FRic_intersect is equal to NA when there are strictly less species in one of the sites than the number of provided traits.

Usage

fd_fric_intersect(traits, sp_com, stand = FALSE)

Arguments

traits

Trait matrix with species as rows and traits as columns. It has to contain exclusively numerical values. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

sp_com

Site-species matrix with sites as rows and species as columns if not provided, the function considers all species with equal abundance in a single site. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

stand

a boolean indicating whether to standardize FRic values over the observed maximum over all species (default: FALSE). This scales FRic between 0 and 1. NB: The maximum FRic values only considers species that are present in both site-species and trait matrices. If you want to consider species that are absent in the site-species matrix, add corresponding columns of 0s.

Details

By default, when loading fundiversity, the functions to compute convex hulls are memoised through the memoise package if it is installed. To deactivate this behavior you can set the option fundiversity.memoise to FALSE by running the following line: options(fundiversity.memoise = FALSE). If you use it interactively it will only affect your current session. Add it to your script(s) or .Rprofile file to avoid toggling it each time.

Value

a data.frame with three columns:

NB: FRic_intersect is equal to NA when there are strictly less species in one of the sites than the number of provided traits. Note that only species with strictly different trait combinations are considered unique, species that share the exact same trait values across all traits are considered as one species.

Parallelization

The computation of this function can be parallelized thanks to future::plan(). To get more information on how to parallelize your computation please refer to the parallelization vignette with: vignette("fundiversity_1-parallel", package = "fundiversity")

See Also

fd_fric(), geometry::intersectn(), geometry::convhulln()

Examples

data(traits_birds)
fd_fric_intersect(traits_birds)

Compute Rao's entropy index (Rao's Q)

Description

This function computes Rao's Quadratic Entropy following Rao (1982). NB: Rao's quadratic entropy is 0 when there are no species in the site.

Usage

fd_raoq(traits = NULL, sp_com, dist_matrix = NULL)

Arguments

traits

Trait matrix with species as rows and traits as columns. It has to contain exclusively numerical values. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

sp_com

Site-species matrix with sites as rows and species as columns if not provided, the function considers all species with equal abundance in a single site. This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

dist_matrix

A dissimilarity matrix that can be provided instead of a trait data.frame (default: NULL). This can be either a matrix, a data.frame, or a Matrix::Matrix() object.

Value

a data.frame with two columns:

NB: Rao's quadratic entropy is 0 when there are no species in the site.

References

Pavoine S., Dolédec S. (2005). The apportionment of quadratic entropy: a useful alternative for partitioning diversity in ecological data. Environmental and Ecological Statistics, 12(2), 125–138. doi:10.1007/s10651-005-1037-2

Examples

data(traits_birds)
fd_raoq(traits_birds)

Site-species matrix of birds along a Tropical Gradient

Description

Presences and absences of birds at different elevations along a tropical gradient. Species names are indicated as column names.

Usage

site_sp_birds

Format

A matrix with 217 columns (1 per species) and 8 rows:

elev_250

is species present at 250 m elevation? 0=No, 1=Yes

elev_500

is species present at 500 m elevation? 0=No, 1=Yes

elev_1000

is species present at 1000 m elevation? 0=No, 1=Yes

elev_1500

is species present at 1500 m elevation? 0=No, 1=Yes

elev_2000

is species present at 2000 m elevation? 0=No, 1=Yes

elev_2500

is species present at 2500 m elevation? 0=No, 1=Yes

elev_3000

is species present at 3000 m elevation? 0=No, 1=Yes

elev_3500

is species present at 3500 m elevation? 0=No, 1=Yes

Source

Nowak, Larissa et al. (2019), Data from: Projecting consequences of global warming for the functional diversity of fleshy-fruited plants and frugivorous birds along a tropical elevational gradient, Dryad, Dataset, doi:10.5061/dryad.c0n737b

Site-species matrix of plants along a Tropical Gradient

Description

Presences and absences of plants at different elevations along a tropical gradient. Species names are indicated as column names.

Usage

site_sp_plants

Format

A matrix with 392 columns (1 per species) and 10 rows:

elev_250

is species present at 250 m elevation? 0=No, 1=Yes

elev_500

is species present at 500 m elevation? 0=No, 1=Yes

elev_1000

is species present at 1000 m elevation? 0=No, 1=Yes

elev_1500

is species present at 1500 m elevation? 0=No, 1=Yes

elev_2000

is species present at 2000 m elevation? 0=No, 1=Yes

elev_2500

is species present at 2500 m elevation? 0=No, 1=Yes

elev_3000

is species present at 3000 m elevation? 0=No, 1=Yes

elev_3500

is species present at 3500 m elevation? 0=No, 1=Yes

elev_3750

is species present at 3750 m elevation? 0=No, 1=Yes

elev_4000

is species present at 4000 m elevation? 0=No, 1=Yes

Source

Nowak, Larissa et al. (2019), Data from: Projecting consequences of global warming for the functional diversity of fleshy-fruited plants and frugivorous birds along a tropical elevational gradient, Dryad, Dataset, doi:10.5061/dryad.c0n737b

Functional Traits of Frugivorous Birds along a Tropical Gradient

Description

A dataset containing some functional traits of frugivorous birds in the Manú biosphere reserve, southeast Peru. Given are species mean trait values. The row names of the dataset give species names. Morphological traits have been measured on museum specimen following Eck et al.(2011). Traits have been measured only for adult and, if possible, for a minimum of two female and two male specimens. Body mass was taken from Dunning et al. (2007).

Usage

traits_birds

Format

A data frame with 217 rows and 4 variables:

Bill.width..mm.

bill width, in mm

Bill.length..mm.

bill length, in mm

Kipp.s.index

Kipp's index indicating wing Pointedness

Bodymass..g.

adult's bodymass, in g

Source

Nowak, Larissa et al. (2019), Data from: Projecting consequences of global warming for the functional diversity of fleshy-fruited plants and frugivorous birds along a tropical elevational gradient, Dryad, Dataset, doi:10.5061/dryad.c0n737b

Functional Traits of Fleshy-fruit plants along a Tropical Gradient

Description

Taxonomy and functional traits of 392 fleshy-fruited plant species from the Manu National Park in south-east Peru. Given are fruit length and width (mm), plant height (m) and crop mass (g). Fruit traits have been measured on fresh fruit samples. Number of fruits per plant (used to determine the crop mass) and plant height have been estimated in the field. Species names are indicated as row names.

Usage

traits_plants

Format

A data frame with 392 rows and 4 variables:

Fruit.length..mm.

fruit length, in mm

Fruit.width..mm.

fruit width, in mm

Plant.height..m.

plant height, in m

Crop.mass..g.

seed mass, in g

Source

Nowak, Larissa et al. (2019), Data from: Projecting consequences of global warming for the functional diversity of fleshy-fruited plants and frugivorous birds along a tropical elevational gradient, Dryad, Dataset, doi:10.5061/dryad.c0n737b