reflora_indets

Retrieve indeterminate specimens from REFLORA collections

refloraR::reflora_indets()

Description

Retrieves occurrence records for indeterminate specimens (e.g., identified only to family or genus level) from the REFLORA Virtual Herbarium 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. All returned records include direct links to specimen images (column 'bibliographicCitation') and, when available, high-resolution download URLs (column 'associatedMedia').

Details

This function supports downloading and processing Darwin Core Archive (DwC-A) files directly from the REFLORA 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.
repatriated	Logical. If `FALSE`, skips downloading records from REFLORA-associated herbaria that have been repatriated. Default is `TRUE`. Use `reflora_summary()` to check which collections are repatriated.
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 REFLORA dwca files. If `NULL`, downloads fresh data.
updates	Logical. If `TRUE` (default), checks for updated DwC-A files from REFLORA.
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: `"reflora_indets"`.
filename	Character. Name of the output file (without extension). Default: `"reflora_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
reflora_indets(taxon = c("Fabaceae", "Ochnaceae"),
               level = "FAMILY",
               save = TRUE,
               dir = "reflora_indets",
               filename = "fabaceae_ochnaceae_records")

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

--- title: 'reflora_indets' description: 'Retrieve indeterminate specimens from REFLORA collections' toc: true toc-depth: 3 --- ```{r} #| eval: false refloraR::reflora_indets() ``` ### Description Retrieves occurrence records for indeterminate specimens (e.g., identified only to family or genus level) from the [REFLORA Virtual Herbarium](https://ipt.jbrj.gov.br/reflora/) 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. All returned records include direct links to specimen images (column `'bibliographicCitation'`) and, when available, high-resolution download URLs (column `'associatedMedia'`). ### Details This function supports downloading and processing Darwin Core Archive (DwC-A) files directly from the REFLORA 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. | | repatriated | Logical. If `FALSE`, skips downloading records from REFLORA-associated herbaria that have been repatriated. Default is `TRUE`. Use `reflora_summary()` to check which collections are repatriated. | | 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 REFLORA dwca files. If `NULL`, downloads fresh data. | | updates | Logical. If `TRUE` (default), checks for updated DwC-A files from REFLORA. | | 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: `"reflora_indets"`. | | filename | Character. Name of the output file (without extension). Default: `"reflora_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 reflora_indets(taxon = c("Fabaceae", "Ochnaceae"), level = "FAMILY", save = TRUE, dir = "reflora_indets", filename = "fabaceae_ochnaceae_records") # Filter by specific herbarium and state reflora_indets(taxon = "Fabaceae", herbarium = "RB", state = c("BA", "MG"), recordYear = c("1990", "2022")) ```