jabot_missing

Missing species for a local herbarium within a target region

jabotR::jabot_missing()

Description

Identifies species listed in the Flora e Funga do Brasil (FFB) that are expected to occur in a target Brazilian state and/or municipality (geo) but are absent from a given JABOT-hosted herbarium (herbarium), regardless of where in Brazil that herbarium’s own specimens were collected. For each missing species, the function searches the pooled occurrence records of the entire JABOT network (all herbaria, or a subset given by network_herbaria) for existing vouchers collected within the target region, and produces:

Summary statistics (FFB species expected in the region, species already held by the herbarium, missing species, % missing, missing species with known collecting localities)
A ranked table of missing species, with the number of network vouchers and municipalities already known for each (collecting priority)
Missing species broken down by family
An interactive map of candidate collecting localities, built from network vouchers of the missing species within the region
A municipality-level heat map ranking collecting priority, i.e. which municipalities within the region already hold the most known vouchers of species still missing from the herbarium, to help target future collecting expeditions
A full, record-level table of every individual network voucher of the missing species found within the region (not aggregated by species), each linking out to the physical specimen (image/viewer page) when the source herbarium provides one
An HTML report (always generated) and optional PDF / PNG exports of individual figures

Details

Because the Flora e Funga do Brasil reports geographic distribution at the state level, the expected species checklist for the region is always resolved at the state(s) intersecting geo (a municipality is mapped to its state via the JABOT records found within it). The candidate collecting map, however, is restricted to actual vouchers falling within the municipalities/states supplied in geo.

The function follows the same synonym-resolution pipeline as jabot_gaps: taxon names recorded as synonyms in FFB are resolved to their accepted names via floraR::flora_search before comparison.

Arguments

Argument	Description
herbarium	Character. Acronym (in uppercase) of the target/local JABOT-hosted herbarium whose gaps are being assessed (e.g. `"HUEFS"`).
geo	Character vector. One or more Brazilian state names/acronyms and/or municipality names delimiting the region of interest (e.g. `"Bahia"`, `"BA"`, or `c("Feira de Santana", "Tucano")`).
network_herbaria	Character vector or `NULL`. Restricts the pooled network sample used to search for candidate collecting points to these herbarium acronyms. `NULL` (default) uses `all` JABOT-hosted herbaria.
jabot_path	Character or `NULL`. Path to a directory holding previously downloaded JABOT DwC-A files (created by `jabot_download`), shared by both the target herbarium and the network pool. When `NULL` (default) records are downloaded automatically.
format	Character vector. Static formats for saving individual figures: `"pdf"`, `"png"`, or both. The HTML report is always generated.
fig_width	Numeric. Width of saved figures in inches. Default `10`.
fig_height	Numeric. Height of saved figures in inches. Default `6`.
open_report	Logical. If `TRUE` (default), opens the HTML report in the default browser after rendering.
verbose	Logical. If `TRUE` (default), progress messages are printed.
dir	Character. Output directory. Defaults to `"<herbarium>_missing_<geo>"`.

Value

Invisibly returns a named list with all computed data frames and ggplot2 objects. The HTML report (and optional figures) are written to dir.

Examples

# Missing species expected in Bahia state but absent from HUEFS herbarium
jabot_missing(herbarium = "HUEFS",
                 geo = "Bahia",
                 format = "pdf")

# Restrict the candidate-locality search to a couple of municipalities
jabot_missing(herbarium = "HUEFS",
                 geo = c("Feira de Santana", "Tucano"),
                 jabot_path = "jabot_download")

--- title: 'jabot_missing' description: 'Missing species for a local herbarium within a target region' toc: true toc-depth: 3 --- ```{r} #| eval: false jabotR::jabot_missing() ``` ### Description Identifies species listed in the [Flora e Funga do Brasil (FFB)](https://floradobrasil.jbrj.gov.br/consulta/) that are expected to occur in a target Brazilian state and/or municipality (`geo`) but are absent from a given JABOT-hosted herbarium (`herbarium`), regardless of where in Brazil that herbarium's own specimens were collected. For each missing species, the function searches the pooled occurrence records of the entire JABOT network (all herbaria, or a subset given by `network_herbaria`) for existing vouchers collected within the target region, and produces: - Summary statistics (FFB species expected in the region, species already held by the herbarium, missing species, % missing, missing species with known collecting localities) - A ranked table of missing species, with the number of network vouchers and municipalities already known for each (collecting priority) - Missing species broken down by family - An interactive map of candidate collecting localities, built from network vouchers of the missing species within the region - A municipality-level heat map ranking collecting priority, i.e. which municipalities within the region already hold the most known vouchers of species still missing from the herbarium, to help target future collecting expeditions - A full, record-level table of every individual network voucher of the missing species found within the region (not aggregated by species), each linking out to the physical specimen (image/viewer page) when the source herbarium provides one - An HTML report (always generated) and optional PDF / PNG exports of individual figures ### Details Because the Flora e Funga do Brasil reports geographic distribution at the state level, the expected species checklist for the region is always resolved at the state(s) intersecting `geo` (a municipality is mapped to its state via the JABOT records found within it). The candidate collecting map, however, is restricted to actual vouchers falling within the municipalities/states supplied in `geo`. The function follows the same synonym-resolution pipeline as `jabot_gaps`: taxon names recorded as synonyms in FFB are resolved to their accepted names via `floraR::flora_search` before comparison. ### Arguments | Argument | Description | |---|---| | herbarium | Character. Acronym (in uppercase) of the target/local JABOT-hosted herbarium whose gaps are being assessed (e.g. `"HUEFS"`). | | geo | Character vector. One or more Brazilian state names/acronyms and/or municipality names delimiting the region of interest (e.g. `"Bahia"`, `"BA"`, or `c("Feira de Santana", "Tucano")`). | | network_herbaria | Character vector or `NULL`. Restricts the pooled network sample used to search for candidate collecting points to these herbarium acronyms. `NULL` (default) uses `all` JABOT-hosted herbaria. | | jabot_path | Character or `NULL`. Path to a directory holding previously downloaded JABOT DwC-A files (created by `jabot_download`), shared by both the target herbarium and the network pool. When `NULL` (default) records are downloaded automatically. | | format | Character vector. Static formats for saving individual figures: `"pdf"`, `"png"`, or both. The HTML report is always generated. | | fig_width | Numeric. Width of saved figures in inches. Default `10`. | | fig_height | Numeric. Height of saved figures in inches. Default `6`. | | open_report | Logical. If `TRUE` (default), opens the HTML report in the default browser after rendering. | | verbose | Logical. If `TRUE` (default), progress messages are printed. | | dir | Character. Output directory. Defaults to `"<herbarium>_missing_<geo>"`. | ### Value Invisibly returns a named list with all computed data frames and ggplot2 objects. The HTML report (and optional figures) are written to `dir`. ### Examples ```r # Missing species expected in Bahia state but absent from HUEFS herbarium jabot_missing(herbarium = "HUEFS", geo = "Bahia", format = "pdf") # Restrict the candidate-locality search to a couple of municipalities jabot_missing(herbarium = "HUEFS", geo = c("Feira de Santana", "Tucano"), jabot_path = "jabot_download") ```