funga_get_children_taxa

Get child taxa from Flora e Funga do Brasil

fungaR::funga_get_children_taxa()

Description

Returns all child taxa (species, subspecies, varieties, etc.) for a given taxonomic name at a specified rank. Useful for getting all species in a genus, all genera in an order, all species in a family, etc.

Details

For rank %in% c("division", "order", "genus", "species"), the function first finds the parent taxon row, then returns all children that have the parent’s taxonID in their lineage (parentNameUsageID), walking down the real FFB hierarchy for fungi: Division -> Order -> Genus -> Species -> Subspecies/Variety/Form.

For rank = "family", there is no such row to walk from (FFB does not give Fungi family-rank taxon records), so genus/species/infraspecific records are instead matched directly on their family classification column. Likewise, requesting child_rank = "family" from a division or order returns a small derived summary data frame (one row per unique family found among the genus-level descendants, with the count of genera in each), rather than real FFB taxon rows, since no such rows exist.

Child rank behavior:

• If child_rank = NULL: Returns ALL descendant ranks
• If child_rank = "species": Returns only species (direct children)
• If child_rank = "subspecies": Returns only subspecies

Arguments

Argument	Description
taxon_name	Character. Scientific name to search for (e.g., “Trichoderma”, “Xylariaceae”, “Agaricales”).
rank	Character. The taxonomic rank of the input name. Options: "division", "order", "family", "genus", "species". Default is "genus". Fungi are classified in FFB by Division (phylum-equivalent, e.g. Ascomycota, Basidiomycota) rather than Class, and FFB does not register a standalone taxon record for family (or class) for the Fungi kingdom - family is stored only as a classification column on genus/species records. rank = "family" is still supported here, but internally it matches directly on that column rather than walking the parent-child hierarchy (see Details).
child_rank	Character or NULL. The taxonomic rank(s) to return as children. If a single rank is provided (e.g., "species"), returns only that rank. If NULL (default), returns ALL descendant ranks (e.g., for a genus: species, subspecies, varieties, etc.). Options: "division", "order", "family", "genus", "species", "subspecies", "variety", "form".
include_synonyms	Logical. If TRUE, includes synonym names (taxonomicStatus == "SINONIMO") in addition to accepted names. Default is FALSE.
version	Character. FFB dataset version to use. Defaults to "latest". Passed to funga_download and funga_parse.
rm_funga_database	Logical. If TRUE, the downloaded FFB database folder ("funga_download") is deleted after the search is complete. If FALSE (default), the database is kept on disk. Keeping the database is recommended because subsequent searches will reuse the existing download, checking if the stored version matches the requested version. If the stored version is outdated or different from the requested version, the function automatically re-downloads the correct version. This caching behavior significantly speeds up repeated searches.
verbose	Logical. If TRUE (default), prints informative progress messages during parsing. If FALSE, runs quietly.

Value

A data frame containing child taxa that match the requested parent taxon after the applied filters.

Examples

# Get all species in a genus (direct children)
species <- funga_get_children_taxa(
  taxon_name = "Trichoderma",
  rank = "genus",
  child_rank = "species"
)

# Get ALL descendants (species, subspecies, varieties)
all_descendants <- funga_get_children_taxa(
  taxon_name = "Trichoderma",
  rank = "genus",
  child_rank = NULL
)

# Get all genera in a family (including synonyms) -- matched via the
# 'family' classification column, since FFB has no family-rank row for Fungi
genera <- funga_get_children_taxa(
  taxon_name = "Xylariaceae",
  rank = "family",
  child_rank = "genus",
  include_synonyms = TRUE
)

# Get all genera in an order
genera_in_order <- funga_get_children_taxa(
  taxon_name = "Agaricales",
  rank = "order",
  child_rank = "genus"
)