document() is a high-level orchestration wrapper for decision workflows built on APSIM Next Generation outputs. It validates inputs, dispatches to a domain-specific decision package, and standardises the returned result into a common report structure. It does not implement the decision logic itself.

document(
  data,
  decision,
  context = list(),
  criteria = list(),
  options = list(),
  simplify = FALSE,
  ...
)

Arguments

data

A data frame or tibble containing APSIM Next Generation simulation outputs.

decision

A single string identifying which decision workflow to run, such as "cultivar".

context

A named list of contextual inputs supplied to the selected decision workflow.

criteria

A named list of decision criteria or thresholds used by the selected decision workflow.

options

A named list of additional options that control reporting or documentation behaviour in the selected decision workflow.

simplify

A boolean flag indicating whether to simplify the returned document into a character vector of lines. If FALSE, the full structured document is returned.

...

Additional arguments passed through to the domain-specific decision documenter.

Value

A list with class "rapsimng_decide_report" containing four named components:

  • meta: metadata describing the decision context and execution.

  • metrics: summary metrics produced by the decision workflow.

  • tables: tabular outputs ready for reporting.

  • figures: figure objects, specifications, or references for visual output.

Details

This package separates responsibilities across the wider workflow:

  • rapsimng is responsible for running or preparing APSIM Next Generation simulations and outputs.

  • rapsimng.decide.* packages implement domain-specific decision logic, such as cultivar suitability assessment.

  • downstream analysis or interpretation layers, including packages such as agrillm, can consume the standardised report returned here.

rapsimng.decide sits between these layers and provides a consistent entry point and output contract for decision-oriented reporting.

Examples

example_data <- data.frame(
  Cultivar = c("A", "A", "B", "B"),
  Year = c(2020, 2021, 2020, 2021),
  SowingDOY = c(120, 120, 125, 125),
  Flowering = c(200, 201, 202, 203),
  Yield = c(4000, 4200, 3800, 3900),
  FrostReduction = 0,
  HeatReduction = 0,
  FrostEvent = 0,
  HeatEvent = 0
)
decision_context <- list(vars = list(
  cultivar_col = "Cultivar",
  year_col = "Year",
  sowing_col = "SowingDOY",
  flower_col = "Flowering",
  yield_col = "Yield",
  frost_reduction_col = "FrostReduction",
  heat_reduction_col = "HeatReduction",
  frost_event_col = "FrostEvent",
  heat_event_col = "HeatEvent"
))
report <- document(
  data = example_data,
  decision = "cultivar",
  context = decision_context,
  simplify = TRUE
)
head(report)
#> [1] "---"                                   
#> [2] "title: \"Cultivar Suitability Report\""
#> [3] "format: html"                          
#> [4] "execute:"                              
#> [5] "  echo: false"                         
#> [6] "  eval: true"