optree

A lightweight R package for hierarchical runtime configuration

optree provides a flexible, mutable, hierarchical options manager for R. It allows packages and projects to define nested configuration options, enforce group validation rules, and easily reset to defaults. Ideal for complex, interdependent settings like crop models, phenology simulations, or multi-module projects.

---

Features

• Hierarchical, nested options (a.b.c)
• Dot-separated path notation for both get() and set() operations
• Runtime mutable configuration
• Merge-aware updates (update only part of a nested group)
• Transactional updates (rollback on validation failure)
• Group and field validation for consistency
• Reset all options to defaults with one call
• Minimal dependencies, lightweight and easy to use

---

Installation

From CRAN

install.packages('optree')

From GitHub (development version)

remotes::install_github('byzheng/optree')

---

Documentation

For detailed documentation and reference, visit: https://optree.bangyou.me

---

Getting Started

1. Create an options manager

library(optree)

# Create the CANOLA options manager with built-in validators
canola <- create_options_manager(
  defaults = list(
    phenology = list(
      thermaltime = list(
        x = c(2, 30, 35),
        y = c(0, 28, 0)
      )
    ),
    frost_threshold = 0,
    model_name = "canola_v1",
    backend = "cpu"
  ),
  validators = list(
    "phenology.thermaltime" = v_xypair(min_len = 3),
    "frost_threshold" = v_numeric_range(min = -5, max = 5),
    "model_name" = v_character_scalar(),
    "backend" = v_enum(c("cpu", "gpu"))
  )
)

2. Access options

# Get a single leaf
canola$get("phenology.thermaltime.x")

# Get the entire group
canola$get("phenology.thermaltime")

3. Update options

# Method 1: Use dot-separated paths (NEW!)
canola$set("phenology.thermaltime.x" = c(5,25,40))
canola$set("phenology.thermaltime.y" = c(0,20,0))

# Method 2: Use nested list (traditional way)
canola$set(phenology = list(
  thermaltime = list(
    x = c(10,20,30),
    y = c(0,10,0)
  )
))

# Mix both styles in one call
canola$set(
  "phenology.thermaltime.x" = c(15,25,35),
  frost_threshold = -2
)

# Update top-level option
canola$set(frost_threshold = -2)

Validator example:

# v_enum validator - value must be one of the allowed choices
canola$set(backend = "quantum")
# Error: must be one of: cpu, gpu

# v_numeric_range validator - frost_threshold must be between -5 and 5
canola$set(frost_threshold = 10)
# Error: must be between -5 and 5

# v_xypair validator - x and y must have same length and meet min_len
canola$set(phenology = list(thermaltime = list(
  x = c(1, 2),
  y = c(0, 1, 2)
)))
# Error: 'x' and 'y' must have the same length

# v_character_scalar validator - model_name must be non-empty string
canola$set(model_name = "")
# Error: must not be empty

5. Transactional safety

# Set valid values
canola$set("phenology.thermaltime.x" = c(5,25,40))
canola$set("phenology.thermaltime.y" = c(0,20,0))

# Try an invalid update - will fail and rollback
canola$set("phenology.thermaltime.x" = c(1,2))  # length mismatch
# Error: x and y must have same length

# Options remain unchanged after failed validation
canola$get("phenology.thermaltime.x")  # Still c(5,25,40)

6. Reset options

canola$reset()
# Returns all defaults
canola$get()

Advantages over existing approaches

Feature	optree	settings::options_manager	base R options()
Hierarchical options	✅	Limited	❌
Merge-aware updates	✅	❌	❌
Runtime mutable	✅	✅	✅
Group validation	✅	Custom only	❌
Arbitrary depth	✅	Limited	❌

Built-in Validators

optree provides a collection of ready-to-use validators for common validation patterns:

• v_numeric_scalar() – Validates single numeric values
• v_numeric_range(min, max) – Validates numeric values within a range
• v_numeric_vector(min_len, finite) – Validates numeric vectors with length/finiteness constraints
• v_logical_scalar() – Validates single logical values
• v_character_scalar(non_empty) – Validates single character values, optionally non-empty
• v_enum(choices) – Validates that value is one of predefined choices
• v_xypair(min_len) – Validates paired x/y lists (useful for time series, phenology data, etc.)

For more details and examples, see the Validators Vignette.

Contributing

Contributions are welcome! Please submit issues or pull requests via GitHub.

License

MIT License – see LICENSE file for details.