funga_distribution_gap

Find candidate new Brazilian state records for a fungal taxon

fungaR::funga_distribution_gap()

Description

Given a fungal genus or species, checks GBIF and, optionally, speciesLink and the Reflora Virtual Herbarium for specimen and occurrence evidence of the taxon in Brazilian states that are not currently listed in its official Flora e Funga do Brasil (FFB) distribution. This flags candidate new state records for a taxonomist to verify - e.g. a species listed by FFB only for Bahia, but with specimens indexed from Pernambuco - so that the distributions in FFB monographs can be kept complete. Georeferenced records are also placed in the six Brazilian phytogeographic domains, to flag candidate new domain records in the same way.

Details

FFB side. The officially listed states come from the parsed FFB taxon and distribution tables (the same locally cached dataset as funga_records). For a genus, the states of all its species and infraspecific taxa are combined; for a species, those of the species and its infraspecific taxa. If the name is a synonym in FFB, the distribution of its accepted name is used.

Occurrence evidence. Up to three sources can be queried (see sources):

"gbif" (default)GBIF’s public API. The name is first resolved to its GBIF backbone key within the Fungi kingdom only (so a genus name shared with a plant, alga, or animal is never confused with the fungal one), so the records of its synonyms and infraspecific taxa are included. All states are counted in a single request. "reflora"Reflora Virtual Herbarium specimens, via reflora_records (requires the refloraR package). Note that the first use downloads the Reflora herbarium archives - several gigabytes - which refloraR then caches for later calls. "speciesLink"speciesLink’s API, which requires a free API key (specieslink_key; create one at https://specieslink.net).

Free-text state values in these sources (e.g. "Ba", "Est. do Bahia", "Paraiba") are normalised to FFB state names before comparison; values that are not Brazilian states are ignored.

Phytogeographic domains. With domains = TRUE (default), the GBIF records that have coordinates - excluding those GBIF flags with geospatial issues, such as zero coordinates or coordinates outside the stated country - are placed in the six Brazilian phytogeographic domains (Amazonia, Caatinga, Cerrado, Mata Atlantica, Pampa, Pantanal) using IBGE’s biome map (2019) bundled with fungaR, simplified to a 1 km tolerance. A domain with records but not listed for the taxon in FFB is a candidate new domain record. Up to max_coordinates records are read (300 per request); Reflora specimens with coordinates are added when "reflora" is among sources. Records that fall outside the six domains (e.g. just offshore) are kept in records, with Domain = NA, but are never flagged nor drawn on the report’s map. This analysis requires the sf package, and the map in the HTML report the leaflet package; without them, they are skipped with a message.

Occurrence records are evidence to review, not proof: a record in a new state may be a cultivated specimen, a misidentification, or a georeferencing error, which is why the HTML report lists the individual records behind each candidate state.

Arguments

Argument	Description
taxon	Character. A single fungal genus or species name (e.g. `"Trichoderma harzianum"` or `"Trichoderma"`).
state	Character vector. Optional subset of Brazilian states (full name or acronym) to restrict the check to. `NULL` (default) checks all states with any evidence.
sources	Character vector. Which occurrence sources to query: any of `"gbif"`, `"reflora"`, `"speciesLink"`. Defaults to `"gbif"`, the fastest. See Details for the requirements of the other two.
specieslink_key	Character. speciesLink API key, used when `"speciesLink"` is among `sources`. Defaults to the `SPECIESLINK_KEY` environment variable.
domains	Logical. If `TRUE` (default), also place the georeferenced records in the Brazilian phytogeographic domains and flag candidate new domain records (see Details). Requires the sf package.
max_coordinates	Numeric. Maximum number of georeferenced GBIF records read for the domain analysis. Defaults to `5000`.
version	Character. FFB dataset version to compare against. Defaults to `"latest"`. Passed to `funga_download`.
verbose	Logical. If `TRUE` (default), prints progress messages.
save	Logical. If `TRUE` (default), the result is saved to disk as an `.xlsx` spreadsheet.
dir	Character. Directory where the spreadsheet is saved when `save = TRUE`. Defaults to `"funga_distribution_gap"`.
filename	Character. Name of the `.xlsx` file (without extension) to save. Defaults to `"funga_distribution_gap_<taxon>"`.
html_report	Logical. If `TRUE` (default), also writes a self-contained HTML report (`<dir>/<filename>.html`) summarizing the results: KPI counts, an evidence-by-source breakdown, the full state-by-state table, the domain table, an interactive map of the georeferenced records over the phytogeographic domains (coloured by candidate status), the records in candidate domains, and the individual occurrence records found in the new-state-record candidate states - each linking to the record in its source database - all as sortable, filterable DT widgets with buttons to copy or download them as CSV/Excel. Requires the rmarkdown, DT, and htmltools packages; if any is missing, the report is skipped with a message (the `.xlsx` spreadsheet is unaffected).
open_report	Logical. If `TRUE` (default in interactive sessions), opens the HTML report in the browser once rendered.

Value

A list of three data.frames:

statesOne row per Brazilian state with any evidence for taxon (in FFB or in the queried sources): Taxon, State, In_FFB_distribution (whether FFB already lists the state), GBIF_records, Reflora_records, and speciesLink_records (records in the state, for each source queried), and New_state_record_candidate (TRUE when the state has evidence from at least one source but is not in FFB’s distribution). domainsOne row per phytogeographic domain with evidence (in FFB or among the georeferenced records): Taxon, Domain, In_FFB_distribution, Georeferenced_records, and New_domain_record_candidate. Empty when domains = FALSE. recordsOne row per georeferenced record, with its coordinates, State, Domain, collector, date, institution, catalogue number, identification, a link to the record, and the logical columns New_state_record_candidate and New_domain_record_candidate. Empty when domains = FALSE.

With save = TRUE, each table is saved as a sheet of the .xlsx spreadsheet.

Examples

# Candidate new state records for a species
gap <- funga_distribution_gap(taxon = "Trichoderma harzianum")

# A whole genus, restricted to two states
gap_ne <- funga_distribution_gap(taxon = "Trichoderma",
                                 state = c("Pernambuco", "Paraiba"))

# The candidate new phytogeographic domains, and the records behind them
gap$domains
gap$records[gap$records$New_domain_record_candidate, ]

# Adding Reflora herbarium specimens (requires refloraR)
gap_reflora <- funga_distribution_gap(taxon = "Trichoderma harzianum",
                                      sources = c("gbif", "reflora"))

--- title: 'funga_distribution_gap' description: 'Find candidate new Brazilian state records for a fungal taxon' toc: true toc-depth: 3 --- ```{r} #| eval: false fungaR::funga_distribution_gap() ``` ### Description Given a fungal genus or species, checks [GBIF](https://www.gbif.org) and, optionally, [speciesLink](https://specieslink.net) and the [Reflora Virtual Herbarium](https://ipt.jbrj.gov.br/reflora/) for specimen and occurrence evidence of the taxon in Brazilian states that are *not* currently listed in its official Flora e Funga do Brasil (FFB) distribution. This flags candidate new state records for a taxonomist to verify - e.g. a species listed by FFB only for Bahia, but with specimens indexed from Pernambuco - so that the distributions in FFB monographs can be kept complete. Georeferenced records are also placed in the six Brazilian phytogeographic domains, to flag candidate new domain records in the same way. ### Details **FFB side.** The officially listed states come from the parsed FFB taxon and distribution tables (the same locally cached dataset as `funga_records`). For a genus, the states of all its species and infraspecific taxa are combined; for a species, those of the species and its infraspecific taxa. If the name is a synonym in FFB, the distribution of its accepted name is used. **Occurrence evidence.** Up to three sources can be queried (see `sources`): `"gbif"` (default)GBIF's public API. The name is first resolved to its GBIF backbone key within the Fungi kingdom only (so a genus name shared with a plant, alga, or animal is never confused with the fungal one), so the records of its synonyms and infraspecific taxa are included. All states are counted in a single request. `"reflora"`Reflora Virtual Herbarium specimens, via `reflora_records` (requires the refloraR package). Note that the first use downloads the Reflora herbarium archives - several gigabytes - which refloraR then caches for later calls. `"speciesLink"`speciesLink's API, which requires a free API key (`specieslink_key`; create one at https://specieslink.net). Free-text state values in these sources (e.g. `"Ba"`, `"Est. do Bahia"`, `"Paraiba"`) are normalised to FFB state names before comparison; values that are not Brazilian states are ignored. **Phytogeographic domains.** With `domains = TRUE` (default), the GBIF records that have coordinates - excluding those GBIF flags with geospatial issues, such as zero coordinates or coordinates outside the stated country - are placed in the six Brazilian phytogeographic domains (Amazonia, Caatinga, Cerrado, Mata Atlantica, Pampa, Pantanal) using IBGE's biome map (2019) bundled with fungaR, simplified to a 1 km tolerance. A domain with records but not listed for the taxon in FFB is a candidate new domain record. Up to `max_coordinates` records are read (300 per request); Reflora specimens with coordinates are added when `"reflora"` is among `sources`. Records that fall outside the six domains (e.g. just offshore) are kept in `records`, with `Domain = NA`, but are never flagged nor drawn on the report's map. This analysis requires the sf package, and the map in the HTML report the leaflet package; without them, they are skipped with a message. Occurrence records are evidence to review, not proof: a record in a new state may be a cultivated specimen, a misidentification, or a georeferencing error, which is why the HTML report lists the individual records behind each candidate state. ### Arguments | Argument | Description | |---|---| | taxon | Character. A single fungal genus or species name (e.g. `"Trichoderma harzianum"` or `"Trichoderma"`). | | state | Character vector. Optional subset of Brazilian states (full name or acronym) to restrict the check to. `NULL` (default) checks all states with any evidence. | | sources | Character vector. Which occurrence sources to query: any of `"gbif"`, `"reflora"`, `"speciesLink"`. Defaults to `"gbif"`, the fastest. See Details for the requirements of the other two. | | specieslink_key | Character. speciesLink API key, used when `"speciesLink"` is among `sources`. Defaults to the `SPECIESLINK_KEY` environment variable. | | domains | Logical. If `TRUE` (default), also place the georeferenced records in the Brazilian phytogeographic domains and flag candidate new domain records (see Details). Requires the sf package. | | max_coordinates | Numeric. Maximum number of georeferenced GBIF records read for the domain analysis. Defaults to `5000`. | | version | Character. FFB dataset version to compare against. Defaults to `"latest"`. Passed to `funga_download`. | | verbose | Logical. If `TRUE` (default), prints progress messages. | | save | Logical. If `TRUE` (default), the result is saved to disk as an `.xlsx` spreadsheet. | | dir | Character. Directory where the spreadsheet is saved when `save = TRUE`. Defaults to `"funga_distribution_gap"`. | | filename | Character. Name of the `.xlsx` file (without extension) to save. Defaults to `"funga_distribution_gap_<taxon>"`. | | html_report | Logical. If `TRUE` (default), also writes a self-contained HTML report (`<dir>/<filename>.html`) summarizing the results: KPI counts, an evidence-by-source breakdown, the full state-by-state table, the domain table, an interactive map of the georeferenced records over the phytogeographic domains (coloured by candidate status), the records in candidate domains, and the individual occurrence records found in the new-state-record candidate states - each linking to the record in its source database - all as sortable, filterable DT widgets with buttons to copy or download them as CSV/Excel. Requires the rmarkdown, DT, and htmltools packages; if any is missing, the report is skipped with a message (the `.xlsx` spreadsheet is unaffected). | | open_report | Logical. If `TRUE` (default in interactive sessions), opens the HTML report in the browser once rendered. | ### Value A list of three `data.frame`s: `states`One row per Brazilian state with any evidence for `taxon` (in FFB or in the queried sources): `Taxon`, `State`, `In_FFB_distribution` (whether FFB already lists the state), `GBIF_records`, `Reflora_records`, and `speciesLink_records` (records in the state, for each source queried), and `New_state_record_candidate` (`TRUE` when the state has evidence from at least one source but is not in FFB's distribution). `domains`One row per phytogeographic domain with evidence (in FFB or among the georeferenced records): `Taxon`, `Domain`, `In_FFB_distribution`, `Georeferenced_records`, and `New_domain_record_candidate`. Empty when `domains = FALSE`. `records`One row per georeferenced record, with its coordinates, `State`, `Domain`, collector, date, institution, catalogue number, identification, a link to the record, and the logical columns `New_state_record_candidate` and `New_domain_record_candidate`. Empty when `domains = FALSE`. With `save = TRUE`, each table is saved as a sheet of the `.xlsx` spreadsheet. ### Examples ```r # Candidate new state records for a species gap <- funga_distribution_gap(taxon = "Trichoderma harzianum") # A whole genus, restricted to two states gap_ne <- funga_distribution_gap(taxon = "Trichoderma", state = c("Pernambuco", "Paraiba")) # The candidate new phytogeographic domains, and the records behind them gap$domains gap$records[gap$records$New_domain_record_candidate, ] # Adding Reflora herbarium specimens (requires refloraR) gap_reflora <- funga_distribution_gap(taxon = "Trichoderma harzianum", sources = c("gbif", "reflora")) ```