gbif_gap

Find fungal species with Brazilian type specimens in GBIF that are missing from FFB

fungaR::gbif_gap()

Description

Given a fungal genus, finds the species-level names whose type specimens - holotypes, isotypes, lectotypes, syntypes, paratypes, and so on - were collected in Brazil according to the Global Biodiversity Information Facility (GBIF), but that are not currently registered in the Flora e Funga do Brasil (FFB). A type specimen collected in Brazil is direct evidence that the taxon occurs in the country, so every name returned is a candidate for inclusion in FFB.

Details

GBIF aggregates the type specimens digitised by herbaria and fungaria worldwide (e.g. RB, K, NY, URM). The search runs in three steps, each covering the whole genus at once rather than one request per species, so even large genera return in seconds:

a single faceted occurrence search lists every name in the genus with type specimens collected in Brazil, and how many;
those names are resolved against the GBIF taxonomic backbone, which also gives each name’s accepted species;
for the names missing from FFB only, the type specimens themselves are retrieved (many names per request) to summarise their type status, herbarium/ fungarium, catalogue number, and state.

Type specimens are filed in GBIF under their current identification, which for a type is usually the typified name itself or, when that name is now a synonym, its accepted name. Only species-level names are reported.

A candidate counts as “already in FFB” if either its GBIF name or its GBIF accepted name matches any FFB name (accepted or synonym, anywhere in the checklist, since GBIF and FFB can disagree on which genus a species belongs to). Names are compared ignoring case, diacritics, hyphens, and the genitive -ii/-i ending, so orthographic variants are not reported as missing.

Only Fungi are searched: the genus is looked up in the GBIF Fungi kingdom, so a genus name shared with a plant, alga, or animal never resolves to the wrong group.

The FFB side of the comparison uses the same locally cached FFB dataset as funga_download and funga_parse (in the "funga_download" folder), downloading it only when needed.

Arguments

Argument	Description
taxon	Character. A single fungal genus name (e.g. `"Trichoderma"`, `"Phellinotus"`).
type_status	Character or `NULL`. GBIF type statuses counted as evidence (GBIF’s current vocabulary, e.g. `"Holotype"`, `"Isotype"`). `NULL` (default) uses all primary and secondary type categories: Type, Holotype, Isotype, Lectotype, Isolectotype, Syntype, Isosyntype, Neotype, Isoneotype, Epitype, Isoepitype, Paratype, Isoparatype, Paralectotype, OriginalMaterial, and TypeSeries. Use e.g. `c("Holotype", "Isotype")` for a stricter search.
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 `"gbif_gap"`.
filename	Character. Name of the `.xlsx` file (without extension) to save. Defaults to `"gbif_gap_<taxon>"`.
html_report	Logical. If `TRUE` (default), also writes a self-contained HTML report (`<dir>/<filename>.html`) summarizing the results: KPI counts and the full candidate table as a sortable, filterable DT widget with buttons to copy or download it 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 data.frame, one row per species-level GBIF name in the requested genus that has type specimens collected in Brazil and is absent from the current FFB checklist, with columns:

GBIF_KeyThe name’s GBIF backbone key. Taxon_nameThe name as registered in GBIF. AuthorsAuthor citation. Taxonomic_statusGBIF’s taxonomic status (e.g. "ACCEPTED", "SYNONYM", "DOUBTFUL"). Accepted_name, Accepted_full_nameGBIF’s accepted species for this name, without and with authors (the name itself when it is accepted). N_type_specimensNumber of type specimens collected in Brazil in GBIF. Type_statusesThe type statuses among them (e.g. "Holotype; Isotype"). Type_specimensUp to ten specimens as herbarium/fungarium and catalogue number, with type status (e.g. "URM 80362 (Holotype)"). Specimen_namesThe names the type specimens are filed under in GBIF - usually the typified name, which for a synonym differs from Taxon_name (e.g. the types of a species’ basionym). Collectors, Years, StatesCollectors, collection years, and Brazilian states of those specimens. GBIF_Published_inProtologue citation, when GBIF has it. GBIF_URLLink to the name’s GBIF page. In_FFBAlways FALSE (kept for clarity when combining with other tables).

Examples

# Species of Trichoderma with Brazilian type specimens that are missing from FFB
gap <- gbif_gap(taxon = "Trichoderma")

# Stricter evidence: holotypes and isotypes only
gap_strict <- gbif_gap(taxon = "Trichoderma", type_status = c("Holotype", "Isotype"))

--- title: 'gbif_gap' description: 'Find fungal species with Brazilian type specimens in GBIF that are missing from FFB' toc: true toc-depth: 3 --- ```{r} #| eval: false fungaR::gbif_gap() ``` ### Description Given a fungal genus, finds the species-level names whose type specimens - holotypes, isotypes, lectotypes, syntypes, paratypes, and so on - were collected in Brazil according to the [Global Biodiversity Information Facility](https://www.gbif.org) (GBIF), but that are not currently registered in the Flora e Funga do Brasil (FFB). A type specimen collected in Brazil is direct evidence that the taxon occurs in the country, so every name returned is a candidate for inclusion in FFB. ### Details GBIF aggregates the type specimens digitised by herbaria and fungaria worldwide (e.g. RB, K, NY, URM). The search runs in three steps, each covering the whole genus at once rather than one request per species, so even large genera return in seconds: 1. a single faceted occurrence search lists every name in the genus with type specimens collected in Brazil, and how many; 2. those names are resolved against the GBIF taxonomic backbone, which also gives each name's accepted species; 3. for the names missing from FFB only, the type specimens themselves are retrieved (many names per request) to summarise their type status, herbarium/ fungarium, catalogue number, and state. Type specimens are filed in GBIF under their current identification, which for a type is usually the typified name itself or, when that name is now a synonym, its accepted name. Only species-level names are reported. A candidate counts as "already in FFB" if either its GBIF name or its GBIF *accepted* name matches any FFB name (accepted or synonym, anywhere in the checklist, since GBIF and FFB can disagree on which genus a species belongs to). Names are compared ignoring case, diacritics, hyphens, and the genitive *-ii*/*-i* ending, so orthographic variants are not reported as missing. Only Fungi are searched: the genus is looked up in the GBIF Fungi kingdom, so a genus name shared with a plant, alga, or animal never resolves to the wrong group. The FFB side of the comparison uses the same locally cached FFB dataset as `funga_download` and `funga_parse` (in the `"funga_download"` folder), downloading it only when needed. ### Arguments | Argument | Description | |---|---| | taxon | Character. A single fungal genus name (e.g. `"Trichoderma"`, `"Phellinotus"`). | | type_status | Character or `NULL`. GBIF type statuses counted as evidence (GBIF's current vocabulary, e.g. `"Holotype"`, `"Isotype"`). `NULL` (default) uses all primary and secondary type categories: Type, Holotype, Isotype, Lectotype, Isolectotype, Syntype, Isosyntype, Neotype, Isoneotype, Epitype, Isoepitype, Paratype, Isoparatype, Paralectotype, OriginalMaterial, and TypeSeries. Use e.g. `c("Holotype", "Isotype")` for a stricter search. | | 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 `"gbif_gap"`. | | filename | Character. Name of the `.xlsx` file (without extension) to save. Defaults to `"gbif_gap_<taxon>"`. | | html_report | Logical. If `TRUE` (default), also writes a self-contained HTML report (`<dir>/<filename>.html`) summarizing the results: KPI counts and the full candidate table as a sortable, filterable DT widget with buttons to copy or download it 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 `data.frame`, one row per species-level GBIF name in the requested genus that has type specimens collected in Brazil and is absent from the current FFB checklist, with columns: GBIF_KeyThe name's GBIF backbone key. Taxon_nameThe name as registered in GBIF. AuthorsAuthor citation. Taxonomic_statusGBIF's taxonomic status (e.g. `"ACCEPTED"`, `"SYNONYM"`, `"DOUBTFUL"`). Accepted_name, Accepted_full_nameGBIF's accepted species for this name, without and with authors (the name itself when it is accepted). N_type_specimensNumber of type specimens collected in Brazil in GBIF. Type_statusesThe type statuses among them (e.g. `"Holotype; Isotype"`). Type_specimensUp to ten specimens as herbarium/fungarium and catalogue number, with type status (e.g. `"URM 80362 (Holotype)"`). Specimen_namesThe names the type specimens are filed under in GBIF - usually the typified name, which for a synonym differs from `Taxon_name` (e.g. the types of a species' basionym). Collectors, Years, StatesCollectors, collection years, and Brazilian states of those specimens. GBIF_Published_inProtologue citation, when GBIF has it. GBIF_URLLink to the name's GBIF page. In_FFBAlways `FALSE` (kept for clarity when combining with other tables). ### Examples ```r # Species of Trichoderma with Brazilian type specimens that are missing from FFB gap <- gbif_gap(taxon = "Trichoderma") # Stricter evidence: holotypes and isotypes only gap_strict <- gbif_gap(taxon = "Trichoderma", type_status = c("Holotype", "Isotype")) ```