jabot_indets

Retrieve indeterminate specimens from JABOT

jabotR::jabot_indets()

Description

Retrieve occurrence records for indeterminate specimens (e.g., identified only to family or genus level) from the JABOT hosted by the Rio de Janeiro Botanical Garden. The function automatically downloads and parses Darwin Core Archive (DwC-A) files, applies optional filters by taxon, herbarium, state, and year, and exports the results if desired.

Details

This function supports downloading and processing Darwin Core Archive (DwC-A) files directly from the JABOT repository. It allows for flexible filtering by taxon, herbarium, locality (Brazilian states), and collection year(s). The level parameter enables filtering for indeterminate records such as those identified only to FAMILY or GENUS rank. The function uses helper functions like .arg_check_herbarium() and .filter_occur_df() to validate inputs and refine the occurrence records. If path is not provided, the function will automatically manage downloading and storing fresh DwC-A archives.

Arguments

Argument	Description
level	Character vector. Filter by taxonomic level. Accepted values: `"FAMILY"`, `"GENUS"`, or both. Defaults to `NULL` to include all indeterminate ranks.
herbarium	Character vector. Herbarium codes (e.g., `"RB"`, `"SP"`) in uppercase. Use `NULL` to include all herbaria.
taxon	Character vector. Specific taxon names to filter by (e.g., `"Fabaceae"`).
state	Character vector. Brazilian state full name or abbreviations (e.g., `"BA"`, `"SP"`) to filter by locality.
recordYear	Character or numeric vector. A single year (e.g., `"2001"`) or a range (e.g., `c("2000", "2022")`).
reorder	Character vector. Reorder output by columns. Defaults to: `c("herbarium", "taxa", "collector", "area", "year")`.
path	Character. Path to existing JABOT dwca files. If `NULL`, downloads fresh data.
updates	Logical. If `TRUE` (default), checks for updated DwC-A files from JABOT.
verbose	Logical. If `TRUE` (default), prints progress messages to the console.
save	Logical. If `TRUE` (default), saves the results to a CSV file.
dir	Character. Directory path to save output files. Default: `"jabot_indets"`.
filename	Character. Name of the output file (without extension). Default: `"jabot_indets_search"`.

Value

A data.frame containing filtered specimen records for the selected indeterminate specimens and criteria. If save = TRUE, a CSV file with the results will be written to the specified dir, and a log.txt file will be created or appended in the same directory summarizing the download session and key statistics (total records, breakdowns by herbarium, family, genus, country, and state).

Examples

# Retrieve indeterminate records for Fabaceae and Ochnaceae from all herbaria
jabot_indets(taxon = c("Fabaceae", "Ochnaceae"),
             level = "FAMILY",
             save = TRUE,
             dir = "jabot_indets",
             filename = "fabaceae_ochnaceae_records")

# Filter by specific herbarium and state
jabot_indets(taxon = "Fabaceae",
             herbarium = "RB",
             state = c("BA", "MG"),
             recordYear = c("1990", "2022"))

--- title: 'jabot_indets' description: 'Retrieve indeterminate specimens from JABOT' toc: true toc-depth: 3 --- ```{r} #| eval: false jabotR::jabot_indets() ``` ### Description Retrieve occurrence records for indeterminate specimens (e.g., identified only to family or genus level) from the [JABOT](https://ipt.jbrj.gov.br/jabot) hosted by the [Rio de Janeiro Botanical Garden](https://www.gov.br/jbrj/pt-br). The function automatically downloads and parses Darwin Core Archive (DwC-A) files, applies optional filters by taxon, herbarium, state, and year, and exports the results if desired. ### Details This function supports downloading and processing Darwin Core Archive (DwC-A) files directly from the JABOT repository. It allows for flexible filtering by taxon, herbarium, locality (Brazilian states), and collection year(s). The `level` parameter enables filtering for indeterminate records such as those identified only to FAMILY or GENUS rank. The function uses helper functions like `.arg_check_herbarium()` and `.filter_occur_df()` to validate inputs and refine the occurrence records. If `path` is not provided, the function will automatically manage downloading and storing fresh DwC-A archives. ### Arguments | Argument | Description | |---|---| | level | Character vector. Filter by taxonomic level. Accepted values: `"FAMILY"`, `"GENUS"`, or both. Defaults to `NULL` to include all indeterminate ranks. | | herbarium | Character vector. Herbarium codes (e.g., `"RB"`, `"SP"`) in uppercase. Use `NULL` to include all herbaria. | | taxon | Character vector. Specific taxon names to filter by (e.g., `"Fabaceae"`). | | state | Character vector. Brazilian state full name or abbreviations (e.g., `"BA"`, `"SP"`) to filter by locality. | | recordYear | Character or numeric vector. A single year (e.g., `"2001"`) or a range (e.g., `c("2000", "2022")`). | | reorder | Character vector. Reorder output by columns. Defaults to: `c("herbarium", "taxa", "collector", "area", "year")`. | | path | Character. Path to existing JABOT dwca files. If `NULL`, downloads fresh data. | | updates | Logical. If `TRUE` (default), checks for updated DwC-A files from JABOT. | | verbose | Logical. If `TRUE` (default), prints progress messages to the console. | | save | Logical. If `TRUE` (default), saves the results to a CSV file. | | dir | Character. Directory path to save output files. Default: `"jabot_indets"`. | | filename | Character. Name of the output file (without extension). Default: `"jabot_indets_search"`. | ### Value A `data.frame` containing filtered specimen records for the selected indeterminate specimens and criteria. If `save = TRUE`, a CSV file with the results will be written to the specified `dir`, and a `log.txt` file will be created or appended in the same directory summarizing the download session and key statistics (total records, breakdowns by herbarium, family, genus, country, and state). ### Examples ```r # Retrieve indeterminate records for Fabaceae and Ochnaceae from all herbaria jabot_indets(taxon = c("Fabaceae", "Ochnaceae"), level = "FAMILY", save = TRUE, dir = "jabot_indets", filename = "fabaceae_ochnaceae_records") # Filter by specific herbarium and state jabot_indets(taxon = "Fabaceae", herbarium = "RB", state = c("BA", "MG"), recordYear = c("1990", "2022")) ```