update doc for rrun.meta.analysis.R

Author: S1DDHEY

modules/meta.analysis/R/run.meta.analysis.R

@@ -183,16 +183,55 @@ check_consistent <- function(point, prior,
 }
 
 #' "Workflow" version of run.meta.analysis.pft
+#' #' Run Bayesian meta-analysis for a single PFT (file-based wrapper)
 #'
-#' Thin wrapper around `meta_analysis_standalone` that also reads/writes files 
-#' and registers results in the PEcAn database. 
+#' Thin wrapper around [meta_analysis_standalone()] that reads trait data and
+#' priors from disk, runs the meta-analysis, and saves results back to disk.
+#' Also registers result files in the BETYdb posteriors table.
+#'
+#' @details
+#' **Upstream contract (reads from `pft$outdir`):**
+#' \describe{
+#'   \item{`trait.data.Rdata`}{Named list of data frames produced by
+#'     [get.trait.data.pft()]. Loaded into `trait_env$trait.data`.}
+#'   \item{`prior.distns.Rdata`}{Data frame of prior distributions produced by
+#'     [get.trait.data.pft()]. Loaded into `prior_env$prior.distns`.}
+#' }
+#'
+#' **File-based side effects (saved to `pft$outdir`):**
+#' \describe{
+#'   \item{`trait.mcmc.Rdata`}{Contains `trait.mcmc`: a named list of
+#'     `mcmc.list` objects (one per trait) with posterior MCMC samples from
+#'     JAGS. Each element has columns `beta.o` (overall mean) and optionally
+#'     `sd.o` (overall SD).}
+#'   \item{`post.distns.MA.Rdata`}{Contains `post.distns`: a data frame with
+#'     one row per trait and columns `distn`, `parama`, `paramb`, `n`
+#'     summarizing the fitted posterior distribution.}
+#'   \item{`post.distns.Rdata`}{Symlink to `post.distns.MA.Rdata`.}
+#'   \item{`jagged.data.Rdata`}{Contains `jagged.data`: a named list of data
+#'     frames (one per trait) after the greenhouse screening and JAGSification
+#'     transform applied by [jagify()].}
+#' }
+#'
+#' **Downstream contract:** The files `trait.mcmc.Rdata` and
+#' `post.distns.Rdata` are expected by [get.parameter.samples()] (in
+#' `PEcAn.uncertainty`), which loads them to generate ensemble and sensitivity
+#' analysis samples. This implicit file-based coupling is a refactoring target.
+#'
+#' **Note:** The core computation is performed by [meta_analysis_standalone()],
+#' which accepts and returns R objects directly — see its documentation for
+#' the pure-function interface.
 #'
 #' @param pft (list) PFT list object, as defined in settings. Must include the
 #'  following: `outdir`, `name`, `posteriorid`
 #' @param dbfiles (character) directory where previous results are found
 #' @param dbcon (DBI connection object) BETY database connection object
-#' @param update (boolean; default = TRUE) If `TRUE`, replace existing
-#'  posteriors with new ones
+#' @param update (boolean; default = FALSE) If `TRUE`, replace existing
+#'   posteriors with new ones
+#'
+#' @return The `pft` list (invisibly), or `NA` if no trait data are available.
+#'   The function's primary outputs are communicated through files saved in
+#'   `pft$outdir`, not through the return value.
 #'
 #' @inheritParams meta_analysis_standalone
 run.meta.analysis.pft <- function(pft, iterations, random = TRUE, threshold = 1.2, dbfiles, dbcon, use_ghs = TRUE, update = FALSE) {
@@ -299,19 +338,22 @@ run.meta.analysis.pft <- function(pft, iterations, random = TRUE, threshold = 1.
 } # run.meta.analysis.pft
 
 ##--------------------------------------------------------------------------------------------------##
-##' Run meta analysis
+##' Run meta-analysis across all PFTs
+##'
+##' Iterates over a list of PFTs and runs [run.meta.analysis.pft()] for each
+##' one. This is the main entry point called by [runModule.run.meta.analysis()].
 ##'
 ##' This will use the following items from settings:
-##' - settings$pfts
-##' - settings$database$bety
-##' - settings$database$dbfiles
-##' - settings$meta.analysis$update
+##' - `settings$pfts`
+##' - `settings$database$bety`
+##' - `settings$database$dbfiles`
+##' - `settings$meta.analysis$update`
 ##'
 ##' @param pfts the list of pfts to get traits for
 ##' @param database database connection parameters
 ##' @param update logical: Rerun the meta-analysis if result files already exist?
 ##' @param threshold Gelman-Rubin convergence diagnostic, passed on to
-##'   \code{\link{pecan.ma.summary}}
+##'   [pecan.ma.summary()]
 ##' @inheritParams meta_analysis_standalone
 ##' @inheritParams run.meta.analysis.pft
 ##'