plot_for_balance

Generate forest plot specimen map and collection balance

forplotR::plot_for_balance()

Description

Processes field data collected using the ForestPlots.net format (field sheets or Query Library output) or Monitora program layouts, and generates a specimen map with collection status and spatial distribution of individuals across subplots. It creates a PDF report with plot-level and subplot-level maps, an optional above-ground biomass summary, and an Excel spreadsheet summarizing the percentage of collected specimens per subplot. The function performs the following steps: (i) validates all input arguments and checks/creates output folders; (ii) reads the input sheet, extracts metadata (team, plot name, plot code), and cleans the data; (iii) normalizes and cleans coordinate and diameter values, computing global plot coordinates; (iv) builds a PDF report including plot metadata, the main map, collected and uncollected specimen maps, an optional palm map and navigable subplot maps; (v) optionally generates a spreadsheet with the collection percentage per subplot (including totals), separating palms from non-palms.

Arguments

Argument	Description
fp_file_path	Path to the Excel file (field or query sheet) in ForestPlots format.
language	Character. One of en (english), pt (portuguese), es (spanish), ma (mandarin) (default = en)
input_type	Character. One of `"field_sheet"`, `"fp_query_sheet"` or `"monitora"`. Specifies the type/layout of the input file.
plot_size	Total plot size in hectares (default = 1).
subplot_size	Side length of each subplot in meters (default = 10).
highlight_palms	Logical. If `TRUE`, highlights Arecaceae individuals in the plots.
station_name	Optional station identifier used when `input_type = "monitora"`. If a vector of length > 1, the function will recursively generate a report and summary spreadsheet for each station.
plot_name	Optional plot name. If provided, overrides the plot name extracted from the input file metadata.
plot_code	Optional plot code. If provided, overrides the plot code extracted from the input file metadata.
team	Optional team or PI name. If provided, overrides the team extracted from the input file metadata.
calc_agb	Logical. If `TRUE`, calculates above-ground biomass (AGB) using `BiomasaFP` and adds a summary section to the PDF report.
trees_csv	Optional. Tree-level measurement data used for above-ground biomass (AGB) estimation. Can be either a data frame or a file path (character) to the “Data.csv” file downloaded via ForestPlots “Advanced Search”.
wd_csv	Optional wood density file, with wood density for each individual tree (by PlotViewID) downloaded from the ForestPlots “Query Library”. Can be a data frame or a file path.
md_csv	Optional metadata file downloaded from the ForestPlots “Query Library”. Can be a data frame or a file path.
dir	Directory path where output will be saved (default is `"Results_map_plot"`). A date-stamped subfolder will be created inside this directory.
filename	Basename for output files (without extension).

Value

Invisibly returns NULL. Called for its side effects of generating a PDF report and an Excel file summarizing specimen collection statistics per subplot.

Examples

plot_for_balance(fp_file_path = "data/forestplot.xlsx",
                 language = c("en", "pt", "es", "ma"),
                 input_type = c("field_sheet", "fp_query_sheet", "monitora"),
                 plot_size = 1,
                 subplot_size = 10,
                 highlight_palms = TRUE,
                 station_name = NULL,
                 plot_name = NULL,
                 plot_code = NULL,
                 team = NULL,
                 calc_agb = FALSE,
                 trees_csv = NULL,
                 md_csv = NULL,
                 wd_csv = NULL,
                 dir = "Results_map_plot",
                 filename = "plot_specimen")

--- title: 'plot_for_balance' description: 'Generate forest plot specimen map and collection balance' toc: true toc-depth: 3 --- ```{r} #| eval: false forplotR::plot_for_balance() ``` ### Description Processes field data collected using the [ForestPlots.net](https://forestplots.net/) format (field sheets or Query Library output) or [](https://www.gov.br/icmbio/pt-br/assuntos/monitoramento/programa-monitora)Monitora program layouts, and generates a specimen map with collection status and spatial distribution of individuals across subplots. It creates a PDF report with plot-level and subplot-level maps, an optional above-ground biomass summary, and an Excel spreadsheet summarizing the percentage of collected specimens per subplot. The function performs the following steps: (i) validates all input arguments and checks/creates output folders; (ii) reads the input sheet, extracts metadata (team, plot name, plot code), and cleans the data; (iii) normalizes and cleans coordinate and diameter values, computing global plot coordinates; (iv) builds a PDF report including plot metadata, the main map, collected and uncollected specimen maps, an optional palm map and navigable subplot maps; (v) optionally generates a spreadsheet with the collection percentage per subplot (including totals), separating palms from non-palms. ### Arguments | Argument | Description | |---|---| | fp_file_path | Path to the Excel file (field or query sheet) in ForestPlots format. | | language | Character. One of en (english), pt (portuguese), es (spanish), ma (mandarin) (default = en) | | input_type | Character. One of `"field_sheet"`, `"fp_query_sheet"` or `"monitora"`. Specifies the type/layout of the input file. | | plot_size | Total plot size in hectares (default = 1). | | subplot_size | Side length of each subplot in meters (default = 10). | | highlight_palms | Logical. If `TRUE`, highlights Arecaceae individuals in the plots. | | station_name | Optional station identifier used when `input_type = "monitora"`. If a vector of length > 1, the function will recursively generate a report and summary spreadsheet for each station. | | plot_name | Optional plot name. If provided, overrides the plot name extracted from the input file metadata. | | plot_code | Optional plot code. If provided, overrides the plot code extracted from the input file metadata. | | team | Optional team or PI name. If provided, overrides the team extracted from the input file metadata. | | calc_agb | Logical. If `TRUE`, calculates above-ground biomass (AGB) using `BiomasaFP` and adds a summary section to the PDF report. | | trees_csv | Optional. Tree-level measurement data used for above-ground biomass (AGB) estimation. Can be either a data frame or a file path (character) to the "Data.csv" file downloaded via ForestPlots "Advanced Search". | | wd_csv | Optional wood density file, with wood density for each individual tree (by PlotViewID) downloaded from the ForestPlots "Query Library". Can be a data frame or a file path. | | md_csv | Optional metadata file downloaded from the ForestPlots "Query Library". Can be a data frame or a file path. | | dir | Directory path where output will be saved (default is `"Results_map_plot"`). A date-stamped subfolder will be created inside this directory. | | filename | Basename for output files (without extension). | ### Value Invisibly returns `NULL`. Called for its side effects of generating a PDF report and an Excel file summarizing specimen collection statistics per subplot. ### Examples ```r plot_for_balance(fp_file_path = "data/forestplot.xlsx", language = c("en", "pt", "es", "ma"), input_type = c("field_sheet", "fp_query_sheet", "monitora"), plot_size = 1, subplot_size = 10, highlight_palms = TRUE, station_name = NULL, plot_name = NULL, plot_code = NULL, team = NULL, calc_agb = FALSE, trees_csv = NULL, md_csv = NULL, wd_csv = NULL, dir = "Results_map_plot", filename = "plot_specimen") ```