Fix bad GAM documentation

Author: araikes

R/ModelArray_Constructor.R

@@ -596,6 +596,8 @@ analyseOneElement.lm <- function(i_element,
 }
 
 #' Fit a GAM for a single element
+#'
+#' #' @description
 #' Returns metadata (column names, smooth term names, parametric term names,
 #' and the smoothing parameter criterion attribute name) used by
 #' \code{\link{ModelArray.gam}} to initialise the output data.frame. When

R/analyse.R

@@ -733,31 +733,51 @@ ModelArray.gam <- function(formula, data, phenotypes, scalar,
 #' Run a user-supplied function for element-wise data
 #'
 #' @description
-#' `ModelArray.wrap` runs a user-supplied function \code{FUN} at each
-#' requested element and returns a tibble of results combined across
-#' elements.
+#' `ModelArray.gam` fits a generalized additive model at each requested
+#' element in a \linkS4class{ModelArray} and returns a tibble of requested
+#' model statistics. There is no model-level p-value for GAMs, so there is
+#' no \code{correct.p.value.model} argument.
 #'
 #' @details
-#' This provides a generic framework reusing ModelArray's per-element
-#' looping, alignment, subject-thresholding, and parallelization. The user
-#' function is called as \code{FUN(data = dat, ...)} where \code{dat} is
-#' \code{phenotypes} with all scalar columns appended for the current
-#' element. The return value from \code{FUN} for a single element must be
-#' one of:
+#' You may request returning specific statistical variables by setting
+#' \code{var.*}, or you can get all by setting \code{full.outputs = TRUE}.
+#' Note that statistics covered by \code{full.outputs} or \code{var.*} are
+#' the ones from \code{broom::tidy()}, \code{broom::glance()}, and
+#' \code{summary.gam()} only, and do not include corrected p-values.
+#' However FDR-corrected p-values (\code{"fdr"}) are generated by default.
+#'
+#' List of acceptable statistic names for each of \code{var.*}:
 #' \itemize{
-#'   \item a one-row \code{data.frame} or \code{tibble}
-#'   \item a named list
-#'   \item a named atomic vector
+#'   \item \code{var.smoothTerms}: \code{c("edf", "ref.df", "statistic",
+#'     "p.value")}; From \code{broom::tidy(parametric = FALSE)}.
+#'   \item \code{var.parametricTerms}: \code{c("estimate", "std.error",
+#'     "statistic", "p.value")}; From \code{broom::tidy(parametric = TRUE)}.
+#'   \item \code{var.model}: \code{c("adj.r.squared", "dev.expl",
+#'     "sp.criterion", "scale", "df", "logLik", "AIC", "BIC", "deviance",
+#'     "df.residual", "nobs")}; From \code{broom::glance()} and
+#'     \code{\link[mgcv]{summary.gam}}.
 #' }
-#' The column names from the first successful element determine the final
-#' schema.
 #'
-#' Note: \code{ModelArray.wrap} never performs any p-value corrections or
-#' modifications. If you need adjusted p-values (e.g. FDR), implement
-#' them inside \code{FUN}.
+#' Smooth term names in the output are normalized: \code{s(age)} becomes
+#' \code{s_age}, \code{ti(x,z)} becomes \code{ti_x_z}, and
+#' \code{s(x):oFactor} becomes \code{s_x_BYoFactor}.
 #'
-#' Use \code{\link{exampleElementData}} to construct a sample per-element
-#' data.frame for testing your function before committing to a full run.
+#' For p-value corrections (arguments \code{correct.p.value.*}), supported
+#' methods include all methods in \code{p.adjust.methods} except
+#' \code{"none"}. You can request more than one method. FDR-corrected
+#' p-values (\code{"fdr"}) are calculated by default. Turn it off by
+#' setting to \code{"none"}.
+#'
+#' When \code{changed.rsq.term.index} is provided, a reduced model (dropping
+#' the specified term) is fit at each element to compute delta adjusted
+#' R-squared and partial R-squared. This approximately doubles execution
+#' time per requested term. The term index refers to the position on the
+#' right-hand side of \code{formula} (use \code{labels(terms(formula))} to
+#' see the ordering).
+#'
+#' Arguments \code{num.subj.lthr.abs} and \code{num.subj.lthr.rel} are
+#' mainly for input data with subject-specific masks, i.e. currently only
+#' for volume data. For fixel-wise data, you may ignore these arguments.
 #'
 #' @inheritParams ModelArray.lm
 #'
@@ -785,54 +805,58 @@ ModelArray.gam <- function(formula, data, phenotypes, scalar,
 #'   level for scalar writes. Default 4.
 #' @param ... Additional arguments forwarded to \code{FUN}.
 #'
-#' @return If \code{flag_initiate = TRUE}, a list with one component:
-#'   \describe{
-#'     \item{column_names}{Character vector. The column names derived from
-#'       the return value of \code{user_fun}, with \code{"element_id"}
-#'       prepended. For unnamed list or atomic returns, columns are named
-#'       \code{v1}, \code{v2}, etc. Set to \code{NaN} if the element was
-#'       skipped or errored.}
-#'   }
-#'   If \code{flag_initiate = FALSE}, a numeric vector of length
-#'   \code{num.stat.output} with \code{element_id} (0-based) first and
-#'   the coerced output of \code{user_fun} in subsequent positions.
-#'   All-\code{NaN} (except \code{element_id}) if the element was skipped
-#'   or if an error occurred with \code{on_error = "skip"}.
+#' @return A data.frame with one row per element. The first column is
+#'   \code{element_id} (0-based). Remaining columns contain the requested
+#'   statistics, named as \code{<term>.<statistic>} for per-term statistics
+#'   and \code{model.<statistic>} for model-level statistics. Smooth term
+#'   names are normalized (e.g. \code{s_age.statistic}). If p-value
+#'   corrections were requested, additional columns are appended with the
+#'   correction method as suffix (e.g. \code{s_age.p.value.fdr}). If
+#'   \code{changed.rsq.term.index} was requested, additional columns
+#'   \code{<term>.delta.adj.rsq} and \code{<term>.partial.rsq} are
+#'   appended.
 #'
 #' @seealso \code{\link{ModelArray.lm}} for linear models,
-#'   \code{\link{ModelArray.gam}} for GAMs,
-#'   \code{\link{exampleElementData}} for building test data,
-#'   \linkS4class{ModelArray} for the input class.
+#'   \code{\link{ModelArray.wrap}} for user-supplied functions,
+#'   \code{\link{gen_gamFormula_fxSmooth}} and
+#'   \code{\link{gen_gamFormula_contIx}} for formula helpers,
+#'   \linkS4class{ModelArray} for the input class,
+#'   \code{\link{ModelArray}} for the constructor,
+#'   \code{\link{exampleElementData}} for testing formulas on a single
+#'   element.
 #'
 #' @examples{
 #' \dontrun{
 #' ma <- ModelArray("path/to/data.h5", scalar_types = c("FD"))
 #' phenotypes <- read.csv("cohort.csv")
 #'
-#' # Simple custom function
-#' my_fun <- function(data, ...) {
-#'   mod <- lm(FD ~ age + sex, data = data)
-#'   tidy_out <- broom::tidy(mod)
-#'   # Return a one-row tibble
-#'   tibble::tibble(
-#'     age_estimate = tidy_out$estimate[tidy_out$term == "age"],
-#'     age_pvalue   = tidy_out$p.value[tidy_out$term == "age"]
-#'   )
-#' }
-#'
+#' # Fit GAM with default outputs
+#' results <- ModelArray.gam(
+#'   FD ~ s(age, fx = TRUE) + sex,
+#'   data = ma,
+#'   phenotypes = phenotypes,
+#'   scalar = "FD"
+#' )
+#' head(results)
 #'
-#' # Test on one element first
-#' test_df <- exampleElementData(ma, scalar = "FD",
-#'                                i_element = 1,
-#'                                phenotypes = phenotypes)
-#' my_fun(data = test_df)
+#' # With changed R-squared for the smooth term (term index 1)
+#' results_rsq <- ModelArray.gam(
+#'   FD ~ s(age, fx = TRUE) + sex,
+#'   data = ma,
+#'   phenotypes = phenotypes,
+#'   scalar = "FD",
+#'   changed.rsq.term.index = list(1)
+#' )
 #'
-#' # Run across all elements
-#' results <- ModelArray.wrap(
-#'   FUN = my_fun,
+#' # Full outputs, no p-value correction
+#' results_full <- ModelArray.gam(
+#'   FD ~ s(age, fx = TRUE) + sex,
 #'   data = ma,
 #'   phenotypes = phenotypes,
-#'   scalar = "FD"
+#'   scalar = "FD",
+#'   full.outputs = TRUE,
+#'   correct.p.value.smoothTerms = "none",
+#'   correct.p.value.parametricTerms = "none"
 #' )
 #' }
 #' }