Create folder structure for personal species photos

This function creates an organized folder structure for storing personal photos of species. It reads a species dataframe generated by arboretum_data() and creates one photo folder per species inside an arboretum_photos/ directory.

The function is designed to be used after arboretum_data() and before generating final labels or minisites with functions such as arboretum_labels(). When personal photos are placed in the appropriate species folders, downstream functions can use them instead of relying only on built-in or automatically retrieved image resources.

Usage

arboretum_photos(data_path = NULL, verbose = TRUE)

Arguments

data_path

Required. Character string giving the path to the input data file generated by arboretum_data(). The file must be in CSV or Excel format and should contain, at minimum, the columns taxonName and family. Passing NULL will result in an error when the input data are read.

verbose

Logical. If TRUE, progress messages are printed to the console. Default is TRUE.

Value

Invisibly returns NULL. The function is called for its side effects:

• creates the main arboretum_photos/ directory, if it does not already exist;

• creates one species-specific subfolder per taxon;

• preserves existing folders and creates only missing folders.

Details

The function follows three main steps:

1. Input data loading

   • Reads the input species data using an internal helper function.

   • Supports CSV and Excel files.

   • Expects species names in taxonName and family names in family.

2. Folder creation

   • Creates a main folder named arboretum_photos.

   • Creates one subfolder for each species in the input data.

   • Subfolder names are built from family, species name, and the suffix photos.

   • Species names are converted to folder-safe names by replacing spaces with underscores.

3. Photo placement

   • Users should place their photo files in the corresponding species folder.

   • Common image formats such as JPG, JPEG, PNG, and similar formats can be used, depending on the downstream functions that read the photos.

   • The photo folders are intended to be used by downstream label or minisite generation functions.

The folder naming pattern is:

FAMILY_Genus_species_photos

For example:

arboretum_photos/
├── ARECACEAE_Euterpe_edulis_photos/
├── FABACEAE_Paubrasilia_echinata_photos/
└── ...

Note

• This function does not download, validate, resize, rename, or convert image files. It only prepares the folder structure for manual photo placement.

• Existing folders are not deleted or overwritten.

• If arboretum_photos/ already exists, the function checks each species folder and creates only those that are missing.

• The function should generally be run after arboretum_data() and before arboretum_labels().

See also

arboretum_data, arboretum_labels

Author

Martin Boucknooghe & Domingos Cardoso

Examples

if (FALSE) { # \dontrun{
# Create photo folders from a CSV file generated by arboretum_data()
arboretum_photos(
  data_path = "arboretum_data/arboretum_data.csv"
)

# Create photo folders from an Excel file
arboretum_photos(
  data_path = "arboretum_data/arboretum_data.xlsx",
  verbose = TRUE
)

# Suppress progress messages
arboretum_photos(
  data_path = "arboretum_data/arboretum_data.csv",
  verbose = FALSE
)
} # }