Reduce across subjects (meta-analysis)

Usage

reduce(
  x,
  method = c("fixed", "random", "stouffer", "fisher"),
  weights = c("1/var", "n_eff", "equal", "custom"),
  by = "contrast",
  options = list(),
  formula = NULL,
  data = NULL
)

Arguments

x

A gds_plan, gds_source, or realised gds

method

Reduction method. Built-ins include "fixed", "random", "stouffer", and "fisher". Registry-backed reducers include meta-analytic regression reducers such as "meta:fe_reg" and the restricted repeated-measures Gaussian LMM reducers "lmm:ri", "lmm:ri_slope1", "lmm:ri_knownvar", and "lmm:ri_slope1_knownvar", plus permutation reducers "perm:onesample" and "perm:twosample".

weights

Weighting scheme ("1/var", "n_eff", "equal", "custom"). Registered reducers apply their own weighting, so only the default "1/var" is accepted for every reducer. "equal" is accepted for unweighted and evidence-combining reducers (e.g. "ols:voxelwise", "stouffer"); other schemes raise an error unless the reducer lists them in options_schema$weights. Unknown method names also raise an error.

by

Grouping variable (e.g., "contrast")

options

Additional reducer options. Common examples include tau2 = NULL, custom_weights, or for restricted LMM reducers list(fit = "REML", theta_mode = "pooled") plus list(slope = "time", covariance = "diag") for "lmm:ri_slope1".

Note: Current grouping is per-contrast. Values other than "contrast" are not interpreted yet; future versions may extend grouping to other factors in row_data/col_data.

Restricted repeated-measures LMM contract:

"lmm:ri" fits a Gaussian random-intercept model.
"lmm:ri_slope1" fits a Gaussian random intercept plus one within-subject slope.
The corresponding *_knownvar methods add the known diagonal sampling variance from var plus an estimated residual heterogeneity component.
Repeated-measure metadata must live on the contrast axis via with_contrast_data() or tabular ingestion with gds(..., contrast_data_cols = ...).
Unweighted methods allow theta_mode = "pooled" or "voxelwise"; known-variance methods currently require "voxelwise".
The supported family is intentionally narrow: one grouping factor only, Gaussian responses only, and no general random-effects formula grammar.

Permutation reducer contract:

"perm:onesample" performs an unweighted one-sample sign-flip t test for each sample and contrast.
"perm:twosample" performs an unweighted two-sample label-permutation t test. It can infer the tested two-level group column from formula and col_data, or use options$group directly.
Common options include n_perm, seed, alternative, and for "perm:twosample" variance = "welch" or "pooled".
Outputs include t_g, parametric p_g, permutation p_perm, and max-|t| family-wise p_fwer.

formula

Optional model formula. For meta-regression reducers the design is built from subject-level col_data. For repeated-measures LMM reducers, the formula specifies fixed effects at the subject-by-repeat level and must not contain lmer-style random-effects syntax.

data

Optional subject-keyed data frame to attach as col_data before execution-time construction of the model matrix.

Value

Updated plan

Details

reduce() always works on a lazy plan internally, so x is whichever stage of the fmrigds workflow you already have:

Start from files or another external source with gds(). That returns a gds_plan you can pipe directly into reduce().
Start from an in-memory result with a realised gds returned by compute() or created directly with new_gds(). reduce() will convert it with as_plan() for you.
You can also pass a low-level gds_source created by gds_source(), but most users do not need this because gds() creates the source binding automatically.

If you want that conversion to be explicit, use as_plan() before calling reduce().

For worked examples, see vignette("fmrigds") for the basic source -> plan -> compute workflow and vignette("as-plan-and-spatial-fdr") for chaining verbs on realised GDS objects.

Output assays

Reducers collapse the subject axis and write group-level assays (named on the realised GDS, retrievable with assays()/assay()):

"ols:voxelwise": per-term coef:<term>, se_coef:<term>, t_coef:<term>, p_coef:<term>, plus sigma2, df_res, n_obs (see reducer-ols-voxelwise).
"fixed"/"meta:fe" and "random"/"meta:re": beta_g, var_g, se_g, z_g, p_g, Q, I2, n_eff (random-effects also adds tau2). n_eff is the number of finite subject-level inputs used for each sample and contrast.
"meta:fe_reg"/"meta:re_reg": per-term coef:<term>, se_coef:<term>, normal-approximation z_coef:<term> and p_coef:<term>, plus Q, df_res (random-effects also adds tau2). "meta:re_reg" uses the DerSimonian–Laird meta-regression denominator $\mathrm{tr}\{W - WX(X^T W X)^{-1}X^T W\}$ and excludes rows with non-finite effects/design values or non-finite, nonpositive variances.
"stouffer"/"combine:stouffer": z_g, p_g.
"fisher"/"combine:fisher" and "combine:lancaster": chi2, df, p_g.
"perm:onesample"/"perm:twosample": beta_g, se_g, t_g, df, p_g, p_perm, p_fwer.