plot_html_map

Plot and save vouchered forest plot map as HTML

forplotR::plot_html_map()

Description

Generates an interactive and self-contained HTML map for forest plots following either the ForestPlots plot protocol or the MONITORA monitoring program, using Leaflet and based on vouchered tree data and plot coordinates. The function handles both standard ForestPlots layouts (1 ha or 0.5 ha plots defined by four corner vertices) and MONITORA layouts (Maltese cross design defined by a single central coordinate). It: (i) converts local subplot coordinates (X, Y) to geographic coordinates using geospatial interpolation from plot vertices or a central point; (ii) extracts metadata such as team name, plot name, and plot code from the input file; (iii) draws the plot boundary polygon or Maltese cross arms over selectable basemaps; (iv) colors tree points by collection status and palms (palms = yellow, collected = gray, missing = red); (v) embeds image carousels in specimen popups when matching voucher images are found in the specified folder; (vi) optionally performs a local herbarium lookup (e.g. JABOT DwC-A downloads) to attach direct “Herbarium image” links to each voucher when available; (vii) adds an interactive filter sidebar with checkboxes, multi-select inputs, and a search box for filtering by family, species, collection status, subplot, and presence of photos; (viii) displays informative popups for each tree, showing tag number, subplot, family, species, DBH, voucher code, herbarium image link (if found), and photos; and (x) saves the resulting map as a date-stamped standalone HTML file with multiple interactive Leaflet map options for easy sharing, archiving, or field consultation.

Arguments

Argument	Description
fp_file_path	Character. Path to the Excel file containing tree data.
input_type	One of `"field_sheet"`, `"fp_query_sheet"` or `"monitora"`. For `"fp_query_sheet"`, the function expects a ForestPlots Query Library export and converts it internally into a field-sheet-like table. For `"monitora"`, it expects a Maltese-cross layout.
vertex_coords	Data frame, path to an Excel file, or numeric vector. For `"field_sheet"` and `"fp_query_sheet"`, provide four plot corners (Latitude/Longitude). For `"monitora"`, provide a single central Latitude/Longitude used as the cross center. A numeric vector of length two is interpreted either as `c(lat, lon)` or as a named vector with elements `lat`/`latitude` and `lon`/`longitude`.
plot_size	Numeric. Total plot size in hectares (default is 1).
subplot_size	Numeric. Subplot size in meters (default is 10).
voucher_imgs	Character. Directory path where voucher images are stored. Subdirectories are assumed to be named after voucher IDs, each containing one or more image files.
filename	Character. Base name of the output HTML file (without extension). The function will prepend a date-stamped prefix and append `".html"` (default is `"plot_map"`).
station_name	Character or `NULL`. For `"monitora"` inputs, optionally filter or loop over one or more station names. When a vector of station names is given, the function calls itself once per station.
collector	Character. Optional fallback collector name used when compact voucher codes are provided (e.g. `"GCO1095"` without an explicit collector string).
herbaria_lookup	Logical. If `TRUE`, the function performs a local herbarium lookup and adds a `herbaria_link` column to the specimen data, building a minimal index from JABOT DwC-A downloads (via jabotR).
herbaria	Character vector or `NULL`. Herbarium codes to be used in the herbaria lookup, e.g. `c("RB","UPCB")`. When `herbaria_lookup = TRUE` this argument must be a non-empty vector; by default it is `NULL` and no herbaria search is performed unless the user explicitly supplies the herbarium codes.
jabot_cache_rds	Character. Path to an `.rds` file used to cache the JABOT-based index (keys and catalog numbers) between runs. Defaults to `"jabot_index.rds"` in the working directory.
jabot_force_refresh	Logical. If `TRUE`, forces rebuilding the JABOT-based index from the local DwC-A archives, ignoring any existing cache file.

Examples

vertex_df <- data.frame(
  Latitude = c(-3.123, -3.123, -3.125, -3.125),
  Longitude = c(-60.012, -60.010, -60.012, -60.010)
)

# Basic example (field_sheet)
plot_html_map(
  fp_file_path = "data/tree_data.xlsx",
  input_type = "field_sheet",
  vertex_coords = vertex_df,
  voucher_imgs = "voucher_imgs",
  filename = "plot_map"
)

# Example with herbaria lookup
plot_html_map(
  fp_file_path = "data/RUS_plot.xlsx",
  input_type = "field_sheet",
  vertex_coords = "data/vertices.xlsx",
  voucher_imgs = "voucher_imgs",
  collector = "G. C. Ottino",
  herbaria_lookup = TRUE,
  herbaria = c("RB", "UPCB"),
  filename = "rus_plot_map"
)

--- title: 'plot_html_map' description: 'Plot and save vouchered forest plot map as HTML' toc: true toc-depth: 3 --- ```{r} #| eval: false forplotR::plot_html_map() ``` ### Description Generates an interactive and self-contained HTML map for forest plots following either the [ForestPlots plot protocol](https://forestplots.net/) or the [](https://www.gov.br/icmbio/pt-br/assuntos/monitoramento/programa-monitora)MONITORA monitoring program, using Leaflet and based on vouchered tree data and plot coordinates. The function handles both standard ForestPlots layouts (1 ha or 0.5 ha plots defined by four corner vertices) and MONITORA layouts (Maltese cross design defined by a single central coordinate). It: (i) converts local subplot coordinates (X, Y) to geographic coordinates using geospatial interpolation from plot vertices or a central point; (ii) extracts metadata such as team name, plot name, and plot code from the input file; (iii) draws the plot boundary polygon or Maltese cross arms over selectable basemaps; (iv) colors tree points by collection status and palms (palms = yellow, collected = gray, missing = red); (v) embeds image carousels in specimen popups when matching voucher images are found in the specified folder; (vi) optionally performs a local herbarium lookup (e.g. JABOT DwC-A downloads) to attach direct “Herbarium image” links to each voucher when available; (vii) adds an interactive filter sidebar with checkboxes, multi-select inputs, and a search box for filtering by family, species, collection status, subplot, and presence of photos; (viii) displays informative popups for each tree, showing tag number, subplot, family, species, DBH, voucher code, herbarium image link (if found), and photos; and (x) saves the resulting map as a date-stamped standalone HTML file with multiple interactive Leaflet map options for easy sharing, archiving, or field consultation. ### Arguments | Argument | Description | |---|---| | fp_file_path | Character. Path to the Excel file containing tree data. | | input_type | One of `"field_sheet"`, `"fp_query_sheet"` or `"monitora"`. For `"fp_query_sheet"`, the function expects a ForestPlots Query Library export and converts it internally into a field-sheet-like table. For `"monitora"`, it expects a Maltese-cross layout. | | vertex_coords | Data frame, path to an Excel file, or numeric vector. For `"field_sheet"` and `"fp_query_sheet"`, provide four plot corners (Latitude/Longitude). For `"monitora"`, provide a single central Latitude/Longitude used as the cross center. A numeric vector of length two is interpreted either as `c(lat, lon)` or as a named vector with elements `lat`/`latitude` and `lon`/`longitude`. | | plot_size | Numeric. Total plot size in hectares (default is 1). | | subplot_size | Numeric. Subplot size in meters (default is 10). | | voucher_imgs | Character. Directory path where voucher images are stored. Subdirectories are assumed to be named after voucher IDs, each containing one or more image files. | | filename | Character. Base name of the output HTML file (without extension). The function will prepend a date-stamped prefix and append `".html"` (default is `"plot_map"`). | | station_name | Character or `NULL`. For `"monitora"` inputs, optionally filter or loop over one or more station names. When a vector of station names is given, the function calls itself once per station. | | collector | Character. Optional fallback collector name used when compact voucher codes are provided (e.g. `"GCO1095"` without an explicit collector string). | | herbaria_lookup | Logical. If `TRUE`, the function performs a local herbarium lookup and adds a `herbaria_link` column to the specimen data, building a minimal index from JABOT DwC-A downloads (via jabotR). | | herbaria | Character vector or `NULL`. Herbarium codes to be used in the herbaria lookup, e.g. `c("RB","UPCB")`. When `herbaria_lookup = TRUE` this argument must be a non-empty vector; by default it is `NULL` and no herbaria search is performed unless the user explicitly supplies the herbarium codes. | | jabot_cache_rds | Character. Path to an `.rds` file used to cache the JABOT-based index (keys and catalog numbers) between runs. Defaults to `"jabot_index.rds"` in the working directory. | | jabot_force_refresh | Logical. If `TRUE`, forces rebuilding the JABOT-based index from the local DwC-A archives, ignoring any existing cache file. | ### Examples ```r vertex_df <- data.frame( Latitude = c(-3.123, -3.123, -3.125, -3.125), Longitude = c(-60.012, -60.010, -60.012, -60.010) ) # Basic example (field_sheet) plot_html_map( fp_file_path = "data/tree_data.xlsx", input_type = "field_sheet", vertex_coords = vertex_df, voucher_imgs = "voucher_imgs", filename = "plot_map" ) # Example with herbaria lookup plot_html_map( fp_file_path = "data/RUS_plot.xlsx", input_type = "field_sheet", vertex_coords = "data/vertices.xlsx", voucher_imgs = "voucher_imgs", collector = "G. C. Ottino", herbaria_lookup = TRUE, herbaria = c("RB", "UPCB"), filename = "rus_plot_map" ) ```