funga_records

Retrieve taxon records from the Flora e Funga do Brasil database

fungaR::funga_records()

Description

Retrieves and filters fungal taxon records from the locally parsed Flora e Funga do Brasil (FFB) taxonomic database, hosted by the Rio de Janeiro Botanical Garden. Unlike funga_search, which resolves a list of species names you already have against the FFB database, funga_records() browses and filters the FFB checklist itself by taxonomic, geographic, and trait-based criteria; no input name list required.

Details

The function downloads (if needed) and parses the FFB dataset exactly like funga_search, then applies the requested filters:

• taxon is matched against the family, genus, and taxonName columns of the FFB taxon table (family names ending in "aceae", single-word genus names, and multi-word species names are detected automatically).
• taxonRank and taxonomicStatus are matched directly against the taxon table.
• state, phytogeographicDomain, endemism, and establishmentMeans are matched against the FFB distribution table (distribution.txt).
• lifeForm, habitat, and vegetationType are matched against the FFB species profile table (speciesprofile.txt).

Text filters are case- and accent-insensitive ("Mata Atlantica" matches "Mata Atl\u00e2ntica", "Liquenizado" matches "liquenizado"). All filters are combined with a logical AND. The result always has one row per matching taxon (geographic/trait filters restrict which taxa are returned, they do not multiply rows).

Arguments

Argument	Description
taxon	Character vector. One or more family, genus, or species names to filter by (e.g. c("Hymenochaetaceae", "Trichoderma", "Xylaria hypoxylon")). NULL (default) does not filter by taxon.
taxonRank	Character vector. Taxonomic rank(s) to keep (e.g. "ESPECIE", "VARIEDADE", "SUBESPECIE", "FORMA", "GENERO", "ORDEM", "DIVISAO" - fungi are classified in FFB by Division/phylum rather than Class). NULL (default) keeps all ranks.
taxonomicStatus	Character vector. FFB taxonomic status to keep: "NOME_ACEITO" (accepted), "SINONIMO" (synonym), or "NOME_DUVIDOSO" (doubtful). NULL (default) keeps all statuses.
state	Character vector. Brazilian state(s) - full name or acronym, diacritics-insensitive (e.g. "Bahia" or "BA") - to filter by occurrence, based on the FFB distribution table (or, with endemism = TRUE, by exclusive occurrence; see the Endemism section). NULL (default) does not filter by state.
phytogeographicDomain	Character vector. Phytogeographic domain(s) to filter by (e.g. "Caatinga", "Mata Atlantica"). NULL (default) does not filter by domain.
endemism	TRUE, FALSE, "Brazil", or NULL. TRUE keeps endemics: Brazilian endemics without an area filter, or the endemics exclusive to the requested state, phytogeographicDomain, or vegetationType. "Brazil" keeps Brazilian endemics occurring in those areas. FALSE keeps the complement of TRUE. NULL (default) does not filter by endemism. See the Endemism section.
establishmentMeans	Character vector. The origin of the taxon in Brazil - whether it is native to the country or was introduced into it - as recorded in FFB’s establishmentMeans field: "native" (FFB’s "Nativa") or "introduced" (FFB’s "Ex\u00f3tica", i.e. exotic). English or Portuguese, case- and accent-insensitive: "native"/"nativa", "introduced"/"exotic"/ "exotica". NULL (default) does not filter by origin; taxa whose origin FFB does not record are only returned then.
lifeForm, habitat, vegetationType	Character vectors, based on the FFB species profile table. NULL (default) does not filter. - lifeForm: nutritional/ecological mode, e.g. "Saprobio", "Parasita", "Liquenizado", "Micorrizico", "Endofitico", "Entomogeno". - habitat: for fungi this field records the substrate/host the fungus was collected on rather than a plant growth habitat, e.g. "Planta viva - raiz", "Planta viva - folha", "Planta viva - cortex do caule", "Tronco em decomposicao", "Folhedo", "Solo", "Esterco ou Fezes", "Outro fungo", "Animal morto". Use this argument to browse the checklist by host/substrate type (FFB does not currently publish a separate named host-taxon field). - vegetationType: vegetation type where the record was made, e.g. "Floresta Ombrofila (= Floresta Pluvial)", "Cerrado (lato sensu)", "Manguezal".
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 and reused by subsequent calls, which significantly speeds up repeated queries.
verbose	Logical. If TRUE (default), prints informative progress messages during download and parsing. If FALSE, runs quietly.
save	Logical. If TRUE, the filtered records are saved to disk as a CSV file. Default is FALSE.
dir	Character. Directory where the CSV file will be saved when save = TRUE. Defaults to "funga_records".
filename	Character. Name of the CSV file (without extension) to save when save = TRUE. Defaults to "funga_records_search".

Value

A data.frame of FFB taxon records matching the requested filters, with one row per taxon. Besides the taxon fields, each row carries the taxon’s FFB distribution and species profile, the unique values of each field joined in one cell with " | " (e.g. "BA | MG | PE"): state (abbreviations), phytogeographicDomain, endemism, establishmentMeans, lifeForm, habitat, and vegetationType - always describing the taxon’s full record, whatever filters were applied. A field FFB does not record for a taxon is NA. If save = TRUE, the result is also written to <dir>/<filename>.csv.

Examples

# All accepted species in Hymenochaetaceae (downloads + parses automatically, caches result)
hymeno <- funga_records(taxon = "Hymenochaetaceae",
                        taxonomicStatus = "NOME_ACEITO")

# All accepted species endemic to Brazil
brazil_endemics <- funga_records(endemism = TRUE,
                                 taxonomicStatus = "NOME_ACEITO")

# Accepted species endemic to Bahia: found only in Bahia
bahia_endemics <- funga_records(state = "Bahia",
                                endemism = TRUE,
                                taxonomicStatus = "NOME_ACEITO")

# Accepted Brazilian endemics that occur in Bahia (and possibly elsewhere)
brazil_endemics_in_bahia <- funga_records(state = "Bahia",
                                          endemism = "Brazil",
                                          taxonomicStatus = "NOME_ACEITO")

# Species endemic to the Caatinga of Bahia: found only in Bahia, only in the Caatinga
bahia_caatinga_endemics <- funga_records(state = "Bahia",
                                         phytogeographicDomain = "Caatinga",
                                         endemism = TRUE)

# Introduced (exotic) species recorded in Bahia
bahia_introduced <- funga_records(state = "Bahia",
                                  establishmentMeans = "introduced")

# Lichenized fungi recorded in the Caatinga
caatinga_lichens <- funga_records(phytogeographicDomain = "Caatinga",
                                  lifeForm = "Liquenizado")

# Fungi recorded growing on living plant roots (habitat = substrate/host)
root_associates <- funga_records(habitat = "Planta viva - raiz")

# Use a specific FFB version stored in a custom folder, and save the result
funga_records(taxon = "Trichoderma",
             version = "393.418",
             save = TRUE,
             dir = "funga_records",
             filename = "trichoderma_records")