Package 'rapsimng.decide'

Title: Decision-Oriented Analysis Interface for APSIM Next Generation Outputs
Description: Provides a high-level interface for analysing Agricultural Production Systems sIMulator ('APSIM') Next Generation simulation outputs to support structured decision-making workflows. The package coordinates domain-specific decision modules (e.g. cultivar selection, experimental design) and standardises their outputs into reproducible decision reports. It does not perform 'APSIM' simulations or implement decision logic directly, but serves as an orchestration layer connecting analysis results with reporting and downstream interpretation.
Authors: Bangyou Zheng [aut, cre]
Maintainer: Bangyou Zheng <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0
Built: 2026-11-19 03:52:33 UTC
Source: https://github.com/cran/rapsimng.decide

Help Index


Document a Decision From APSIM NG Outputs

Description

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.

Usage

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.

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.

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.

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)

Evaluate a Decision From APSIM NG Outputs

Description

evaluate() 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.

Usage

evaluate(
  data,
  decision,
  context = list(),
  criteria = list(),
  options = list(),
  ...
)

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 evaluation behaviour in the selected decision workflow.

...

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

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.

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.

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 <- evaluate(
  data = example_data,
  decision = "cultivar",
  context = decision_context
)
names(report)

Read APSIMX output

Description

Read APSIMX output

Usage

read_output(apsimx_file, report = "HarvestReport", years = NULL)

Arguments

apsimx_file

The path to the APSIMX output file (.apsimx)

report

The name of the report to read from the APSIMX output ( default: "HarvestReport")

years

Optional numeric vector of years to filter the output by (e.g., 1996:2025)

Value

A data frame containing the APSIMX output data

Examples

apsimx_file <- system.file(
  "example", "cultivar.apsimx",
  package = "rapsimng.decide"
)
output <- read_output(apsimx_file, years = 2010:2011)
head(output)