fp_herb_converter

Fill empty herbarium spreadsheet from forestplots-formatted data

forplotR::fp_herb_converter()

Description

Function to process data collected in the Forestplots format and convert it into a herbarium format. The default herbarium format is JABOT, but it also supports conversion to the Brahms and custom herbarium formats, where the user can specify the column names in column_map list. The function performs the following steps: (i) Reads the input forestplots field sheet template and herbarium datasets; (ii) Ensures all required metadata (e.g., majorarea, minorarea, lat, long) is correctly provided;(iii) Processes taxonomic, spatial, and additional metadata to fill the herbarium format sheet; (iv) Generates a new xlsx file with the converted data, saved in a directory named after the current date. This function automatically converts field codes from the Rainfor protocol (e.g., tree condition codes and light exposure codes) into their full descriptive meanings, and incorporates them into the final herbarium notes. For example, the code “A” is converted to “alive normal” (or “árvore viva normal” in Portuguese). These translations are integrated into a standardized descriptive text alongside other information extracted directly from the forestplots sheet, such as DBH, field notes, and subplot coordinates. For instance, a final note in English might read:

“Tree, 24.83cm DBH, with peeling bark, small buttress roots, bark with tiny reddish plates, crown completely exposed to vertical and lateral light in a 45 degree curve. Individual #3 in the subplot 1, x = 1.5m, y = 2.5m.”

The phrases “with peeling bark” and “crown completely exposed to vertical and lateral light…” are automatically generated from the Rainfor codes, while phrases such as “small buttress roots” and “bark with reddish plates” come from the original field notes recorded in the Forestplots sheet.The conversion of Rainfor codes and the construction of this descriptive text are supported in three languages: English, Portuguese, and Spanish, depending on the value set in the language argument.

Arguments

Argument	Description
herb_file_path	File path of the herbarium empty template dataset.
language	Language for output metadata. Default is “en”, options are “en”, “pt” and “es”.
herbarium_format	Format of the herbarium dataset. Default is “jabot”, additional options is “brahms”, “custom” herbarium format, where column names must be specified by the user.
country	Country where the data was collected. Default is “Brazil”.
majorarea	State where the data was collected.
minorarea	Municipality where the data was collected.
protectedarea	Name of the protected area (if applicable).
locnotes	Notes of the locality where the data was collected.
project	Project name or description (if applicable).
collector	Main collector name. If `'NULL'`, extract the ‘Team’ information of forestplots dataset. the first member of the team will be considered as the main collector.
addcoll	Character. Additional collector(s) name(s).If `'NULL'`, extract the additional members of the ‘Team’ in forestplots dataset.
lat	Latitude in decimal degrees of the collection site.
long	Longitude in decimal degrees of the collection site.
alt	Altitude in meters of the collection site. If `'NULL'`, extract the altitude from geographic coordinates dataset.
add_census_notes	If `'TRUE'`, census notes will be included in the herbarium sheet’s notes. If `'FALSE'`, census notes will be omitted.
dir	Pathway to the computer’s directory, where the file will be saved. The default is to create a directory named Results_filled_herbarium_sheet and the search results will be saved within a subfolder named after the current date.
filename	Name of the output file. Default is forestplot_to_herbarium_sheet.
forestplots_file_path	File path to the forestplots dataset.

Value

A data frame in herbarium format with the processed data from forestplots dataset.

Examples

fp_herb_converter <- function(fp_file_path = NULL,
                              herb_file_path = NULL,
                              language = "en",
                              herbarium_format = "jabot",
                              country = "Brazil",
                              majorarea = NULL,
                              minorarea = NULL,
                              protectedarea = NULL,
                              locnotes = NULL,
                              project = NULL,
                              collector = NULL,
                              addcoll = NULL,
                              lat = NULL,
                              long = NULL,
                              alt = NULL,
                              add_census_notes = TRUE,
                              dir = "Results_filled_herbarium_sheet",
                              filename =  "forestplot_to_herbarium_sheet")

--- title: 'fp_herb_converter' description: 'Fill empty herbarium spreadsheet from forestplots-formatted data' toc: true toc-depth: 3 --- ```{r} #| eval: false forplotR::fp_herb_converter() ``` ### Description Function to process data collected in the [Forestplots format](https://forestplots.net/) and convert it into a herbarium format. The default herbarium format is [JABOT](https://rb.jbrj.gov.br/v2/validarplanilha_externo.php), but it also supports conversion to the [Brahms](https://herbaria.plants.ox.ac.uk/bol/brahms/support/conifers) and custom herbarium formats, where the user can specify the column names in column_map list. The function performs the following steps: (i) Reads the input forestplots field sheet template and herbarium datasets; (ii) Ensures all required metadata (e.g., majorarea, minorarea, lat, long) is correctly provided;(iii) Processes taxonomic, spatial, and additional metadata to fill the herbarium format sheet; (iv) Generates a new xlsx file with the converted data, saved in a directory named after the current date. This function automatically converts field codes from the Rainfor protocol (e.g., tree condition codes and light exposure codes) into their full descriptive meanings, and incorporates them into the final herbarium notes. For example, the code "A" is converted to "alive normal" (or "árvore viva normal" in Portuguese). These translations are integrated into a standardized descriptive text alongside other information extracted directly from the forestplots sheet, such as DBH, field notes, and subplot coordinates. For instance, a final note in English might read: "Tree, 24.83cm DBH, with peeling bark, small buttress roots, bark with tiny reddish plates, crown completely exposed to vertical and lateral light in a 45 degree curve. Individual #3 in the subplot 1, x = 1.5m, y = 2.5m." The phrases "with peeling bark" and "crown completely exposed to vertical and lateral light..." are automatically generated from the Rainfor codes, while phrases such as "small buttress roots" and "bark with reddish plates" come from the original field notes recorded in the Forestplots sheet.The conversion of Rainfor codes and the construction of this descriptive text are supported in three languages: English, Portuguese, and Spanish, depending on the value set in the `language` argument. ### Arguments | Argument | Description | |---|---| | herb_file_path | File path of the herbarium empty template dataset. | | language | Language for output metadata. Default is "en", options are "en", "pt" and "es". | | herbarium_format | Format of the herbarium dataset. Default is "jabot", additional options is "brahms", "custom" herbarium format, where column names must be specified by the user. | | country | Country where the data was collected. Default is "Brazil". | | majorarea | State where the data was collected. | | minorarea | Municipality where the data was collected. | | protectedarea | Name of the protected area (if applicable). | | locnotes | Notes of the locality where the data was collected. | | project | Project name or description (if applicable). | | collector | Main collector name. If `'NULL'`, extract the 'Team' information of forestplots dataset. the first member of the team will be considered as the main collector. | | addcoll | Character. Additional collector(s) name(s).If `'NULL'`, extract the additional members of the 'Team' in forestplots dataset. | | lat | Latitude in decimal degrees of the collection site. | | long | Longitude in decimal degrees of the collection site. | | alt | Altitude in meters of the collection site. If `'NULL'`, extract the altitude from geographic coordinates dataset. | | add_census_notes | If `'TRUE'`, census notes will be included in the herbarium sheet's notes. If `'FALSE'`, census notes will be omitted. | | dir | Pathway to the computer's directory, where the file will be saved. The default is to create a directory named **Results_filled_herbarium_sheet** and the search results will be saved within a subfolder named after the current date. | | filename | Name of the output file. Default is **forestplot_to_herbarium_sheet**. | | forestplots_file_path | File path to the forestplots dataset. | ### Value A data frame in herbarium format with the processed data from forestplots dataset. ### Examples ```r fp_herb_converter <- function(fp_file_path = NULL, herb_file_path = NULL, language = "en", herbarium_format = "jabot", country = "Brazil", majorarea = NULL, minorarea = NULL, protectedarea = NULL, locnotes = NULL, project = NULL, collector = NULL, addcoll = NULL, lat = NULL, long = NULL, alt = NULL, add_census_notes = TRUE, dir = "Results_filled_herbarium_sheet", filename = "forestplot_to_herbarium_sheet") ```