% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/extract_traits.R
\name{extract_traits}
\alias{extract_traits}
\title{Extract Quantitative Traits for Specified Taxa}
\usage{
extract_traits(
  sp.list,
  dataset,
  rank = "species",
  traits = NULL,
  within_species = c("error", "mean", "median"),
  among_species = c("mean", "median")
)
}
\arguments{
\item{sp.list}{A non-empty character vector containing unique taxon names
to extract. Names must correspond to the taxonomic rank specified by
`rank`.}

\item{dataset}{A non-empty data frame or tibble containing taxonomic
information and quantitative trait data. A `"species"` column is required
for all analyses. A `"genus"` or `"family"` column is additionally
required when extracting traits at the corresponding rank.}

\item{rank}{Taxonomic rank used to match the requested taxa. Must be one of
`"species"`, `"genus"`, or `"family"`. The default is `"species"`.}

\item{traits}{Character vector specifying the traits to extract. If `NULL`,
all numeric columns other than `"species"`, `"genus"`, and `"family"`
are extracted.}

\item{within_species}{Rule used when a species has multiple different
finite records for the same trait. Must be `"error"`, `"mean"`, or
`"median"`. The default, `"error"`, requires the user to resolve the
records or explicitly select a summary rule.}

\item{among_species}{Rule used to aggregate species-level values within a
genus or family. Must be `"mean"` or `"median"`. The default is `"mean"`.
This argument is ignored when `rank = "species"`.}
}
\value{
A data frame with one row for each requested taxon, in the order
  supplied in `sp.list`, and one column for each retained numeric trait.
  Taxon names are stored as row names. Taxa not found in `dataset` are
  retained and returned with missing values for all traits.
}
\description{
`extract_traits()` retrieves selected quantitative traits for specified
species, genera, or families.
}
\details{
Repeated records are first resolved separately for each species and trait.
For genus and family extraction, the resulting species-level values are
then aggregated so that each contributing species receives equal weight,
regardless of its number of records in the original dataset.


Taxon names are matched exactly against the column corresponding to `rank`.
The function does not standardize taxonomic names, spelling, capitalization,
or synonyms.

Only numeric traits are extracted. Requested traits that are absent or
non-numeric are ignored with a warning, and the function stops if no
requested numeric traits are available.

For each requested trait, only records belonging to the requested taxa are
examined. Non-finite numeric values (`Inf`, `-Inf`, and `NaN`) in these
records are treated as missing and reported in a warning. Non-finite values
in unrequested taxa or traits do not affect the extraction.

Within each species and trait, missing and non-finite records are excluded.
If no finite values remain, `NA` is returned. A single finite value, or
multiple identical finite values, is returned directly. Multiple different
finite values either trigger an error or are summarized using the mean or
median, according to `within_species`.

For genus and family extraction, the resolved species-level values are
aggregated separately for each trait using `among_species`. Species without
a finite value for the focal trait are excluded from that trait's
aggregation. Each contributing species receives equal weight.

The resulting genus or family value represents the central tendency of the
contributing species. When interpreting this aggregate, users should also
consider the number of contributing species and the variation among their
trait values.

Each species must be assigned to only one requested genus or family.
Conflicting taxonomic assignments cause the function to stop. Values are
not inferred from higher taxonomic levels.

Trait-specific validity constraints are not evaluated automatically. For
example, the function does not assume that zero is invalid because zero or
negative values may be valid for some quantitative traits.
}
\examples{
trait_data <- data.frame(
  species = c("Species a", "Species a", "Species b", "Species c"),
  genus = c("Genus1", "Genus1", "Genus1", "Genus2"),
  family = c("Family1", "Family1", "Family1", "Family2"),
  Trait1 = c(1, 3, 5, 2),
  Trait2 = c(4, 4, 6, NA)
)

# Resolve repeated records using their mean
extract_traits(
  c("Species a", "Species c"),
  trait_data,
  traits = c("Trait1", "Trait2"),
  within_species = "mean"
)

# Calculate genus-level means from resolved species-level values
extract_traits(
  c("Genus1", "Genus2"),
  trait_data,
  rank = "genus",
  traits = c("Trait1", "Trait2"),
  within_species = "mean",
  among_species = "mean"
)

}
