Write model-specific run scripts and configuration files

Usage

run.write.configs(
  settings,
  ensemble.size,
  input_design,
  write = TRUE,
  posterior.files = rep(NA, length(settings$pfts)),
  overwrite = TRUE
)

Arguments

settings: a PEcAn settings list
ensemble.size: number of ensemble runs
input_design: Input design data.frame coordinating input files across runs. Contains columns for each sampled input (met, param, etc.) with row indices, as documented in runModule.run.write.configs.
write: should the runs be written to the database?
posterior.files: Filenames for posteriors for drawing samples for ensemble and sensitivity analysis (e.g. post.distns.Rdata, or prior.distns.Rdata).
overwrite: logical: Replace output files that already exist?

Value

The settings list (invisibly), updated with ensemble IDs for SA and ensemble analysis (e.g. settings$sensitivity.analysis$ensemble.id, settings$ensemble$ensemble.id).

Details

Upstream contract (reads from settings$outdir):

samples.Rdata: Produced by get.parameter.samples. Contains 5 bundled objects: trait.samples, sa.samples, ensemble.samples, runs.samples, env.samples. This function loads trait.samples and sa.samples to build model configuration files. If input_design contains a param column, ensemble.samples is rebuilt by subsetting trait.samples according to the design indices.

File-based side effects (saved to settings$outdir):

sensitivity.samples.<ensemble_id>.Rdata: Contains sa.run.ids (named list of run IDs per PFT/trait/quantile), sa.ensemble.id, sa.samples, pft.names, and trait.names. Saved when sensitivity analysis is configured.
ensemble.samples.<ensemble_id>.Rdata: Contains ens.run.ids (vector of run IDs), ens.ensemble.id, ens.samples, pft.names, and trait.names. Saved when ensemble is configured.
runs_manifest.csv: A CSV table tracking all runs created, appended across ensemble and SA analyses.

Downstream contract: The sensitivity.samples.*.Rdata and ensemble.samples.*.Rdata files are loaded by get.results to match model outputs to their corresponding parameter sets. This implicit file-based coupling is a refactoring target.

The default value for posterior.files is NA, in which case the most recent posterior or prior (in that order) for the workflow is used. When specified, posterior.files should be a vector of filenames with one entry for each PFT. Specify filenames with no path; PFT outdirs will be appended. This forces use of only files within this workflow, to avoid confusion.

Author

David LeBauer, Shawn Serbin, Ryan Kelly, Mike Dietze, Akash B V