flora_species_gap

Find species that occur in Brazil but are missing from FFB

floraR::flora_species_gap()

Description

Given a genus of plants or algae, finds the species-level names that global sources record for Brazil but that are not currently registered in the Flora e Funga do Brasil (FFB) - candidates for inclusion in the FFB monograph of the group. Two independent kinds of evidence are combined (see sources):

POWO distributions: species that Plants of the World Online (POWO, Royal Botanic Gardens, Kew) maps in Brazil;
GBIF type specimens: species whose type specimens - holotypes, isotypes, lectotypes, syntypes, paratypes, and so on - were collected in Brazil, according to the herbaria that publish them through the Global Biodiversity Information Facility (GBIF).

The result is a single table, one row per name, stating which source(s) reported it: names reported by both are the strongest candidates. This is not a general diff of the databases: a name missing from FFB is only returned when there is evidence that the species occurs in Brazil.

Details

FFB side. Names are compared against the locally cached FFB dataset (as in flora_download and flora_parse). A name counts as “already in FFB” if either the name itself or its accepted name (in POWO or GBIF) matches any FFB name - accepted or synonym, anywhere in the checklist, since checklists disagree on generic placement (e.g. a Myrcia synonym accepted as Eugenia florida). Names are compared ignoring case, diacritics, hyphens, y/i, and the genitive -ii/-i ending, so orthographic variants such as Luetzelburgia andrade-limae and FFB’s L. andradelimae are not reported. Only species-level names are reported.

POWO ("powo"). POWO’s names, synonymy, and distribution maps come from the World Checklist of Vascular Plants (WCVP), read from one of two sources chosen with powo_source:

"rWCVPdata" (default): The whole WCVP, installed locally by the rWCVPdata package: every name and distribution of the genus is resolved at once, in memory. The data is as current as the installed release (see rWCVPdata::wcvp_check_version()). rWCVPdata is not on CRAN; install it with install.packages("rWCVPdata", repos = c("https://matildabrown.github.io/drat", "https://cloud.r-project.org")).
"checklistbank": POWO’s own weekly export and WCVP, as hosted on ChecklistBank (POWO’s own API blocks programmatic clients). Always current and needs no extra package, but slower: one request per FFB-missing name.

A POWO name has Brazil evidence when its accepted name occurs in at least one of the five TDWG level-3 areas covering Brazil - Brazil North (BZN), Northeast (BZE), West-Central (BZC), Southeast (BZL), and South (BZS); native, introduced, or extinct, but not doubtful. Without a mapped distribution, POWO’s free-text range (e.g. "Brazil (Bahia)") is checked instead. POWO covers vascular plants only, so it finds nothing for algae.

GBIF ("gbif"). The genus is looked up among plants and algae only - the GBIF kingdoms Plantae (land plants, red and green algae), Chromista (brown algae, diatoms), and Protozoa (euglenids) - so a genus name shared with an animal (e.g. Gracilaria, both a red alga and a moth) resolves to the plant or alga. A single faceted search lists every name in the genus with type specimens collected in Brazil; for the FFB-missing names only, the specimens themselves are then retrieved, many names per request, and summarised. Types are filed in GBIF under their current identification - usually the typified name - which GBIF_Specimen_names shows.

Arguments

Argument	Description
taxon	Character. A single genus name of plants or algae (e.g. `"Myrcia"`, `"Gracilaria"`). Fungi are not searched.
sources	Character vector. Which kinds of evidence to use: `"powo"` (POWO distributions), `"gbif"` (Brazilian type specimens in GBIF), or both (default).
powo_source	Character. Where POWO’s data is read from: `"rWCVPdata"` (default; fast, local) or `"checklistbank"` (always current, slower). See Details.
require_brazil_evidence	Logical. Applies to POWO. If `TRUE` (default), POWO names are only kept when POWO places the species in Brazil. Set to `FALSE` to also return POWO names missing from FFB regardless of distribution, for manual review. (GBIF names always have Brazil evidence: their types were collected there.)
type_status	Character or `NULL`. Applies to 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.
fetch_details	Logical. Applies to POWO with `powo_source = "checklistbank"`: if `TRUE` (default), each candidate’s protologue citation is fetched (one request per name). With `"rWCVPdata"` it is always included.
max_number	Numeric. Applies to POWO with `powo_source = "checklistbank"`: maximum number of names retrieved. Defaults to `5000`.
version	Character. FFB dataset version to compare against. Defaults to `"latest"`. Passed to `flora_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 `"flora_species_gap"`.
filename	Character. Name of the `.xlsx` file (without extension) to save. Defaults to `"flora_species_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 name in the genus that is absent from the current FFB checklist and reported by at least one source, sorted with the names reported by both sources first. Common columns:

Taxon_name, Authors: The name and its author citation.
Accepted_name: The accepted name (POWO’s when available, else GBIF’s).
Found_in: Which source(s) reported the name: "POWO; GBIF", "POWO", or "GBIF".
Brazil_evidence: Logical; TRUE when POWO places the species in Brazil or it has Brazilian type specimens in GBIF.
In_FFB: Always FALSE (kept for clarity when combining with other tables).

POWO columns (when "powo" is among sources; NA for names only in GBIF):

POWO_ID, POWO_Taxonomic_status, POWO_Accepted_name: The name’s POWO (IPNI) identifier, status (e.g. "Accepted", "Synonym"), and accepted name.
POWO_Year, POWO_Published_in: Year of publication and protologue citation.
POWO_Range: POWO’s free-text range.
POWO_Distribution, POWO_Brazil_Areas: Every TDWG level-3 area of the accepted name’s distribution, and only the Brazilian ones.
POWO_Brazil_Evidence, POWO_Evidence_Source: Whether POWO places the species in Brazil, and whether from the "WCVP distribution" or the "POWO range text".
POWO_URL, IPNI_URL: Links to the name’s POWO and IPNI pages.

GBIF columns (when "gbif" is among sources; NA for names only in POWO):

GBIF_Key, GBIF_Taxonomic_status, GBIF_Accepted_name: The name’s GBIF backbone key, status (e.g. "ACCEPTED", "DOUBTFUL"), and accepted species.
GBIF_N_type_specimens, GBIF_Type_statuses: Number of type specimens collected in Brazil, and their type categories.
GBIF_Type_specimens: Up to ten specimens as herbarium, catalogue number, and type status (e.g. "RB 00123 (Holotype)").
GBIF_Specimen_names: The names the types are filed under - usually the typified name, e.g. the basionym of a species.
GBIF_Collectors, GBIF_Years, GBIF_States: Collectors, collection years, and Brazilian states of those specimens.
GBIF_Published_in, GBIF_URL: Protologue citation, when GBIF has it, and a link to the name’s GBIF page.

Examples

# Species of Myrcia recorded in Brazil by POWO and/or with Brazilian type
# specimens in GBIF, but missing from FFB
gap <- flora_species_gap(taxon = "Myrcia")

# POWO only, read live from ChecklistBank instead of the local WCVP copy
gap_powo <- flora_species_gap(taxon = "Myrcia", sources = "powo",
                              powo_source = "checklistbank")

# An algal genus: GBIF type specimens only (POWO covers vascular plants)
gap_algae <- flora_species_gap(taxon = "Gracilaria", sources = "gbif")

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

--- title: 'flora_species_gap' description: 'Find species that occur in Brazil but are missing from FFB' toc: true toc-depth: 3 --- ```{r} #| eval: false floraR::flora_species_gap() ``` ### Description Given a genus of plants or algae, finds the species-level names that global sources record for Brazil but that are not currently registered in the Flora e Funga do Brasil (FFB) - candidates for inclusion in the FFB monograph of the group. Two independent kinds of evidence are combined (see `sources`): - **POWO distributions**: species that [Plants of the World Online](https://powo.science.kew.org) (POWO, Royal Botanic Gardens, Kew) maps in Brazil; - **GBIF type specimens**: species whose type specimens - holotypes, isotypes, lectotypes, syntypes, paratypes, and so on - were collected in Brazil, according to the herbaria that publish them through the [Global Biodiversity Information Facility](https://www.gbif.org) (GBIF). The result is a single table, one row per name, stating which source(s) reported it: names reported by both are the strongest candidates. This is not a general diff of the databases: a name missing from FFB is only returned when there is evidence that the species occurs in Brazil. ### Details **FFB side.** Names are compared against the locally cached FFB dataset (as in `flora_download` and `flora_parse`). A name counts as "already in FFB" if either the name itself or its *accepted* name (in POWO or GBIF) matches any FFB name - accepted or synonym, anywhere in the checklist, since checklists disagree on generic placement (e.g. a *Myrcia* synonym accepted as *Eugenia florida*). Names are compared ignoring case, diacritics, hyphens, *y*/*i*, and the genitive *-ii*/*-i* ending, so orthographic variants such as *Luetzelburgia andrade-limae* and FFB's *L. andradelimae* are not reported. Only species-level names are reported. **POWO** (`"powo"`). POWO's names, synonymy, and distribution maps come from the [World Checklist of Vascular Plants](https://powo.science.kew.org/about-wcvp) (WCVP), read from one of two sources chosen with `powo_source`: - `"rWCVPdata"` (default): The whole WCVP, installed locally by the [rWCVPdata](https://github.com/matildabrown/rWCVPdata) package: every name and distribution of the genus is resolved at once, in memory. The data is as current as the installed release (see `rWCVPdata::wcvp_check_version()`). rWCVPdata is not on CRAN; install it with `install.packages("rWCVPdata", repos = c("https://matildabrown.github.io/drat", "https://cloud.r-project.org"))`. - `"checklistbank"`: POWO's own weekly export and WCVP, as hosted on [ChecklistBank](https://www.checklistbank.org) (POWO's own API blocks programmatic clients). Always current and needs no extra package, but slower: one request per FFB-missing name. A POWO name has Brazil evidence when its accepted name occurs in at least one of the five TDWG level-3 areas covering Brazil - Brazil North (`BZN`), Northeast (`BZE`), West-Central (`BZC`), Southeast (`BZL`), and South (`BZS`); native, introduced, or extinct, but not doubtful. Without a mapped distribution, POWO's free-text range (e.g. `"Brazil (Bahia)"`) is checked instead. POWO covers vascular plants only, so it finds nothing for algae. **GBIF** (`"gbif"`). The genus is looked up among plants and algae only - the GBIF kingdoms Plantae (land plants, red and green algae), Chromista (brown algae, diatoms), and Protozoa (euglenids) - so a genus name shared with an animal (e.g. *Gracilaria*, both a red alga and a moth) resolves to the plant or alga. A single faceted search lists every name in the genus with type specimens collected in Brazil; for the FFB-missing names only, the specimens themselves are then retrieved, many names per request, and summarised. Types are filed in GBIF under their current identification - usually the typified name - which `GBIF_Specimen_names` shows. ### Arguments | Argument | Description | |---|---| | taxon | Character. A single genus name of plants or algae (e.g. `"Myrcia"`, `"Gracilaria"`). Fungi are not searched. | | sources | Character vector. Which kinds of evidence to use: `"powo"` (POWO distributions), `"gbif"` (Brazilian type specimens in GBIF), or both (default). | | powo_source | Character. Where POWO's data is read from: `"rWCVPdata"` (default; fast, local) or `"checklistbank"` (always current, slower). See Details. | | require_brazil_evidence | Logical. Applies to POWO. If `TRUE` (default), POWO names are only kept when POWO places the species in Brazil. Set to `FALSE` to also return POWO names missing from FFB regardless of distribution, for manual review. (GBIF names always have Brazil evidence: their types were collected there.) | | type_status | Character or `NULL`. Applies to 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. | | fetch_details | Logical. Applies to POWO with `powo_source = "checklistbank"`: if `TRUE` (default), each candidate's protologue citation is fetched (one request per name). With `"rWCVPdata"` it is always included. | | max_number | Numeric. Applies to POWO with `powo_source = "checklistbank"`: maximum number of names retrieved. Defaults to `5000`. | | version | Character. FFB dataset version to compare against. Defaults to `"latest"`. Passed to `flora_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 `"flora_species_gap"`. | | filename | Character. Name of the `.xlsx` file (without extension) to save. Defaults to `"flora_species_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 name in the genus that is absent from the current FFB checklist and reported by at least one source, sorted with the names reported by both sources first. Common columns: - Taxon_name, Authors: The name and its author citation. - Accepted_name: The accepted name (POWO's when available, else GBIF's). - Found_in: Which source(s) reported the name: `"POWO; GBIF"`, `"POWO"`, or `"GBIF"`. - Brazil_evidence: Logical; `TRUE` when POWO places the species in Brazil or it has Brazilian type specimens in GBIF. - In_FFB: Always `FALSE` (kept for clarity when combining with other tables). POWO columns (when `"powo"` is among `sources`; `NA` for names only in GBIF): - POWO_ID, POWO_Taxonomic_status, POWO_Accepted_name: The name's POWO (IPNI) identifier, status (e.g. `"Accepted"`, `"Synonym"`), and accepted name. - POWO_Year, POWO_Published_in: Year of publication and protologue citation. - POWO_Range: POWO's free-text range. - POWO_Distribution, POWO_Brazil_Areas: Every TDWG level-3 area of the accepted name's distribution, and only the Brazilian ones. - POWO_Brazil_Evidence, POWO_Evidence_Source: Whether POWO places the species in Brazil, and whether from the `"WCVP distribution"` or the `"POWO range text"`. - POWO_URL, IPNI_URL: Links to the name's POWO and IPNI pages. GBIF columns (when `"gbif"` is among `sources`; `NA` for names only in POWO): - GBIF_Key, GBIF_Taxonomic_status, GBIF_Accepted_name: The name's GBIF backbone key, status (e.g. `"ACCEPTED"`, `"DOUBTFUL"`), and accepted species. - GBIF_N_type_specimens, GBIF_Type_statuses: Number of type specimens collected in Brazil, and their type categories. - GBIF_Type_specimens: Up to ten specimens as herbarium, catalogue number, and type status (e.g. `"RB 00123 (Holotype)"`). - GBIF_Specimen_names: The names the types are filed under - usually the typified name, e.g. the basionym of a species. - GBIF_Collectors, GBIF_Years, GBIF_States: Collectors, collection years, and Brazilian states of those specimens. - GBIF_Published_in, GBIF_URL: Protologue citation, when GBIF has it, and a link to the name's GBIF page. ### Examples ```r # Species of Myrcia recorded in Brazil by POWO and/or with Brazilian type # specimens in GBIF, but missing from FFB gap <- flora_species_gap(taxon = "Myrcia") # POWO only, read live from ChecklistBank instead of the local WCVP copy gap_powo <- flora_species_gap(taxon = "Myrcia", sources = "powo", powo_source = "checklistbank") # An algal genus: GBIF type specimens only (POWO covers vascular plants) gap_algae <- flora_species_gap(taxon = "Gracilaria", sources = "gbif") # Stricter type evidence: holotypes and isotypes only gap_strict <- flora_species_gap(taxon = "Myrcia", type_status = c("Holotype", "Isotype")) ```