jabot_identify

Suggest identifications for indeterminate specimens from duplicates in JABOT and REFLORA

jabotR::jabot_identify()

Description

Looks for identifications for the indeterminate specimens of a herbarium hosted in the JABOT network or in the Reflora Virtual Herbarium. A specimen is considered indeterminate when it lacks the family, the genus or the specific epithet. The records of the JABOT network and of REFLORA (or subsets of their herbaria) are standardized with barRoso::barroso_std(), which flags blocks of duplicates (same collector and collector number, or same species, collector and date when the number is missing; see barRoso::barroso_flag_duplicates()). For each indeterminate specimen, the duplicates held by other herbaria are inspected to find out whether any of them was already identified, and to which level. The results are summarized in a self-contained, interactive HTML report.

Details

The herbarium to be investigated (herbarium) can be any JABOT-hosted herbarium or, when it is not hosted in JABOT, any herbarium available in REFLORA, which also gathers Brazilian specimens held by international herbaria (e.g. "NY", "K", "P", "US"). When it is available in both, the JABOT records are used. The duplicates are searched in the other herbaria of JABOT (jabot = TRUE) and of REFLORA (reflora = TRUE). The databases are first checked in jabot_path and reflora_path (or in the default folders jabot_download and reflora_download) and only what is missing or outdated is downloaded, with jabot_download() and refloraR::reflora_download(). REFLORA herbaria that are already in the JABOT data are not used from REFLORA (they are not even downloaded), so no specimen is counted twice, and the source of each record (JABOT or REFLORA) is kept. The records are read with jabot_parse() and refloraR::reflora_parse(), one herbarium at a time, keeping in memory only the records that may be duplicates of an indeterminate specimen, and then standardized with barRoso.

The analysis includes the number of indeterminate specimens of the herbarium, how many of them can be matched with duplicates in other herbaria, how many have a duplicate with a better identification (to species, genus or family), the suggested identification and its source (data source, herbarium, catalog number and, when available, links to both the indeterminate specimen and the duplicate that identifies it, so that both images can be compared), the herbaria that most contribute with identifications, indeterminate specimens by family, conflicts between the identification of the specimen and of its duplicates, graphical summaries and an HTML report.

A duplicate is considered a candidate identification when it fills at least one rank missing in the indeterminate specimen (family, genus or specific epithet). Candidates that disagree with ranks already present in the specimen (e.g. a different family) are reported as conflicts and never suggested. Only duplicates held by herbaria other than herbarium are considered. Specimens without a known collector and a collector number (or, for those identified at least to genus, a complete collection date) cannot be matched with duplicates and are counted separately.

The determiner (identifiedBy) and the date of identification (dateIdentified) of the indeterminate specimen and of each duplicate are included in the tables, to help deciding which identification to trust when they conflict.

The suggested identifications come from the records of other herbaria and should be checked, preferably against the specimen images, before being adopted.

Arguments

Argument	Description
herbarium	Character. A single herbarium acronym in uppercase (e.g., `"RB"`) whose indeterminate specimens will be investigated. It can be hosted in JABOT or, otherwise, in REFLORA (e.g., `"HUEFS"`).
taxon	Character vector. Family and/or genus names to restrict the indeterminate specimens of `herbarium` (e.g., `"Fabaceae"` or `c("Inga", "Mimosa")`). Specimens without any family or genus cannot match a `taxon`. Use `NULL` (default) to analyse all indeterminate specimens.
jabot	Logical. If `TRUE` (default), searches for duplicates in the herbaria of the JABOT network.
network_herbaria	Character vector. JABOT herbarium acronyms to restrict the JABOT records searched for duplicates. `NULL` (default) uses all JABOT-hosted herbaria.
reflora	Logical. If `TRUE` (default), also searches for duplicates in the herbaria of REFLORA, including the international ones.
reflora_herbaria	Character vector. REFLORA herbarium acronyms to restrict the REFLORA records searched for duplicates (e.g., `c("NY", "K", "P", "US")`). `NULL` (default) uses all REFLORA herbaria. Use `refloraR::reflora_summary()` to see them.
jabot_path	Character. Path to existing JABOT DwC-A files. If `NULL` (default), the files are downloaded automatically.
reflora_path	Character. Path to existing REFLORA DwC-A files. If `NULL` (default), the files are downloaded automatically.
format	Character vector. Static formats used to save the individual figures: `"pdf"`, `"png"`, or both. The HTML report is always generated. Defaults to `NULL` (figures are not saved separately).
fig_width, fig_height	Numeric. Dimensions (in inches) of saved figures.
open_report	Logical. If `TRUE` (default), opens the HTML report in the default browser after rendering (interactive sessions only).
verbose	Logical. If `TRUE` (default), prints progress messages.
dir	Character. Output directory. Defaults to `"<herbarium>_identify"`.

Value

Invisibly, a named list with the computed objects, among them indets (one row per indeterminate specimen, with the outcome and the suggested identification), suggestions (one row per specimen and duplicate held by another herbarium), the summary tables and the figures. The HTML report and two CSV files (<herbarium>_identify_indets.csv and <herbarium>_identify_suggestions.csv) are saved in dir.

Examples

# All indeterminate specimens of RB, compared with JABOT and REFLORA
jabot_identify(herbarium = "RB")

# Only indeterminate Fabaceae and Inga, reusing downloaded files
jabot_identify(herbarium = "RB",
               taxon = c("Fabaceae", "Inga"),
               jabot_path = "jabot_download",
               reflora_path = "reflora_download")

# Herbarium available only in REFLORA, compared with international herbaria
jabot_identify(herbarium = "HUEFS",
               jabot = FALSE,
               reflora_herbaria = c("NY", "K", "P", "US"))

# Restrict the herbaria searched for duplicates
jabot_identify(herbarium = "RB",
               network_herbaria = c("MBM", "UPCB", "FURB"),
               reflora_herbaria = c("NY", "HUEFS"),
               jabot_path = "jabot_download",
               reflora_path = "reflora_download")

--- title: 'jabot_identify' description: 'Suggest identifications for indeterminate specimens from duplicates in JABOT and REFLORA' toc: true toc-depth: 3 --- ```{r} #| eval: false jabotR::jabot_identify() ``` ### Description Looks for identifications for the indeterminate specimens of a herbarium hosted in the [JABOT](https://ipt.jbrj.gov.br/jabot) network or in the [Reflora Virtual Herbarium](https://ipt.jbrj.gov.br/reflora/). A specimen is considered indeterminate when it lacks the family, the genus or the specific epithet. The records of the JABOT network and of REFLORA (or subsets of their herbaria) are standardized with `barRoso::barroso_std()`, which flags blocks of duplicates (same collector and collector number, or same species, collector and date when the number is missing; see `barRoso::barroso_flag_duplicates()`). For each indeterminate specimen, the duplicates held by other herbaria are inspected to find out whether any of them was already identified, and to which level. The results are summarized in a self-contained, interactive HTML report. ### Details The herbarium to be investigated (`herbarium`) can be any JABOT-hosted herbarium or, when it is not hosted in JABOT, any herbarium available in REFLORA, which also gathers Brazilian specimens held by international herbaria (e.g. `"NY"`, `"K"`, `"P"`, `"US"`). When it is available in both, the JABOT records are used. The duplicates are searched in the other herbaria of JABOT (`jabot = TRUE`) and of REFLORA (`reflora = TRUE`). The databases are first checked in `jabot_path` and `reflora_path` (or in the default folders `jabot_download` and `reflora_download`) and only what is missing or outdated is downloaded, with `jabot_download()` and `refloraR::reflora_download()`. REFLORA herbaria that are already in the JABOT data are not used from REFLORA (they are not even downloaded), so no specimen is counted twice, and the source of each record (JABOT or REFLORA) is kept. The records are read with `jabot_parse()` and `refloraR::reflora_parse()`, one herbarium at a time, keeping in memory only the records that may be duplicates of an indeterminate specimen, and then standardized with barRoso. The analysis includes the number of indeterminate specimens of the herbarium, how many of them can be matched with duplicates in other herbaria, how many have a duplicate with a better identification (to species, genus or family), the suggested identification and its source (data source, herbarium, catalog number and, when available, links to both the indeterminate specimen and the duplicate that identifies it, so that both images can be compared), the herbaria that most contribute with identifications, indeterminate specimens by family, conflicts between the identification of the specimen and of its duplicates, graphical summaries and an HTML report. A duplicate is considered a candidate identification when it fills at least one rank missing in the indeterminate specimen (family, genus or specific epithet). Candidates that disagree with ranks already present in the specimen (e.g. a different family) are reported as conflicts and never suggested. Only duplicates held by herbaria other than `herbarium` are considered. Specimens without a known collector and a collector number (or, for those identified at least to genus, a complete collection date) cannot be matched with duplicates and are counted separately. The determiner (`identifiedBy`) and the date of identification (`dateIdentified`) of the indeterminate specimen and of each duplicate are included in the tables, to help deciding which identification to trust when they conflict. The suggested identifications come from the records of other herbaria and should be checked, preferably against the specimen images, before being adopted. ### Arguments | Argument | Description | |---|---| | herbarium | Character. A single herbarium acronym in uppercase (e.g., `"RB"`) whose indeterminate specimens will be investigated. It can be hosted in JABOT or, otherwise, in REFLORA (e.g., `"HUEFS"`). | | taxon | Character vector. Family and/or genus names to restrict the indeterminate specimens of `herbarium` (e.g., `"Fabaceae"` or `c("Inga", "Mimosa")`). Specimens without any family or genus cannot match a `taxon`. Use `NULL` (default) to analyse all indeterminate specimens. | | jabot | Logical. If `TRUE` (default), searches for duplicates in the herbaria of the JABOT network. | | network_herbaria | Character vector. JABOT herbarium acronyms to restrict the JABOT records searched for duplicates. `NULL` (default) uses all JABOT-hosted herbaria. | | reflora | Logical. If `TRUE` (default), also searches for duplicates in the herbaria of REFLORA, including the international ones. | | reflora_herbaria | Character vector. REFLORA herbarium acronyms to restrict the REFLORA records searched for duplicates (e.g., `c("NY", "K", "P", "US")`). `NULL` (default) uses all REFLORA herbaria. Use `refloraR::reflora_summary()` to see them. | | jabot_path | Character. Path to existing JABOT DwC-A files. If `NULL` (default), the files are downloaded automatically. | | reflora_path | Character. Path to existing REFLORA DwC-A files. If `NULL` (default), the files are downloaded automatically. | | format | Character vector. Static formats used to save the individual figures: `"pdf"`, `"png"`, or both. The HTML report is always generated. Defaults to `NULL` (figures are not saved separately). | | fig_width, fig_height | Numeric. Dimensions (in inches) of saved figures. | | open_report | Logical. If `TRUE` (default), opens the HTML report in the default browser after rendering (interactive sessions only). | | verbose | Logical. If `TRUE` (default), prints progress messages. | | dir | Character. Output directory. Defaults to `"<herbarium>_identify"`. | ### Value Invisibly, a named list with the computed objects, among them `indets` (one row per indeterminate specimen, with the outcome and the suggested identification), `suggestions` (one row per specimen and duplicate held by another herbarium), the summary tables and the figures. The HTML report and two CSV files (`<herbarium>_identify_indets.csv` and `<herbarium>_identify_suggestions.csv`) are saved in `dir`. ### Examples ```r # All indeterminate specimens of RB, compared with JABOT and REFLORA jabot_identify(herbarium = "RB") # Only indeterminate Fabaceae and Inga, reusing downloaded files jabot_identify(herbarium = "RB", taxon = c("Fabaceae", "Inga"), jabot_path = "jabot_download", reflora_path = "reflora_download") # Herbarium available only in REFLORA, compared with international herbaria jabot_identify(herbarium = "HUEFS", jabot = FALSE, reflora_herbaria = c("NY", "K", "P", "US")) # Restrict the herbaria searched for duplicates jabot_identify(herbarium = "RB", network_herbaria = c("MBM", "UPCB", "FURB"), reflora_herbaria = c("NY", "HUEFS"), jabot_path = "jabot_download", reflora_path = "reflora_download") ```