|
1 | 1 | #' Write model-specific run scripts and configuration files |
2 | 2 | #' |
3 | | -#' Generates run scripts and configuration files for all analyses specified |
4 | | -#' in the provided settings. Most of the heavy lifting is done by the |
5 | | -#' \code{write.config.*} function for your specific ecosystem model |
6 | | -#' (e.g. write.config.ED2, write.config.SIPNET). |
| 3 | +#' @md |
| 4 | +#' Generates run scripts and configuration files for all analyses (ensemble |
| 5 | +#' and/or sensitivity analysis) specified in the provided settings. Delegates |
| 6 | +#' the model-specific config writing to the appropriate `write.config.*` |
| 7 | +#' function (e.g. `write.config.ED2`, `write.config.SIPNET`). |
7 | 8 | #' |
| 9 | +#' @details |
| 10 | +#' **Upstream contract (reads from `settings$outdir`):** |
| 11 | +#' \describe{ |
| 12 | +#' \item{`samples.Rdata`}{Produced by \code{\link[PEcAn.uncertainty]{get.parameter.samples}}. |
| 13 | +#' Contains 5 bundled objects: `trait.samples`, |
| 14 | +#' `sa.samples`, `ensemble.samples`, `runs.samples`, `env.samples`. |
| 15 | +#' This function loads `trait.samples` and `sa.samples` to build |
| 16 | +#' model configuration files. If `input_design` contains a `param` |
| 17 | +#' column, `ensemble.samples` is rebuilt by subsetting `trait.samples` |
| 18 | +#' according to the design indices.} |
| 19 | +#' } |
| 20 | +#' |
| 21 | +#' **File-based side effects (saved to `settings$outdir`):** |
| 22 | +#' \describe{ |
| 23 | +#' \item{`sensitivity.samples.<ensemble_id>.Rdata`}{Contains `sa.run.ids` |
| 24 | +#' (named list of run IDs per PFT/trait/quantile), `sa.ensemble.id`, |
| 25 | +#' `sa.samples`, `pft.names`, and `trait.names`. Saved when sensitivity |
| 26 | +#' analysis is configured.} |
| 27 | +#' \item{`ensemble.samples.<ensemble_id>.Rdata`}{Contains `ens.run.ids` |
| 28 | +#' (vector of run IDs), `ens.ensemble.id`, `ens.samples`, `pft.names`, |
| 29 | +#' and `trait.names`. Saved when ensemble is configured.} |
| 30 | +#' \item{`runs_manifest.csv`}{A CSV table tracking all runs created, |
| 31 | +#' appended across ensemble and SA analyses.} |
| 32 | +#' } |
| 33 | +#' |
| 34 | +#' **Downstream contract:** The `sensitivity.samples.*.Rdata` and |
| 35 | +#' `ensemble.samples.*.Rdata` files are loaded by \code{\link[PEcAn.uncertainty]{get.results}} |
| 36 | +#' to match model outputs to their corresponding |
| 37 | +#' parameter sets. This implicit file-based coupling is a refactoring target. |
| 38 | +#' |
| 39 | +#' The default value for `posterior.files` is NA, in which case the |
| 40 | +#' most recent posterior or prior (in that order) for the workflow is used. |
| 41 | +#' When specified, `posterior.files` should be a vector of filenames with one |
| 42 | +#' entry for each PFT. Specify filenames with no path; PFT outdirs will be |
| 43 | +#' appended. This forces use of only files within this workflow, to avoid |
| 44 | +#' confusion. |
8 | 45 | #' |
9 | 46 | #' @param settings a PEcAn settings list |
10 | 47 | #' @param ensemble.size number of ensemble runs |
11 | | -#' @param input_design Input design data.frame coordinating input files across runs. |
12 | | -#' Contains columns for each sampled input (met, param, etc.) with row indices, |
13 | | -#' as documented in \code{runModule.run.write.configs()}. |
| 48 | +#' @param input_design Input design data.frame coordinating input files across |
| 49 | +#' runs. Contains columns for each sampled input (met, param, etc.) with row |
| 50 | +#' indices, as documented in \code{\link[PEcAn.workflow]{runModule.run.write.configs}}. |
14 | 51 | #' @param write should the runs be written to the database? |
15 | | -#' @param posterior.files Filenames for posteriors for drawing samples for ensemble and sensitivity |
16 | | -#' analysis (e.g. post.distns.Rdata, or prior.distns.Rdata) |
| 52 | +#' @param posterior.files Filenames for posteriors for drawing samples for |
| 53 | +#' ensemble and sensitivity analysis (e.g. `post.distns.Rdata`, or |
| 54 | +#' `prior.distns.Rdata`). |
17 | 55 | #' @param overwrite logical: Replace output files that already exist? |
18 | 56 | #' |
19 | | -#' @details The default value for \code{posterior.files} is NA, in which case the |
20 | | -#' most recent posterior or prior (in that order) for the workflow is used. |
21 | | -#' When specified, \code{posterior.files} should be a vector of filenames with one entry for each PFT. |
22 | | -#' Specify filenames with no path; PFT outdirs will be appended. This forces use of only |
23 | | -#' files within this workflow, to avoid confusion. |
24 | | -#' |
25 | | -#' @return an updated settings list, which includes ensemble IDs for SA and ensemble analysis |
| 57 | +#' @return The `settings` list (invisibly), updated with ensemble IDs for SA |
| 58 | +#' and ensemble analysis (e.g. `settings$sensitivity.analysis$ensemble.id`, |
| 59 | +#' `settings$ensemble$ensemble.id`). |
26 | 60 | #' @export |
27 | 61 | #' |
28 | 62 | #' @author David LeBauer, Shawn Serbin, Ryan Kelly, Mike Dietze, Akash B V |
|
0 commit comments