All about aRboretum

Introduction

aRboretum is an integrated R package designed to automate the production of botanical collection labels, from taxonomic data extraction to interactive web labels and print-ready QR codes. It can be used for arboreta, botanic gardens, educational trails, and other living plant collections.

The package offers:

multilingual output in Portuguese, English, French, and Spanish;
synonym resolution and integration of data from Flora e Funga do Brasil (FFB) and the World Checklist of Vascular Plants (WCVP), the backbone of Plants of the World Online (POWO);
global conservation status from the IUCN Red List;
browser-based guides to review the retrieved data and edit the species phrases;
interactive HTML labels with species information, text-to-speech, distribution maps, photo slideshows, and optional personal audio recordings;
a searchable minisite index linking all generated labels;
printable QR-code labels in different layouts;
one flexible additional language slot for community-based accessibility through add_lang.

All functions are designed to work together. This vignette provides a technical overview of the package workflow, main arguments, expected data structure, and common customisation options.

Installation

aRboretum depends on two packages that are not on CRAN, so install them first:

rWCVPdata, which provides the World Checklist of Vascular Plants data and is distributed through its own repository;
floraR, which downloads and parses the Flora e Funga do Brasil dataset used by arboretum_data().

if (!requireNamespace("rWCVPdata", quietly = TRUE)) {
  install.packages("rWCVPdata",
                   repos = c(
                     "https://matildabrown.github.io/drat",
                     "https://cloud.r-project.org"
                   )
  )
}

if (!requireNamespace("BiocManager", quietly = TRUE))
  install.packages("BiocManager")

# Install the development version of floraR from GitHub,
# together with its required dependencies
BiocManager::install("DBOSlab/floraR", dependencies = TRUE)

Then install the development version of aRboretum from GitHub:

# Install the development version of aRboretum from GitHub,
# together with its required dependencies
BiocManager::install("DBOSlab/aRboretum", dependencies = TRUE)

library(aRboretum)

Optional: IUCN Red List API token

By default, IUCN Red List categories are retrieved from the IUCN Red List checklist mirrored by GBIF, which requires no registration. To query the official IUCN Red List API instead, install the rredlist package, request a free API token, and store it in your .Renviron file:

install.packages("rredlist")
usethis::edit_r_environ()   # add the line: IUCN_REDLIST_KEY=your_token

Internal data structures

The internal translation dictionary

The package contains an internal translation table used to build species descriptions in the built-in languages. It includes terms and sentence fragments related to:

taxonomy;
endemism and establishment means;
phytogeographic domains and vegetation types;
IUCN categories;
genus diversity notes;
sentence-building connectors.

The helper functions .tr_dict() and .phrase_generator() use this dictionary to produce natural-language species summaries.

Botanical regions mapping

The package also relies on an internal mapping between botanical regions (the level-3 areas of the World Geographical Scheme for Recording Plant Distributions used by WCVP), countries, and continents, with their names in the four built-in languages. This allows WCVP distribution data to be converted into readable geographic statements and distribution maps.

Expected data structure

Most functions rely on the standard species data file written by arboretum_data() and completed by arboretum_phrases(). Its columns are:

# Written by arboretum_data()
family
genus
taxonName
scientificNameAuthorship
FFB.vernacularName
country
endemism                  # endemism in Brazil
botanical_country
introduced_to
FFB.establishmentMeans
FFB.stateProvince
FFB.phytogeographicDomain
FFB.vegetationType
FFB.genusRichness
FFB.genusRank
IUCN.status
plant_uses_EN, plant_uses_PT, plant_uses_ES, plant_uses_FR
free_notes_EN, free_notes_PT, free_notes_ES, free_notes_FR
POWO.url
FFB.url

# Added by arboretum_phrases()
full_phrases_EN, full_phrases_PT, full_phrases_ES, full_phrases_FR
full_phrases_ADD_LANGUAGE

Not every column needs to be filled, but the core taxonomic and distribution fields are required for full functionality. arboretum_audios() and arboretum_labels() also require the full_phrases_* columns of every language they use.

Main workflow

A typical aRboretum workflow consists of the following steps:

extract and structure species data with arboretum_data(), then review it;
generate the editable species phrases with arboretum_phrases();
optionally prepare folders for personal audio with arboretum_audios();
optionally prepare folders for species photos with arboretum_photos();
generate interactive HTML labels with arboretum_labels();
create a searchable minisite with arboretum_minisite();
create printable QR-code labels with arboretum_qrcodes().

Function overview

`arboretum_data()`

What it does

arboretum_data() extracts and merges species information from Flora e Funga do Brasil and the World Checklist of Vascular Plants, and adds the IUCN Red List status of each species. It resolves synonyms when possible, merges overlapping information, and returns a standardised dataset that can be used by the rest of the package.

The output also includes empty user-editable columns such as plant_uses_* and free_notes_*, which can later be used to enrich labels in the built-in languages.

Example

spp_list <- c("Luetzelburgia bahiensis", "Paubrasilia echinata")

extracted_data <- arboretum_data(
  spp_list = spp_list,
  printed_lang = c("pt", "en", "fr", "es"),
  save = TRUE,
  format = "xlsx",
  dir = "arboretum_data",
  ffb_dir = "flora_download"
)

Data reviewing guide

When save = TRUE, the function also writes __data_reviewing_guide.html to dir. It shows one card per species with editable fields for the vernacular names, country, endemism in Brazil, botanical countries, introduced range, establishment means, Brazilian states, phytogeographic domains, vegetation types, IUCN status, plant uses, and free notes. Endemism, establishment means, and IUCN status are drop-down menus restricted to the values used to build the phrases. The corrected data can be saved or exported as CSV or XLSX directly from the browser. printed_lang sets the languages of the guide interface and which plant-use and note fields it shows; the data file always keeps the columns of all four languages.

Notes

Synonyms are resolved to accepted names when possible.
Missing values from one source may still be complemented by the other.
The FFB dataset is downloaded with floraR into ffb_dir and kept there. Later runs always use the most recent version already downloaded, without contacting the FFB server, so the function also works offline. To update it, run floraR::flora_download(dir = ffb_dir). ffb_dir can also point to one specific version folder, such as "flora_download/dwca_ffb_v393_430_latest".
WCVP data come from the rWCVPdata package, so no per-species web request is needed.
If dir already contains a data file, it is read instead of querying the databases again, and the reviewing guide is rebuilt from it.
No phrase is generated at this step.

`arboretum_phrases()`

What it does

arboretum_phrases() generates the natural-language species descriptions once the data retrieved with arboretum_data() have been reviewed. The phrases are stored in the data file itself, in the columns full_phrases_EN, full_phrases_PT, full_phrases_ES, full_phrases_FR, and full_phrases_ADD_LANGUAGE, which are created at this step only. It also writes an HTML phrase guide (__phrase_generating_guide.html) next to the data file, in which phrases, vernacular names, plant uses and notes can be edited and exported.

Example

arboretum_phrases(
  data_path = "arboretum_data/arboretum_data.xlsx",
  printed_lang = c("pt", "en", "fr", "es"),
  add_lang = "TUKANO"
)

Notes

Stored phrases, including manual edits, are never overwritten; only empty phrases are filled when the function is run again.
overwrite = TRUE regenerates all phrases, for example after correcting the data. full_phrases_ADD_LANGUAGE is never overwritten.
Phrases pick some vernacular names and countries at random, so regenerating a phrase may change its wording; storing them keeps them stable.
arboretum_audios() and arboretum_labels() only read the stored phrases and never generate them.

`arboretum_audios()`

What it does

arboretum_audios() prepares a folder structure for personal species audio recordings. For each species and each language, the function creates one folder, inside arboretum_audios/, where users can place audio files.

It also writes an HTML recording guide, arboretum_audios/__personal_audio_recording_guide.html, showing the phrase stored by arboretum_phrases() for each species and language. In Chromium-based browsers, the guide can also record directly into the species folders.

Example

arboretum_audios(
  data_path = "arboretum_data/arboretum_data.xlsx",
  printed_lang = c("pt", "en", "fr", "es"),
  add_lang = "TUKANO",
  verbose = TRUE
)

Notes

Built-in languages are "pt", "en", "fr", and "es".
The optional add_lang argument creates one additional language folder per species, such as TUKANO.
Species folders are only created when arboretum_audios/ does not exist yet; the recording guide is rewritten on every run.

`arboretum_photos()`

What it does

arboretum_photos() creates one photo folder per species so that users can add personal or curated images to be embedded later in the HTML labels.

Example

arboretum_photos(
  data_path = "arboretum_data/arboretum_data.xlsx",
  verbose = TRUE
)

Notes

Existing folders are preserved, and only missing species folders are created.
Photos are optional and only appear in labels when files are found in the expected species folder.

`arboretum_labels()`

What it does

arboretum_labels() generates one standalone HTML label per species. Each label may include:

multilingual species text, taken from the phrases stored by arboretum_phrases();
plant uses and free notes;
taxonomic information;
world and Brazil distribution maps;
browser-based speech synthesis;
personal audio recordings when available;
photo slideshows when available;
IUCN iconography and links to FFB and POWO;
institutional and package logos.

Example

arboretum_labels(
  data_path = "arboretum_data/arboretum_data.xlsx",
  audio_dir = "arboretum_audios",
  photo_dir = "arboretum_photos",
  printed_lang = c("pt", "en"),
  add_lang = "TUKANO",
  path_to_logo = "path/to/institution_logo.png",
  logo_url = "https://www.example.org",
  dir = "species_labels",
  verbose = TRUE
)

The `add_lang` workflow

The add_lang argument provides a flexible, interim pathway for including one additional community or local language in species labels and associated audio, without requiring translation of the full website interface.

When add_lang is supplied:

arboretum_phrases() adds an editable field for the extra language to the phrase guide, stored in the column full_phrases_ADD_LANGUAGE;
arboretum_labels() looks for the column full_phrases_ADD_LANGUAGE;
if that column contains non-empty text, the extra language is added as an additional text option in the label;
the custom language text is read directly from full_phrases_ADD_LANGUAGE;
this extra language does not pass through the standard phrase-generation and translation workflow.

This is especially useful in collaborative work with Indigenous peoples or other local communities, where species-level accessibility may be more important than translating the full minisite interface.

Notes

The function stops if the full_phrases_* column of a language in printed_lang is missing, and warns about species without a stored phrase.
Personal audio files take priority over browser speech synthesis.
For custom languages added through add_lang, personal recordings are recommended because browser voices may not be available.
Personal audio and photo folders are copied into dir (as __arboretum_audios/ and __arboretum_photos/), and photos larger than 1 MB are compressed in the copy.
Photos and maps are included only when available.

`arboretum_minisite()`

What it does

arboretum_minisite() builds a searchable index.html page linking all generated species labels. When the species data file is provided, it also includes a dashboard with collection summaries: numbers of species, genera and families, establishment means, phytogeographic domains, Brazilian states, and countries.

Example

arboretum_minisite(
  labels_dir = "species_labels",
  data_path = "arboretum_data/arboretum_data.xlsx",
  site_title = "Garden Collection",
  printed_lang = c("en", "pt", "es", "fr"),
  logo = "path/to/logo.png",
  logo_url = "https://www.example.org",
  group_by_family = TRUE
)

Notes

The interface language order follows the order of printed_lang.
The minisite can work without data_path, but vernacular names and the dashboard are then omitted.
After writing index.html, the labels folder is renamed after the site title, here Garden_Collection_minisite/. The whole folder can then be published as a website.

`arboretum_qrcodes()`

What it does

arboretum_qrcodes() creates printable A4 sheets of QR-code labels that can link to the species HTML labels of a published minisite, to external URLs, or to source records. Four layouts are available: "minimalist" (QR code with the species and vernacular names) and the detailed "classic", "modern", and "botanical" layouts (with authorship, family, endemism, optional logo and specimen code).

Example

arboretum_qrcodes(
  data_path = "arboretum_data/arboretum_data.xlsx",
  base_url = "https://myinstitution.org/collection",
  layout = "minimalist",
  dir = "qrcodes_mini"
)

arboretum_qrcodes(
  data_path = "arboretum_data/arboretum_data.xlsx",
  base_url = "https://myinstitution.org/collection",
  layout = "classic",
  width = 6.0,
  length = 8.0,
  id_code = "catalogue_number",
  printed_lang = "en",
  path_to_logo = "path/to/logo.png",
  color = "#1a2e1a",
  format = "pdf",
  dir = "qrcodes_classic"
)

Notes

QR codes point, in order of priority, to base_url (one page per species, matching the label file names), to url, to the POWO page, to the FFB page, or encode the taxon name.
id_code can be the name of a column of the data file or one or more codes.
Detailed layouts print a single language, the first one in printed_lang.
Default label sizes are 2.5 × 2.5 cm for the minimalist layout and 6 × 8 cm for the detailed layouts.
Output can span multiple pages automatically, as PDF or PNG.

Practical example with one additional language

The example below illustrates a simple workflow where Portuguese and English remain the main interface languages, while Tukano is added as a community language for species labels and optional personal recordings.

arboretum_phrases(
  data_path = "arboretum_data/arboretum_data.xlsx",
  printed_lang = c("pt", "en"),
  add_lang = "TUKANO"
)

arboretum_audios(
  data_path = "arboretum_data/arboretum_data.xlsx",
  printed_lang = c("pt", "en"),
  add_lang = "TUKANO"
)

arboretum_labels(
  data_path = "arboretum_data/arboretum_data.xlsx",
  audio_dir = "arboretum_audios",
  printed_lang = c("pt", "en"),
  add_lang = "TUKANO",
  dir = "species_labels"
)

Before generating the labels, fill the column full_phrases_ADD_LANGUAGE created by arboretum_phrases() with the full text to display in Tukano for each species, either in the phrase guide or directly in the data file.

Defensive checks and internal helpers

Several internal helper functions provide validation and error prevention.

`.arg_check_spp_list()`

trims whitespace;
standardises input species names;
checks for invalid entries.

`.arg_check_dir()`

validates output directory names;
removes trailing slashes when needed.

`.arg_check_printed_lang()`

standardises language codes to lower case;
removes duplicates;
validates built-in language codes.

`.read_species_data()`

checks file existence and extension;
reads CSV or Excel input;
validates required columns.

`.load_ffb()`, `.load_wcvp()`, and `.get_iucn_status()`

load the FFB dataset, reusing a previous download;
load the WCVP tables once per run;
retrieve IUCN Red List categories from GBIF or the IUCN Red List API.

`.copy_folder_progress()`

copies user-provided audio or photo folders into output directories;
shows progress feedback when many files are involved.

Phrase-generation helpers

Helpers such as .phrase_generator(), .tr_dict(), .botdiv_to_countries(), and .add_genus_curiosity_notes() support the construction of species descriptions in the built-in languages.

Conclusion

aRboretum provides a practical pipeline for creating modern botanical collection labels, from taxonomic data retrieval to multilingual HTML pages and printable QR codes. The package combines automation with flexibility, allowing users to review the data and edit the phrases, and to enrich labels with notes, uses, photos, personal audio, and one additional community-based language through add_lang.

For function-specific details, see the package documentation:

?arboretum_data
?arboretum_phrases
?arboretum_audios
?arboretum_photos
?arboretum_labels
?arboretum_minisite
?arboretum_qrcodes

aRboretum: Complete technical guide for botanical collections

Martin Boucknooghe & Domingos Cardoso

2026-10-05

Introduction

Installation

Optional: IUCN Red List API token

Internal data structures

The internal translation dictionary

Botanical regions mapping

Expected data structure

Main workflow

Function overview

arboretum_data()

What it does

Example

Data reviewing guide

Notes

arboretum_phrases()

What it does

Example

Notes

arboretum_audios()

What it does

Example

Notes

arboretum_photos()

What it does

Example

Notes

arboretum_labels()

What it does

Example

The add_lang workflow

Notes

arboretum_minisite()

What it does

Example

Notes

arboretum_qrcodes()

What it does

Example

Notes

Practical example with one additional language

Defensive checks and internal helpers

.arg_check_spp_list()

.arg_check_dir()

.arg_check_printed_lang()

.read_species_data()

.load_ffb(), .load_wcvp(), and .get_iucn_status()

.copy_folder_progress()

Phrase-generation helpers

Conclusion

`arboretum_data()`

`arboretum_phrases()`

`arboretum_audios()`

`arboretum_photos()`

`arboretum_labels()`

The `add_lang` workflow

`arboretum_minisite()`

`arboretum_qrcodes()`

`.arg_check_spp_list()`

`.arg_check_dir()`

`.arg_check_printed_lang()`

`.read_species_data()`

`.load_ffb()`, `.load_wcvp()`, and `.get_iucn_status()`

`.copy_folder_progress()`