Title:	Functional Trait Moment Calculation
Version:	0.0.5
Depends:	R (≥ 4.1.0)
Description:	Calculates the community four 'moments' (mean, variance, skewness, and kurtosis) of a given trait based on the moments described in Wieczynski et al. (2019) <doi:10.1073/pnas.1813723116>. These functional metrics are extremely useful in characterizing the distribution of traits in a plant community. It also provides tidyverse-friendly wrappers to seamlessly calculate advanced functional diversity indices (e.g., FDis, Rao's Q) using 'fundiversity' (Grenie et al. 2023 <doi:10.1111/ecog.06585>) and functional rarity indices using 'funrar' (Grenie et al. 2017 <doi:10.1111/ddi.12629>). Evaluating these community-weighted moments and diversity metrics allows researchers to evaluate shifts in optimal phenotypes and understand ecological filtering with exactness.
License:	MIT + file LICENSE
Suggests:	covr, testthat (≥ 3.1.5)
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.3
URL:	https://github.com/PaulESantos/tidyttmoment, https://paulesantos.github.io/tidyttmoment/
BugReports:	https://github.com/PaulESantos/tidyttmoment/issues
Imports:	cli, dplyr, lifecycle, tidyr, fundiversity, funrar, rlang, tibble
NeedsCompilation:	no
Packaged:	2026-03-19 04:11:25 UTC; PC
Author:	Paul Efren Santos Andrade [aut, cre], Macroecology Lab [cph, fnd]
Maintainer:	Paul Efren Santos Andrade <paulefrens@gmail.com>
Repository:	CRAN
Date/Publication:	2026-03-23 17:20:02 UTC

tidyttmoment: Functional Trait Moment Calculation

Description

Calculates the community four 'moments' (mean, variance, skewness, and kurtosis) of a given trait based on the moments described in Wieczynski et al. (2019) doi:10.1073/pnas.1813723116. These functional metrics are extremely useful in characterizing the distribution of traits in a plant community. It also provides tidyverse-friendly wrappers to seamlessly calculate advanced functional diversity indices (e.g., FDis, Rao's Q) using 'fundiversity' (Grenie et al. 2023 doi:10.1111/ecog.06585) and functional rarity indices using 'funrar' (Grenie et al. 2017 doi:10.1111/ddi.12629). Evaluating these community-weighted moments and diversity metrics allows researchers to evaluate shifts in optimal phenotypes and understand ecological filtering with exactness.

Calculates the community four 'moments' (mean, variance, skewness, and kurtosis) of a given trait based on the moments described in Wieczynski et al. (2019) doi:10.1073/pnas.1813723116. These functional metrics are extremely useful in characterizing the distribution of traits in a plant community. It also provides tidyverse-friendly wrappers to seamlessly calculate advanced functional diversity indices (e.g., FDis, Rao's Q) using 'fundiversity' (Grenie et al. 2023 doi:10.1111/ecog.06585) and functional rarity indices using 'funrar' (Grenie et al. 2017 doi:10.1111/ddi.12629). Evaluating these community-weighted moments and diversity metrics allows researchers to evaluate shifts in optimal phenotypes and understand ecological filtering with exactness.

Author(s)

Maintainer: Paul Efren Santos Andrade paulefrens@gmail.com (ORCID)

Other contributors:

• Macroecology Lab [copyright holder, funder]

See Also

Useful links:

• https://github.com/PaulESantos/tidyttmoment

• https://paulesantos.github.io/tidyttmoment/

• Report bugs at https://github.com/PaulESantos/tidyttmoment/issues

Useful links:

• https://github.com/PaulESantos/tidyttmoment

• https://paulesantos.github.io/tidyttmoment/

• Report bugs at https://github.com/PaulESantos/tidyttmoment/issues

Calculate functional diversity indices from tidy data

Description

Wraps the fundiversity package to calculate functional diversity indices (FRic, FDiv, FEve, FDis, Rao's Q) directly from a tidy long-format data frame. Automatically handles parallelization if a future::plan() is set.

Usage

tidy_calc_diversity(
  df,
  comm_names,
  sp_names,
  trait_names,
  trait_value,
  weight,
  index = c("FRic", "FDiv", "FEve", "FDis", "RaoQ")
)

Arguments

Value

A tibble with community coordinates and the selected functional diversity indices.

Calculate community weighted mean, variance, skewness, and kurtosis

Description

Calculates the community weighted mean, variance, skewness, and excess kurtosis of a given trait based on the moments described in Wieczynski et al. (2019).

Usage

tidy_calc_moment(df, trait_names, comm_names, trait_value, weight)

Arguments

Value

Returns a tibble with the columns comm, trait, cwm (mean), cwv (variance), cws (skewness), and cwk (excess kurtosis).

References

Enquist, B. J., Norberg, J., Bonser, S. P., Violle, C., Webb, C. T., Henderson, A., ... & Savage, V. M. (2015). Scaling from traits to ecosystems. Advances in Ecological Research, 52, 249-318.

Metcalfe, R. J., Ozturk, M., & Pouteau, R. (2020). Using functional traits to model annual plant community dynamics. Ecology.

Šímová, I., Violle, C., Kraft, N. J., Storch, D., Svenning, J. C., Gallagher, R. V., ... & Enquist, B. J. (2018). Spatial patterns and climate relationships of major plant traits in the New World differ between woody and herbaceous species. Global Ecology and Biogeography, 27(8), 895-916.

Wieczynski, D. J., Boyle, B., Buzzard, V., Duran, S. M., Henderson, A. N., Hulshof, C. M., ... & Savage, V. M. (2019). Climate shapes and shifts functional biodiversity in forests worldwide. Proceedings of the National Academy of Sciences, 116(2), 587-592.

Examples

df <- data.frame(trait = c("height", "height", "weight", "weight"),
                 trait_value = c(5, 10, 15, 12),
                 abundancia = c(1, 2, 1, 3),
                 comm = c("A", "A", "B", "B"))
tidy_calc_moment(df,
trait_names = trait,
comm_names = comm,
trait_value = trait_value,
weight = abundancia)

Calculate functional rarity indices from tidy data

Description

Wraps the funrar package to calculate functional rarity indices (Distinctiveness and Uniqueness) directly from a tidy long-format data frame.

Usage

tidy_calc_rarity(df, comm_names, sp_names, trait_names, trait_value, weight)

Arguments

Value

A list of tibbles containing distinctiveness and uniqueness metrics.

Convert tidy long data to community and trait matrices

Description

Helper function to pivot a tidy long-format data frame into a site-by-species abundance matrix and a species-by-trait matrix, which are required for indices like functional diversity and rarity.

Usage

tidy_to_matrices(df, comm_names, sp_names, trait_names, trait_value, weight)

Arguments

Value

A list containing site_species (a site by species matrix) and species_traits (a species by trait matrix).

Examples

df <- data.frame(
  comm = c("A", "A", "B", "B"),
  species = c("sp1", "sp2", "sp1", "sp3"),
  trait = c("height", "height", "height", "height"),
  trait_value = c(5, 10, 5, 15),
  abundance = c(1, 2, 1, 3)
)
tidy_to_matrices(df, comm, species, trait, trait_value, abundance)