fundiversity

📦 R package to compute functional diversity indices efficiently

https://github.com/funecology/fundiversity

Keywords

Repository

📦 R package to compute functional diversity indices efficiently

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

temp_dir = tempdir(check = TRUE)

pkg_has_vignettes_and_test = function(pkg_name, pkg_dir = temp_dir) {
  pkg_archive = download.packages(pkg_name, destdir = pkg_dir,
                                  repos = "https://cran.r-project.org")
  
  files_list = untar(pkg_archive[1, 2], list = TRUE)
  
  has_vignette = paste0(pkg_archive[1, 1], "/vignettes/") %in% files_list

  has_tests = paste0(pkg_archive[1, 1], "/tests/") %in% files_list

  c(ifelse(has_vignette, "✅", "❌"), ifelse(has_tests, "✅", "❌"))
}
```

# fundiversity 


[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![R build status](https://github.com/funecology/fundiversity/workflows/R-CMD-check/badge.svg)](https://github.com/funecology/fundiversity/actions)
[![Coverage Status](https://codecov.io/gh/funecology/fundiversity/branch/main/graph/badge.svg?token=HR4YH118VT)](https://app.codecov.io/gh/funecology/fundiversity)
[![CRAN status](https://www.r-pkg.org/badges/version-ago/fundiversity)](https://CRAN.R-project.org/package=fundiversity)
[![DOI](https://zenodo.org/badge/300231216.svg)](https://zenodo.org/badge/latestdoi/300231216)


`fundiversity` provides a lightweight package to compute common functional
diversity indices. To a get a glimpse of what `fundiversity` can do refer to the
[introductory vignette](https://funecology.github.io/fundiversity/articles/fundiversity.html).
The package is built using clear, public 
[design principles](https://funecology.github.io/fundiversity/articles/fundiversity_4-design-principles.html)
inspired from our own experience and user feedback.


## Installation

You can install the stable version from CRAN with:

```{r, eval = FALSE}
install.packages("fundiversity")
```

Alternatively, you can install the development version with:

```{r eval = FALSE}
install.packages("fundiversity", repos = "https://bisaloo.r-universe.dev")
```


## Examples

`fundiversity` lets you compute six functional diversity indices: Functional Richness with `fd_fric()`, intersection with between convex hulls with `fd_fric_intersect()`, Functional Divergence with
`fd_fdiv()`, Rao's Quadratic Entropy with `fd_raoq()`, Functional Dispersion with `fd_fdis()` and Functional Evenness with `fd_feve()`. You can have a brief overview of the indices in the [introductory vignette](https://funecology.github.io/fundiversity/articles/fundiversity.html).

All indices can be computed either using global trait data or at the site-level:

```{r example}
library("fundiversity")

# If only the trait dataset is specified, considers all species together
# by default
fd_fric(traits_birds)

# We can also compute diversity across sites
fd_fric(traits_birds, site_sp_birds)
```

To compute Rao's Quadratic Entropy, the user can also provide a distance matrix between species directly:

```{r rao-distance-matrix}
dist_traits_birds = as.matrix(dist(traits_birds))

fd_raoq(traits = NULL, dist_matrix = dist_traits_birds)
```

## Function Summary

```{r child="man/rmdchunks/_fundiversity_functions.Rmd"}
```

## Parallelization

Thanks to the `future.apply` package, all functions (except `fd_raoq()`) within `fundiversity` support parallelization through the `future` backend. To toggle parallelization follow the [`future` syntax](https://cran.r-project.org/package=future):

```{r future-syntax, render=FALSE}
future::plan(future::multisession)
fd_fdiv(traits_birds)
```

For more details please refer to the [parallelization vignette](https://funecology.github.io/fundiversity/articles/fundiversity_1-parallel.html) or use `vignette("fundiversity_1-parallel", package = "fundiversity")` within R. **Note**: parallelization and memoization are **mutually exclusive**, when doing computation in parallel, fundiversity falls back on **unmemoised** versions of function.


## Available functional diversity indices

According to Pavoine & Bonsall (2011) classification, functional diversity indices can be classified in three "domains" that assess different properties of the functional space: richness, divergence, and regularity. We made sure that the computations in the package are correct in our [correctness vignette](https://funecology.github.io/fundiversity/articles/fundiversity_3-correctness.html).
`fundiversity` provides function to compute indices that assess this three facets at the site scale:

|               Scale                |                                      Richness                                                                                                                              |                   Divergence                                                                                                                                                                                                                                                       |        Evenness                                                                        |
|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| α-diversity
(= among sites)   | FRic with [`fd_fric()`](https://funecology.github.io/fundiversity/reference/fd_fric.html)                                                                                     | FDiv with [`fd_fdiv()`](https://funecology.github.io/fundiversity/reference/fd_fdiv.html)
Rao's QE with [`fd_raoq()`](https://funecology.github.io/fundiversity/reference/fd_raoq.html)
FDis with [`fd_fdis()`](https://funecology.github.io/fundiversity/reference/fd_fdis.html) | FEve with [`fd_feve()`](https://funecology.github.io/fundiversity/reference/fd_feve.html) |
| β-diversity
(= between sites) | FRic pairwise intersection with [`fd_fric_intersect()`](https://funecology.github.io/fundiversity/reference/fd_fric_intersect.html)
alternatives available in `betapart` | available in `entropart`, `betapart` or `hillR`                                                                                                                                                                                                                                    | available in `BAT`    |
 
## Related Packages

```{r pkg-vign-tests, include = FALSE}
adiv        = pkg_has_vignettes_and_test("adiv")
bat         = pkg_has_vignettes_and_test("BAT")
betapart    = pkg_has_vignettes_and_test("betapart")
entropart   = pkg_has_vignettes_and_test("entropart")
fd          = pkg_has_vignettes_and_test("FD")
hilldiv     = pkg_has_vignettes_and_test("hilldiv")
hillr       = pkg_has_vignettes_and_test("hillR")
hypervolume = pkg_has_vignettes_and_test("hypervolume")
tpd         = pkg_has_vignettes_and_test("TPD")
vegan       = pkg_has_vignettes_and_test("vegan")
```

Several other packages exist that compute functional diversity indices. We did a [performance comparison](https://funecology.github.io/fundiversity/articles/fundiversity_2-performance.html) between related packages. We here mention some of them (but do not mention the numerous wrappers around these packages): 

| Package Name                                          |                     Indices included                                                                                |    Has vignettes   |      Has tests     | On GitHub | On CRAN (last updated)                                    |
|-------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------|--------------------|-----------|-----------------------------------------------------------|
| [`adiv`](https://github.com/cran/adiv)                | Functional Entropy, Functional Redundancy                                                                           |`r adiv[[1]]`       |`r adiv[[2]]`       | ❌       | ![](https://www.r-pkg.org/badges/last-release/adiv)       |
| [`BAT`](https://github.com/cardosopmb/BAT)            | β-diversity indices, Richness, divergence, and evenness with hypervolumes                                           |`r bat[[1]]`        |`r bat[[2]]`        | ✅        | ![](https://www.r-pkg.org/badges/last-release/BAT)        |  
| [`betapart`](https://github.com/cran/betapart)        | Functional β-diversity                                                                                              |`r betapart[[1]]`   |`r betapart[[2]]`   | ❌       | ![](https://www.r-pkg.org/badges/last-release/betapart)   |
| [`entropart`](https://github.com/EricMarcon/entropart)| Functional Entropy                                                                                                  |`r entropart[[1]]`  |`r entropart[[2]]`  | ✅        | ![](https://www.r-pkg.org/badges/last-release/entropart)  |  
| [`FD`](https://github.com/cran/FD)                    | FRic, FDiv, FDis, FEve, Rao's QE, Functional Group Richness                                                         |`r fd[[1]]`         |`r fd[[2]]`         | ❌       | ![](https://www.r-pkg.org/badges/last-release/FD)         |
| [`hilldiv`](https://github.com/anttonalberdi/hilldiv) | Dendrogram-based Hill numbers for functional diversity                                                              |`r hilldiv[[1]]`    |`r hilldiv[[2]]`    | ✅       | ![](https://www.r-pkg.org/badges/last-release/hilldiv)    | 
| [`hillR`](https://github.com/daijiang/hillR)          | Functional Diversity Hill Numbers                                                                                   |`r hillr[[1]]`      |`r hillr[[2]]`      | ✅        | ![](https://www.r-pkg.org/badges/last-release/hillR)      |    
| [`hypervolume`](https://github.com/cran/hypervolume)  | Hypervolume measure of functional diversity (~FRic)                                                                 |`r hypervolume[[1]]`|`r hypervolume[[2]]`| ✅        | ![](https://www.r-pkg.org/badges/last-release/hypervolume)|
| [`mFD`](https://github.com/CmlMagneville/mFD)         | Functional α- and β-diversity indices, including FRic, FDiv, FDis, FEve, FIde, FMPD, FNND, FOri, FSpe, Hill Numbers | ✅                 | ❌                | ✅          | ![](https://www.r-pkg.org/badges/last-release/mFD)     |
| [`TPD`](https://github.com/cran/TPD)                  | FRic, FDiv, FEve but for probability distributions                                                                  |`r tpd[[1]]`        |`r tpd[[2]]`        | ❌       | ![](https://www.r-pkg.org/badges/last-release/TPD)        |
| [`vegan`](https://github.com/vegandevs/vegan)         | Only dendrogram-based FD (`treedive()`)                                                                             |`r vegan[[1]]`      |`r vegan[[2]]`      | ✅        | ![](https://www.r-pkg.org/badges/last-release/vegan)      |                 

---

Owner

Citation (CITATION.cff)

# --------------------------------------------
# CITATION file created with {cffr} R package
# See also: https://docs.ropensci.org/cffr/
# --------------------------------------------
 
cff-version: 1.2.0
message: 'To cite package "fundiversity" in publications use:'
type: software
license: GPL-3.0-only
title: 'fundiversity: Easy Computation of Functional Diversity Indices'
version: 1.1.1
doi: 10.5281/zenodo.4761754
identifiers:
- type: doi
  value: 10.32614/CRAN.package.fundiversity
abstract: 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 <https://doi.org/10.1890/07-1206.1>).
  Provides efficient, modular, and parallel functions to compute functional diversity
  indices (Grenié & Gruson 2023 <https://doi.org/10.1111/ecog.06585>).
authors:
- family-names: Grenié
  given-names: Matthias
  email: matthias.grenie@gmail.com
  orcid: https://orcid.org/0000-0002-4659-7522
- family-names: Gruson
  given-names: Hugo
  orcid: https://orcid.org/0000-0002-4094-1476
preferred-citation:
  type: manual
  title: 'fundiversity: Easy Computation of Functional Diversity Indices'
  authors:
  - family-names: Grenié
    given-names: Matthias
    email: matthias.grenie@gmail.com
    orcid: https://orcid.org/0000-0002-4659-7522
  - family-names: Gruson
    given-names: Hugo
    orcid: https://orcid.org/0000-0002-4094-1476
  year: '2025'
  notes: R package version 1.1.1
  url: https://CRAN.R-project.org/package=fundiversity
  doi: 10.5281/zenodo.4761754
repository: https://CRAN.R-project.org/package=fundiversity
repository-code: https://github.com/funecology/fundiversity
url: https://funecology.github.io/fundiversity/
contact:
- family-names: Grenié
  given-names: Matthias
  email: matthias.grenie@gmail.com
  orcid: https://orcid.org/0000-0002-4659-7522
keywords:
- biodiversity
- biodiversity-indicators
- biodiversity-informatics
- functional-diversity
- functional-ecology
- functional-trait
- functional-traits
- r
- r-package
- trait
- trait-based
- traits
references:
- type: article
  title: 'fundiversity: a modular R package to compute functional diversity indices'
  authors:
  - family-names: Grenié
    given-names: Matthias
  - family-names: Gruson
    given-names: Hugo
  journal: Ecography
  year: '2023'
  doi: 10.1111/ecog.06585
  volume: '2023'
  issue: '3'
  start: e06585
- type: software
  title: 'R: A Language and Environment for Statistical Computing'
  notes: Depends
  url: https://www.R-project.org/
  authors:
  - name: R Core Team
  institution:
    name: R Foundation for Statistical Computing
    address: Vienna, Austria
  year: '2025'
  version: '>= 3.2.0'
- type: software
  title: future.apply
  abstract: 'future.apply: Apply Function to Elements in Parallel using Futures'
  notes: Imports
  url: https://future.apply.futureverse.org
  repository: https://CRAN.R-project.org/package=future.apply
  authors:
  - family-names: Bengtsson
    given-names: Henrik
    email: henrikb@braju.com
    orcid: https://orcid.org/0000-0002-7579-5165
  year: '2025'
  doi: 10.32614/CRAN.package.future.apply
- type: software
  title: geometry
  abstract: 'geometry: Mesh Generation and Surface Tessellation'
  notes: Imports
  url: https://davidcsterratt.github.io/geometry/
  repository: https://CRAN.R-project.org/package=geometry
  authors:
  - family-names: Habel
    given-names: Kai
  - family-names: Grasman
    given-names: Raoul
  - family-names: Gramacy
    given-names: Robert B.
  - family-names: Mozharovskyi
    given-names: Pavlo
  - family-names: Sterratt
    given-names: David C.
    email: david.c.sterratt@ed.ac.uk
    orcid: https://orcid.org/0000-0001-9092-9099
  year: '2025'
  doi: 10.32614/CRAN.package.geometry
- type: software
  title: Matrix
  abstract: 'Matrix: Sparse and Dense Matrix Classes and Methods'
  notes: Imports
  url: https://Matrix.R-forge.R-project.org
  repository: https://CRAN.R-project.org/package=Matrix
  authors:
  - family-names: Bates
    given-names: Douglas
    orcid: https://orcid.org/0000-0001-8316-9503
  - family-names: Maechler
    given-names: Martin
    email: mmaechler+Matrix@gmail.com
    orcid: https://orcid.org/0000-0002-8685-9910
  - family-names: Jagan
    given-names: Mikael
    orcid: https://orcid.org/0000-0002-3542-2938
  year: '2025'
  doi: 10.32614/CRAN.package.Matrix
- type: software
  title: vegan
  abstract: 'vegan: Community Ecology Package'
  notes: Imports
  url: https://vegandevs.github.io/vegan/
  repository: https://CRAN.R-project.org/package=vegan
  authors:
  - family-names: Oksanen
    given-names: Jari
    email: jhoksane@gmail.com
  - family-names: Simpson
    given-names: Gavin L.
    email: ucfagls@gmail.com
  - family-names: Blanchet
    given-names: F. Guillaume
  - family-names: Kindt
    given-names: Roeland
  - family-names: Legendre
    given-names: Pierre
  - family-names: Minchin
    given-names: Peter R.
  - family-names: O'Hara
    given-names: R.B.
  - family-names: Solymos
    given-names: Peter
  - family-names: Stevens
    given-names: M. Henry H.
  - family-names: Szoecs
    given-names: Eduard
  - family-names: Wagner
    given-names: Helene
  - family-names: Barbour
    given-names: Matt
  - family-names: Bedward
    given-names: Michael
  - family-names: Bolker
    given-names: Ben
  - family-names: Borcard
    given-names: Daniel
  - family-names: Borman
    given-names: Tuomas
  - family-names: Carvalho
    given-names: Gustavo
  - family-names: Chirico
    given-names: Michael
  - family-names: De Caceres
    given-names: Miquel
  - family-names: Durand
    given-names: Sebastien
  - family-names: Evangelista
    given-names: Heloisa Beatriz Antoniazi
  - family-names: FitzJohn
    given-names: Rich
  - family-names: Friendly
    given-names: Michael
  - family-names: Furneaux
    given-names: Brendan
  - family-names: Hannigan
    given-names: Geoffrey
  - family-names: Hill
    given-names: Mark O.
  - family-names: Lahti
    given-names: Leo
  - family-names: Martino
    given-names: Cameron
  - family-names: McGlinn
    given-names: Dan
  - family-names: Ouellette
    given-names: Marie-Helene
  - family-names: Ribeiro Cunha
    given-names: Eduardo
  - family-names: Smith
    given-names: Tyler
  - family-names: Stier
    given-names: Adrian
  - family-names: Ter Braak
    given-names: Cajo J.F.
  - family-names: Weedon
    given-names: James
  year: '2025'
  doi: 10.32614/CRAN.package.vegan
- type: software
  title: future
  abstract: 'future: Unified Parallel and Distributed Processing in R for Everyone'
  notes: Suggests
  url: https://future.futureverse.org
  repository: https://CRAN.R-project.org/package=future
  authors:
  - family-names: Bengtsson
    given-names: Henrik
    email: henrikb@braju.com
    orcid: https://orcid.org/0000-0002-7579-5165
  year: '2025'
  doi: 10.32614/CRAN.package.future
- type: software
  title: knitr
  abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R'
  notes: Suggests
  url: https://yihui.org/knitr/
  repository: https://CRAN.R-project.org/package=knitr
  authors:
  - family-names: Xie
    given-names: Yihui
    email: xie@yihui.name
    orcid: https://orcid.org/0000-0003-0645-5666
  year: '2025'
  doi: 10.32614/CRAN.package.knitr
- type: software
  title: memoise
  abstract: 'memoise: ''Memoisation'' of Functions'
  notes: Suggests
  url: https://memoise.r-lib.org
  repository: https://CRAN.R-project.org/package=memoise
  authors:
  - family-names: Wickham
    given-names: Hadley
    email: hadley@rstudio.com
  - family-names: Hester
    given-names: Jim
  - family-names: Chang
    given-names: Winston
    email: winston@rstudio.com
  - family-names: Müller
    given-names: Kirill
    email: krlmlr+r@mailbox.org
  - family-names: Cook
    given-names: Daniel
    email: danielecook@gmail.com
  year: '2025'
  doi: 10.32614/CRAN.package.memoise
- type: software
  title: rmarkdown
  abstract: 'rmarkdown: Dynamic Documents for R'
  notes: Suggests
  url: https://pkgs.rstudio.com/rmarkdown/
  repository: https://CRAN.R-project.org/package=rmarkdown
  authors:
  - family-names: Allaire
    given-names: JJ
    email: jj@posit.co
  - family-names: Xie
    given-names: Yihui
    email: xie@yihui.name
    orcid: https://orcid.org/0000-0003-0645-5666
  - family-names: Dervieux
    given-names: Christophe
    email: cderv@posit.co
    orcid: https://orcid.org/0000-0003-4474-2498
  - family-names: McPherson
    given-names: Jonathan
    email: jonathan@posit.co
  - family-names: Luraschi
    given-names: Javier
  - family-names: Ushey
    given-names: Kevin
    email: kevin@posit.co
  - family-names: Atkins
    given-names: Aron
    email: aron@posit.co
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
  - family-names: Cheng
    given-names: Joe
    email: joe@posit.co
  - family-names: Chang
    given-names: Winston
    email: winston@posit.co
  - family-names: Iannone
    given-names: Richard
    email: rich@posit.co
    orcid: https://orcid.org/0000-0003-3925-190X
  year: '2025'
  doi: 10.32614/CRAN.package.rmarkdown
- type: software
  title: testthat
  abstract: 'testthat: Unit Testing for R'
  notes: Suggests
  url: https://testthat.r-lib.org
  repository: https://CRAN.R-project.org/package=testthat
  authors:
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
  year: '2025'
  doi: 10.32614/CRAN.package.testthat
  version: '>= 3.0.0'
- type: software
  title: withr
  abstract: 'withr: Run Code ''With'' Temporarily Modified Global State'
  notes: Suggests
  url: https://withr.r-lib.org
  repository: https://CRAN.R-project.org/package=withr
  authors:
  - family-names: Hester
    given-names: Jim
  - family-names: Henry
    given-names: Lionel
    email: lionel@posit.co
  - family-names: Müller
    given-names: Kirill
    email: krlmlr+r@mailbox.org
  - family-names: Ushey
    given-names: Kevin
    email: kevinushey@gmail.com
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
  - family-names: Chang
    given-names: Winston
  year: '2025'
  doi: 10.32614/CRAN.package.withr

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago

Packages