Package 'fundiversity'

Title: Easy Computation of Functional Diversity Indices
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 (Grenié & Gruson 2023 <doi:10.1111/ecog.06585>).
Authors: Matthias Grenié [aut, cre] , Hugo Gruson [aut]
Maintainer: Matthias Grenié <[email protected]>
License: GPL-3
Version: 1.1.1
Built: 2024-09-13 04:39:58 UTC
Source: https://github.com/funecology/fundiversity

Help Index


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:

  • site the names of the sites as the row names of the input sp_com,

  • FDis the values of functional dispersion at each site.

If the sp_com argument is not provided or if sp_com doesn't have rownames, arbitrary rownames s1, s2, s3, etc. will be used.

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 (their results are cached to avoid recomputing the same functional volume twice). 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. By changing the option, the behavior will automatically change the next time you run the function. Note: memoisation is only available when the memoise package has been installed and without parallelization, otherwise fundiversity will use unmemoised versions of the functions. In other words, memoization and parallelization are mutually exclusive.

Value

a data.frame with two columns:

  • site the names of the sites as the row names of the input sp_com,

  • FDiv the values of functional divergence at each site.

If the sp_com argument is not provided or if sp_com doesn't have rownames, arbitrary rownames s1, s2, s3, etc. will be used.

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:

  • site character column that contains site names based on input sp_com row names,

  • FEve numeric column that contains FEve values corresponding to each site.

If the sp_com argument is not provided or if sp_com doesn't have rownames, arbitrary rownames s1, s2, s3, etc. will be used.

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 (their results are cached to avoid recomputing the same functional volume twice). 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. By changing the option, the behavior will automatically change the next time you run the function. Note: memoisation is only available when the memoise package has been installed and without parallelization, otherwise fundiversity will use unmemoised versions of the functions. In other words, memoization and parallelization are mutually exclusive.

Value

a data.frame with two columns:

  • site the names of the sites as the row names of the input sp_com,

  • FRic the values of functional richness at each site.

If the sp_com argument is not provided or if sp_com doesn't have rownames, arbitrary rownames s1, s2, s3, etc. will be used.

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 (their results are cached to avoid recomputing the same functional volume twice). 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. By changing the option, the behavior will automatically change the next time you run the function. Note: memoisation is only available when the memoise package has been installed and without parallelization, otherwise fundiversity will use unmemoised versions of the functions. In other words, memoization and parallelization are mutually exclusive.

Value

a data.frame with three columns:

  • first_site the names of the first site used in the pair sp_com,

  • second_site the names of the first site used in the pair,

  • FRic_intersect the volume of the convex hulls intersection of each pair of site.

If the sp_com argument is not provided or if sp_com doesn't have rownames, arbitrary rownames s1, s2, s3, etc. will be used.

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

References

Villéger S., Grenouillet G., Brosse S. (2013), Decomposing functional β\beta-diversity reveals that low functional β\beta-diversity is driven by low functional turnover in European fish assemblages, Global Ecology and Biogeography, 22(6), 671–681. doi:10.1111/geb.12021.

Zhao T., Villéger S., Cucherousset J. (2019). Accounting for intraspecific diversity when examining relationships between non-native species and functional diversity. Oecologia, 189(1), 171-183. doi:10.1007/s00442-018-4311-3.

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:

  • site the names of the sites as the row names of the input sp_com,

  • Q the values of Rao's quadratic entropy at each site.

If the sp_com argument is not provided or if sp_com doesn't have rownames, arbitrary rownames s1, s2, s3, etc. will be used.

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)

Options for fundiversity

Description

The memoisation is the convex hull computation in fundiversity is controlled via the fundiversity.memoise option:

  • if unset, the default is to use memoisation if memoise was installed when fundiversity was loaded, and not to use memoisation otherwise.

  • if options(fundiversity.memoise = TRUE), memoisation is used and an error is thrown if memoise is not installed.

  • if options(fundiversity.memoise = FALSE), memoisation is not used.


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