Write Taxonomic Descriptions

Overview

The barroso_write_taxon_descr() function is a powerful tool in the barRoso package for generating automated morphological descriptions from structured Excel data. It transforms taxonomic and morphological character data into standardized, publication-ready species descriptions in Word document format.

Key Features

Automatically generates species descriptions from morphological Excel data
Groups related characters and avoids term repetition
Combines measurements (length × width) with proper units and symbols
Formats measurement ranges with en dashes (e.g., “4.3–14.5 cm”)
Handles complex hierarchical character structures
Merges duplicate species entries intelligently
Customizable text formatting (bold, italic) for different description elements
Exports professionally formatted Word (.docx) documents

Usage

library(barRoso)

# Generate descriptions for all species
descriptions <- barroso_write_taxon_descr(
  xlsx_path = "morphological_data.xlsx",
  species_cols = c("Genus", "Species", "Author"),
  character_cols = 4:20
)

# Generate descriptions only for specific species
descriptions <- barroso_write_taxon_descr(
  xlsx_path = "morphological_data.xlsx",
  species_cols = c("Genus", "Species"),
  character_cols = 3:15,
  species_filter = c("Ouratea concinna", "Ouratea coarctata")
)

# Customize formatting and output
descriptions <- barroso_write_taxon_descr(
  xlsx_path = "morphological_data.xlsx",
  species_cols = 1:3,
  character_cols = 4:25,
  font_family = "Arial",
  font_size = 11,
  species_bold = TRUE,
  species_italic = TRUE,
  group_bold = FALSE,
  group_italic = TRUE,
  description_bold = FALSE,
  description_italic = FALSE,
  filename = "MySpeciesDescriptions",
  dir = "Output"
)

Output

Returns a data frame with:

species_name: Full species name with authorship
description_plain: Plain text version of the description

Also creates a Word document (.docx) saved to the specified directory with:

Species names formatted following botanical conventions Morphological descriptions organized by character groups Measurements properly formatted with units Hierarchical characters grouped logically

Data Format Requirements

# Excel data should follow these naming conventions:
# Simple characters: "HABIT", "LEAF shape"
# Measurements: "LEAF length (cm)", "LEAF width (mm)"
# Hierarchical: "LEAF MARGINS", "FLOWER SEPALS shape"
# Complex hierarchy: "FLOWER SEPALS BASE shape", "FLOWER SEPALS APEX shape"

# Example data structure:
# | Genus | Species | Author | HABIT | LEAF shape | LEAF length (cm) | LEAF width (cm) |
# |-------|---------|--------|-------|------------|------------------|-----------------|
# | Ouratea | concinna | (Mart.) Engl. | tree | elliptic | 4.3-14.5 | 2.1-3.8 |

Examples

Basic Example

# Using included dataset
data(morphological_dataset)
library(openxlsx)
openxlsx::write.xlsx(morphological_dataset, "morphological_dataset.xlsx")

barroso_write_taxon_descr(
  xlsx_path = "morphological_dataset.xlsx",
  species_cols = c("Genus", "Species", "Author"),
  character_cols = 19:131
)

Custom Column Selection

# Select specific character groups
selected_cols <- c(
  "HABIT", "HABIT height (m)",
  "LEAF BLADE shape", "LEAF BLADE length (cm)", "LEAF BLADE width (cm)",
  "FLOWER SEPALS shape", "FLOWER SEPALS length (mm)", "FLOWER SEPALS width (mm)"
)

barroso_write_taxon_descr(
  xlsx_path = "data.xlsx",
  species_cols = c("Genus", "Species"),
  character_cols = selected_cols,
  filename = "Selected_Characters"
)

Using Column Indices

# Use column indices instead of names
barroso_write_taxon_descr(
  xlsx_path = "data.xlsx",
  species_cols = 1:2,      # First two columns: Genus and Species
  character_cols = 3:18,   # Columns 3-18: morphological characters
  font_family = "Times New Rowman",
  font_size = 12
)

Notes

Uses parsing of column names to group related characters
Measurements sharing the same base name are automatically combined (e.g., “LEAF length” and “LEAF width” become “X × Y cm”)
ALL CAPS terms in column names are used for hierarchical grouping
Creates date-stamped folders to organize output by processing date
Maintains original column order while intelligently grouping related items

Example Output

Ouratea concinna A.Queiroz-Lima & D.B.O.S.Cardoso Shrub; 0.3–1 m tall; erect; branched; stem striated, gray, glabrous. Stipule single; intrapetiolar; at the apex of young branches, becoming progressively deciduous from the tip towards the base; 1–2.5 × 1 mm; lanceolate or triangular; base truncate; margin entire; apex acute or aristate; glabrous. Leaf dispersed; grouped at the apical portion of the branch; petiole sessile, elephant’s foot, longitudinal, glabrous, 0.1 × 0.1 cm; blade flat, shiny, rigid and leathery, oblong or ovate, 1.3–2.5 × 0.6–1.1 cm, apex apiculate or rounded mucronate, base rounded or rounded, subcordate; margins entire, flat or narrowly revolute; eucamptodromous; secondary-venation 3–6 pairs, curved distally towards the marginal vein, visible on both surfaces; tertiary-venation parallel to each other, at 45° from the central rib, visible on both surfaces; midvein prominent on both surfaces; glabrous on both surfaces. Inflorescence panicle; terminal; erect; 4.5–7 × 1–5.5 cm; with around 70 flowers; axes tiny glandular projections; peduncle brownish, channeled, with many bracts at their base or just scars, glabrous, 0.5 × 0.1 cm; bract present, grouped at the base of inflorescence and dispersed along the rachis, lanceolate, 2 × 1 mm, longitudinal-venation present, margins entire. Flower actinomorphic; pedicel glabrous, 6 × 0.5 mm; sepals free, brownish, glabrous, oblong, entire, translucent, not persistent, 7 × 2 mm, apex rounded, base truncate; petals 5, free, yellow, membranous, glabrous, flabellate, 7 × 7 mm, apex rounded, irregular, base attenuate; stamen 10, sessile, anthers brownish, anthers wrinkled, anthers glabrous, anthers bithecal, anthers poricidal, anthers 5 × 1 mm; gynoecium superior, glabrous, 5 mm long, carpels 5, stigma inconspicuous, style brownish, style 4 mm long. Fruit 2.5 cm long; carpophore globose, 0.7 × 0.5 cm; mericarp 5, oval, 10 × 5 mm. Seed 9 × 5 mm.

Ouratea gladiifolia A.Queiroz-Lima & D.B.O.S.Cardoso Shrub or subshrub; 0.3–0.6 m tall; erect, growing from xylopodium; branched; stem striated or striated, scaly, gray, glabrous. Stipule 1 pair; lateral to petiole; usually persistent along the branches; 3–4 × 1 mm; lanceolate; base truncate; margin entire; apex aristate; glabrous. Leaf dispersed; well distributed along the branches; petiole sessile, elephant’s foot, longitudinal, glabrous or present, 0.1 × 0.1 cm; blade flat, shiny, chartaceous, elliptic, lanceolate or lanceolate, 2.3–6.2 × 0.3–1.8 cm, apex narrowly acute, mucronate, base attenuate; margins entire, flat; eucamptodromous; secondary-venation 3–4 pairs, curved distally towards the marginal vein, visible on both surfaces; tertiary-venation parallel to each other, at 45° from the central rib, visible on both surfaces; midvein prominent on both surfaces; glabrous on both surfaces or glabrous on both surfaces, sometimes with scattered trichomes above. Inflorescence panicle; terminal; erect; 6–7 × 3–4 cm; with around 20 flowers or with around 25 flowers; axes glabrous; peduncle brownish, channeled, with many bracts at their base or just scars or brownish, channeled, with many bracts at their base or just scars, several racemes or panicles start from the same point, glabrous, 0.5–3 × 0.1 cm; bract present, grouped at the base of inflorescence and dispersed along the rachis, lanceolate, 2–3 × 1 mm, longitudinal-venation present, margins entire. Flower actinomorphic; pedicel glabrous, 6–9 × 0.5 mm; sepals free, brownish, glabrous, oblong, entire, translucent, 6 × 2.5 mm, apex rounded, base truncate; petals 5, free, yellow, membranous, glabrous, flabellate, 5–7 × 5 mm, apex rounded, irregular, base attenuate; stamen 10, sessile, anthers brownish, anthers wrinkled, anthers glabrous, anthers bithecal, anthers poricidal, anthers 5.5–6 × 1 mm; gynoecium superior, glabrous, 4–6 mm long, carpels 5, stigma inconspicuous, style brownish, style 2–4 mm long. Fruit not seen.

--- title: "Write Taxonomic Descriptions" format: html --- ## Overview The `barroso_write_taxon_descr()` function is a powerful tool in the `barRoso` package for generating automated morphological descriptions from structured Excel data. It transforms taxonomic and morphological character data into standardized, publication-ready species descriptions in Word document format. ## Key Features - Automatically generates species descriptions from morphological Excel data - Groups related characters and avoids term repetition - Combines measurements (length × width) with proper units and symbols - Formats measurement ranges with en dashes (e.g., "4.3–14.5 cm") - Handles complex hierarchical character structures - Merges duplicate species entries intelligently - Customizable text formatting (bold, italic) for different description elements - Exports professionally formatted Word (.docx) documents ## Usage ```r library(barRoso) # Generate descriptions for all species descriptions <- barroso_write_taxon_descr( xlsx_path = "morphological_data.xlsx", species_cols = c("Genus", "Species", "Author"), character_cols = 4:20 ) # Generate descriptions only for specific species descriptions <- barroso_write_taxon_descr( xlsx_path = "morphological_data.xlsx", species_cols = c("Genus", "Species"), character_cols = 3:15, species_filter = c("Ouratea concinna", "Ouratea coarctata") ) # Customize formatting and output descriptions <- barroso_write_taxon_descr( xlsx_path = "morphological_data.xlsx", species_cols = 1:3, character_cols = 4:25, font_family = "Arial", font_size = 11, species_bold = TRUE, species_italic = TRUE, group_bold = FALSE, group_italic = TRUE, description_bold = FALSE, description_italic = FALSE, filename = "MySpeciesDescriptions", dir = "Output" ) ``` ## Output Returns a data frame with: - species_name: Full species name with authorship - description_plain: Plain text version of the description Also creates a Word document (.docx) saved to the specified directory with: Species names formatted following botanical conventions Morphological descriptions organized by character groups Measurements properly formatted with units Hierarchical characters grouped logically ## Data Format Requirements ```r # Excel data should follow these naming conventions: # Simple characters: "HABIT", "LEAF shape" # Measurements: "LEAF length (cm)", "LEAF width (mm)" # Hierarchical: "LEAF MARGINS", "FLOWER SEPALS shape" # Complex hierarchy: "FLOWER SEPALS BASE shape", "FLOWER SEPALS APEX shape" # Example data structure: # | Genus | Species | Author | HABIT | LEAF shape | LEAF length (cm) | LEAF width (cm) | # |-------|---------|--------|-------|------------|------------------|-----------------| # | Ouratea | concinna | (Mart.) Engl. | tree | elliptic | 4.3-14.5 | 2.1-3.8 | ``` ## Examples # Basic Example ```r # Using included dataset data(morphological_dataset) library(openxlsx) openxlsx::write.xlsx(morphological_dataset, "morphological_dataset.xlsx") barroso_write_taxon_descr( xlsx_path = "morphological_dataset.xlsx", species_cols = c("Genus", "Species", "Author"), character_cols = 19:131 ) ``` # Custom Column Selection ```r # Select specific character groups selected_cols <- c( "HABIT", "HABIT height (m)", "LEAF BLADE shape", "LEAF BLADE length (cm)", "LEAF BLADE width (cm)", "FLOWER SEPALS shape", "FLOWER SEPALS length (mm)", "FLOWER SEPALS width (mm)" ) barroso_write_taxon_descr( xlsx_path = "data.xlsx", species_cols = c("Genus", "Species"), character_cols = selected_cols, filename = "Selected_Characters" ) ``` # Using Column Indices ```r # Use column indices instead of names barroso_write_taxon_descr( xlsx_path = "data.xlsx", species_cols = 1:2, # First two columns: Genus and Species character_cols = 3:18, # Columns 3-18: morphological characters font_family = "Times New Rowman", font_size = 12 ) ``` ## Notes - Uses parsing of column names to group related characters - Measurements sharing the same base name are automatically combined (e.g., "LEAF length" and "LEAF width" become "X × Y cm") - ALL CAPS terms in column names are used for hierarchical grouping - Creates date-stamped folders to organize output by processing date - Maintains original column order while intelligently grouping related items ## Example Output _**Ouratea concinna**_ A.Queiroz-Lima & D.B.O.S.Cardoso **Shrub**; 0.3–1 m tall; erect; branched; stem striated, gray, glabrous. **Stipule** single; intrapetiolar; at the apex of young branches, becoming progressively deciduous from the tip towards the base; 1–2.5 × 1 mm; lanceolate or triangular; base truncate; margin entire; apex acute or aristate; glabrous. **Leaf** dispersed; grouped at the apical portion of the branch; petiole sessile, elephant's foot, longitudinal, glabrous, 0.1 × 0.1 cm; blade flat, shiny, rigid and leathery, oblong or ovate, 1.3–2.5 × 0.6–1.1 cm, apex apiculate or rounded mucronate, base rounded or rounded, subcordate; margins entire, flat or narrowly revolute; eucamptodromous; secondary-venation 3–6 pairs, curved distally towards the marginal vein, visible on both surfaces; tertiary-venation parallel to each other, at 45° from the central rib, visible on both surfaces; midvein prominent on both surfaces; glabrous on both surfaces. **Inflorescence** panicle; terminal; erect; 4.5–7 × 1–5.5 cm; with around 70 flowers; axes tiny glandular projections; peduncle brownish, channeled, with many bracts at their base or just scars, glabrous, 0.5 × 0.1 cm; bract present, grouped at the base of inflorescence and dispersed along the rachis, lanceolate, 2 × 1 mm, longitudinal-venation present, margins entire. **Flower** actinomorphic; pedicel glabrous, 6 × 0.5 mm; sepals free, brownish, glabrous, oblong, entire, translucent, not persistent, 7 × 2 mm, apex rounded, base truncate; petals 5, free, yellow, membranous, glabrous, flabellate, 7 × 7 mm, apex rounded, irregular, base attenuate; stamen 10, sessile, anthers brownish, anthers wrinkled, anthers glabrous, anthers bithecal, anthers poricidal, anthers 5 × 1 mm; gynoecium superior, glabrous, 5 mm long, carpels 5, stigma inconspicuous, style brownish, style 4 mm long. **Fruit** 2.5 cm long; carpophore globose, 0.7 × 0.5 cm; mericarp 5, oval, 10 × 5 mm. **Seed** 9 × 5 mm. _**Ouratea gladiifolia**_ A.Queiroz-Lima & D.B.O.S.Cardoso **Shrub or subshrub**; 0.3–0.6 m tall; erect, growing from xylopodium; branched; stem striated or striated, scaly, gray, glabrous. **Stipule** 1 pair; lateral to petiole; usually persistent along the branches; 3–4 × 1 mm; lanceolate; base truncate; margin entire; apex aristate; glabrous. **Leaf** dispersed; well distributed along the branches; petiole sessile, elephant's foot, longitudinal, glabrous or present, 0.1 × 0.1 cm; blade flat, shiny, chartaceous, elliptic, lanceolate or lanceolate, 2.3–6.2 × 0.3–1.8 cm, apex narrowly acute, mucronate, base attenuate; margins entire, flat; eucamptodromous; secondary-venation 3–4 pairs, curved distally towards the marginal vein, visible on both surfaces; tertiary-venation parallel to each other, at 45° from the central rib, visible on both surfaces; midvein prominent on both surfaces; glabrous on both surfaces or glabrous on both surfaces, sometimes with scattered trichomes above. **Inflorescence** panicle; terminal; erect; 6–7 × 3–4 cm; with around 20 flowers or with around 25 flowers; axes glabrous; peduncle brownish, channeled, with many bracts at their base or just scars or brownish, channeled, with many bracts at their base or just scars, several racemes or panicles start from the same point, glabrous, 0.5–3 × 0.1 cm; bract present, grouped at the base of inflorescence and dispersed along the rachis, lanceolate, 2–3 × 1 mm, longitudinal-venation present, margins entire. **Flower** actinomorphic; pedicel glabrous, 6–9 × 0.5 mm; sepals free, brownish, glabrous, oblong, entire, translucent, 6 × 2.5 mm, apex rounded, base truncate; petals 5, free, yellow, membranous, glabrous, flabellate, 5–7 × 5 mm, apex rounded, irregular, base attenuate; stamen 10, sessile, anthers brownish, anthers wrinkled, anthers glabrous, anthers bithecal, anthers poricidal, anthers 5.5–6 × 1 mm; gynoecium superior, glabrous, 4–6 mm long, carpels 5, stigma inconspicuous, style brownish, style 2–4 mm long. **Fruit** not seen.