Package 'fmrigds'

Description

Lazy, format-agnostic group analysis for fMRI.

Details

fmrigds provides a common Group Data Set (GDS) abstraction for first-level fMRI outputs together with a lazy, plan-based workflow for group analysis. The package centers on a compact public grammar:

• gds() to open supported sources and create a plan

• subset(), derive(), align(), mask(), map_to(), reduce(), posthoc(), and write_out() to describe analysis steps

• compute() to execute the plan and return a realised GDS

Core capabilities include:

• Constructors for GDS objects and spaces

• Storage adapters (tabular, NIfTI, HDF5, fmristore)

• Statistical derivations and variance propagation helpers

• Reducer and post-hoc registries for group and meta-analytic workflows

• Provenance-aware export and inspection helpers

See the package reference and vignettes for supported workflows and release guidance.

Author(s)

Maintainer: Brad Buchsbaum [email protected]

See Also

Useful links:

• https://github.com/bbuchsbaum/fmrigds

• Report bugs at https://github.com/bbuchsbaum/fmrigds/issues

Description

Align subjects into a consensus space

Usage

align(x, family)

Arguments

Value

Updated plan

Description

Syntactic sugar around the map-family registry helpers.

Usage

register_alignment(x, family, overwrite = FALSE)

list_alignments(x)

get_alignment(x, name)

Arguments

Value

The updated object with the family registered

A character vector of registered alignment family names

The MapFamily entry or NULL if not found

Description

Apply a common mask to two realised GDS objects

Usage

apply_common_mask(g1, g2, rule = c("intersection", "union"))

Arguments

Value

A list with subsetted g1, g2, and indices idx1, idx2

Description

Convert a legacy rectangular GDS cube to a canonical frame

Usage

as_fmri_frame.gds(
  x,
  subject = NULL,
  contrast = NULL,
  assay_map = c(var = "variance", se = "std_error"),
  ...
)

Arguments

Value

An fmri_frame with one row per subject-contrast cell.

Description

Provides a lightweight front door for external packages holding data in memory (lists, arrays, data.frames) to construct a validated GDS without going through on-disk adapters.

Usage

as_gds(x, ...)

## S3 method for class 'list'
as_gds(
  x,
  space = NULL,
  subjects = NULL,
  contrasts = NULL,
  col_data = NULL,
  row_data = NULL,
  metadata = list(),
  ...
)

## S3 method for class 'array'
as_gds(
  x,
  space = NULL,
  subjects = NULL,
  contrasts = NULL,
  assay_name = "beta",
  col_data = NULL,
  row_data = NULL,
  metadata = list(),
  ...
)

## S3 method for class 'data.frame'
as_gds(
  x,
  mapping = NULL,
  space = NULL,
  col_data = NULL,
  row_data = NULL,
  contrast_data = NULL,
  metadata = list(),
  ...
)

## S3 method for class 'nftab'
as_gds(x, feature = NULL, ...)

Arguments

Value

A gds object

Description

This compatibility projection is deliberately strict. The selected observation annotations must define one complete, unique Cartesian product of subject and contrast keys. Ragged frames remain frames and are rejected rather than padded with implicit slabs.

Usage

## S3 method for class 'fmri_frame'
as_gds(
  x,
  subject = "subject_id",
  contrast = "contrast_id",
  subjects = NULL,
  contrasts = NULL,
  assay_names = names(fmridataset::assays(x)),
  assay_map = NULL,
  memory_budget = 2 * 1024^3,
  metadata = list(),
  ...
)

Arguments

Value

A realized legacy gds compatibility projection.

Description

Create a GDS plan from an image catalog. The catalog's assay mappings determine which files are used for the beta assay and, optionally, one uncertainty assay (se or var); mapping any other assay is an error. When the catalog has a subject column, its values become the GDS subject labels and uncertainty files are paired with beta files by subject; subject-level metadata from the catalog is attached as col_data.

Usage

## S3 method for class 'image_catalog'
as_gds(x, mask = NULL, ...)

Arguments

Value

A gds_plan object.

Examples

if (requireNamespace("neuroim2", quietly = TRUE) &&
    requireNamespace("RNifti", quietly = TRUE)) {
  # Write tiny 4x4x2 beta and SE maps for three subjects
  root <- tempfile("study_")
  for (s in c("01", "02", "03")) {
    d <- file.path(root, paste0("sub-", s), "stats")
    dir.create(d, recursive = TRUE)
    RNifti::writeNifti(array(rnorm(32), c(4, 4, 2)),
                       file.path(d, paste0("sub-", s, "_beta.nii.gz")))
    RNifti::writeNifti(array(0.5, c(4, 4, 2)),
                       file.path(d, paste0("sub-", s, "_se.nii.gz")))
  }

  catalog <- image_catalog(root, "sub-*/stats/*.nii.gz",
                           path_regex = "sub-(?<subject>[^/]+)") |>
    map_assays(beta = "_beta", se = "_se")

  plan <- as_gds(catalog)
  result <- compute(plan)
  print(result)

  unlink(root, recursive = TRUE)
}

Description

Import a neuroim2::NeuroVec (4D brain volume) as a GDS object. The 4th dimension can represent subjects OR contrasts.

Usage

## S3 method for class 'NeuroVec'
as_gds(
  x,
  assay_name = "beta",
  along = c("subject", "contrast"),
  subjects = NULL,
  contrasts = NULL,
  mask = NULL,
  ...
)

## S3 method for class 'DenseNeuroVec'
as_gds(
  x,
  assay_name = "beta",
  along = c("subject", "contrast"),
  subjects = NULL,
  contrasts = NULL,
  mask = NULL,
  ...
)

Arguments

Value

A gds object with voxel space.

Examples

if (requireNamespace("neuroim2", quietly = TRUE)) {
  sp4 <- neuroim2::NeuroSpace(c(4, 4, 2, 3), spacing = c(2, 2, 2))
  vec4d <- neuroim2::NeuroVec(array(rnorm(96), c(4, 4, 2, 3)), sp4)

  # 4D volume where each volume is a subject
  gds_obj <- as_gds(vec4d, along = "subject",
                    subjects = c("sub-01", "sub-02", "sub-03"))
  print(subjects(gds_obj))

  # 4D volume where each volume is a contrast
  gds_obj <- as_gds(vec4d, along = "contrast",
                    contrasts = c("faces", "places", "objects"))
  print(contrasts(gds_obj))
}

Description

Import a single neuroim2::NeuroVol (3D brain volume) as a GDS object. The volume becomes a single subject with a single contrast.

Usage

## S3 method for class 'NeuroVol'
as_gds(
  x,
  assay_name = "beta",
  subject = "subject1",
  contrast = "contrast1",
  mask = NULL,
  ...
)

## S3 method for class 'DenseNeuroVol'
as_gds(
  x,
  assay_name = "beta",
  subject = "subject1",
  contrast = "contrast1",
  mask = NULL,
  ...
)

Arguments

Value

A gds object with voxel space.

Examples

if (requireNamespace("neuroim2", quietly = TRUE)) {
  sp <- neuroim2::NeuroSpace(c(4, 4, 2), spacing = c(2, 2, 2))
  vol <- neuroim2::NeuroVol(array(rnorm(32), c(4, 4, 2)), sp)
  gds_obj <- as_gds(vol, subject = "sub-01", contrast = "faces")
  print(gds_obj)
}

Description

Extract a single assay from a GDS object and return it as a neuroim2::NeuroVec (4D neuroimaging array), stacking along the 4th dimension.

Usage

as_neurovec(
  x,
  assay = "beta",
  along = c("subject", "contrast", "both"),
  subset_subjects = NULL,
  subset_contrasts = NULL
)

Arguments

Value

A neuroim2::NeuroVec object with dimensions ⁠[x, y, z, n]⁠ where n depends on the along parameter.

Examples

if (requireNamespace("neuroim2", quietly = TRUE)) {
  sp4 <- neuroim2::NeuroSpace(c(4, 4, 2, 4), spacing = c(2, 2, 2))
  vec4d <- neuroim2::NeuroVec(array(rnorm(128), c(4, 4, 2, 4)), sp4)
  gds <- as_gds(vec4d, along = "subject", subjects = paste0("sub0", 1:4))

  # Stack all subjects into a 4D volume
  vec <- as_neurovec(gds, assay = "beta", along = "subject")
  print(dim(vec))

  # Stack specific subjects
  vec <- as_neurovec(gds, assay = "beta", along = "subject",
                     subset_subjects = c("sub01", "sub02"))
  print(dim(vec))
}

Description

Extract a single assay from a GDS object and return it as a list of neuroim2::NeuroVol objects, one per subject/contrast combination.

Usage

as_neurovol_list(
  x,
  assay = "beta",
  by = c("subject", "contrast"),
  drop_dim = TRUE
)

Arguments

Value

A named list of neuroim2::NeuroVol objects. The structure depends on the by parameter and the dimensions of the data:

• Single contrast, by = "subject": list of NeuroVol named by subject

• Single subject, by = "contrast": list of NeuroVol named by contrast

• Multiple of both: nested list ⁠[[subject]][[contrast]]⁠

Examples

if (requireNamespace("neuroim2", quietly = TRUE)) {
  sp4 <- neuroim2::NeuroSpace(c(4, 4, 2, 4), spacing = c(2, 2, 2))
  vec4d <- neuroim2::NeuroVec(array(rnorm(128), c(4, 4, 2, 4)), sp4)
  gds <- as_gds(vec4d, along = "subject", subjects = paste0("sub0", 1:4))

  # Extract beta maps as list of NeuroVols (one per subject)
  vols <- as_neurovol_list(gds, assay = "beta")
  print(names(vols))
  print(vols$sub01)  # NeuroVol for subject "sub01"

  # Extract by contrast (here: one subject with three contrasts)
  sp3 <- neuroim2::NeuroSpace(c(4, 4, 2, 3), spacing = c(2, 2, 2))
  vec_con <- neuroim2::NeuroVec(array(rnorm(96), c(4, 4, 2, 3)), sp3)
  gds_con <- as_gds(vec_con, along = "contrast",
                    contrasts = c("faces", "places", "objects"))
  vols_by_con <- as_neurovol_list(gds_con, assay = "beta", by = "contrast")
  print(names(vols_by_con))
}

Description

Ensure an object is a plan

Usage

as_plan(x)

Arguments

Value

A plan object

Description

Extract a single assay from a GDS object

Usage

assay(x, name = "beta", ...)

Arguments

Value

A 3D array

Description

Retrieve assay metadata

Usage

assay_info(name)

Arguments

Value

Assay metadata list or NULL if not found

Description

Extract assays from a GDS object

Usage

assays(x)

Arguments

Value

Named list of 3D arrays

Description

Assert compatibility between two spaces

Usage

assert_compatible_spaces(g1, g2, fields = c("type", "dim", "template_id"))

Arguments

Value

TRUE if compatible; otherwise errors

Examples

sp1 <- space_voxel(c(2,2,2), diag(4), storage = "dense")
sp2 <- space_voxel(c(2,2,2), diag(4), storage = "dense")
assert_compatible_spaces(sp1, sp2)

Description

Apply regex patterns to filenames or paths to extract values for new metadata columns.

Usage

assign_meta(
  catalog,
  column,
  pattern,
  source = "basename",
  replacement = "\\1"
)

Arguments

Value

Updated image_catalog.

Examples

root <- tempfile("study_")
d <- file.path(root, "sub-01")
dir.create(d, recursive = TRUE)
invisible(file.create(file.path(d, c("run-1_faces.nii", "run-2_faces.nii",
                                     "run-1_houses.nii"))))
catalog <- image_catalog(root, "sub-*/*.nii")

catalog <- assign_meta(catalog, "run", "run-([0-9]+)", source = "basename")
catalog <- assign_meta(catalog, "contrast", "_([^_]+)\\.nii", replacement = "\\1")
catalog$metadata[, c("basename", "run", "contrast")]

unlink(root, recursive = TRUE)

Description

Stores a weight array as an assay. Note that none of the built-in registered reducers currently consume custom weight assays: reduce() refuses weights = "custom" (and "n_eff") unless the selected reducer declares support for that scheme, rather than silently ignoring it.

Usage

attach_weight(g, name, array)

Arguments

Value

Updated GDS with weights stored in assays

Examples

beta <- array(0, dim = c(2,2,1)); var <- array(1, dim = c(2,2,1))
g <- new_gds(list(beta = beta, var = var), space_sample_labels(c("a","b")), c("s1","s2"), "c1")
w <- array(1, dim = c(2,2,1))
g2 <- attach_weight(g, "w_custom", w)

Description

Returns a samples x terms x contrasts array by stacking per-term coefficient assays (e.g., coef:(Intercept), coef:age, ...) along a new terms dimension.

Usage

coef_array(gds, prefix = "coef:")

Arguments

Value

A 3D numeric array ⁠samples x terms x contrasts⁠

Description

Retrieve packed covariance triangles for OLS coefficients

Usage

coef_cov_tri(gds, method = "ols:voxelwise", contrast)

Arguments

Value

A list with fields type, terms, pack, and cov_tri (L x samples)

Description

Extract column (subject) metadata from a GDS object

Usage

col_data(x)

Arguments

Value

Data frame with subject-level metadata

Description

Compute a common mask between two spaces

Usage

common_mask(g1, g2, rule = c("intersection", "union"))

Arguments

Value

A list with integer indices idx1 and idx2 for subsetting each

Examples

m1 <- array(c(TRUE, FALSE, TRUE, TRUE), c(2, 2, 1))
m2 <- array(c(TRUE, TRUE, FALSE, TRUE), c(2, 2, 1))
sp1 <- space_voxel(c(2,2,1), diag(4), mask_bitmap = m1,
  storage = "packed")
sp2 <- space_voxel(c(2,2,1), diag(4), mask_bitmap = m2,
  storage = "packed")
common_mask(sp1, sp2, rule = "intersection")

Description

Materialise a plan into a realised GDS

Usage

compute(
  x,
  sink = c("memory", "h5"),
  path = NULL,
  sink_options = list(),
  block = NULL,
  assays = NULL,
  ...
)

Arguments

Value

A realised gds object

Description

Extract contrast-level metadata from a GDS object

Usage

contrast_data(x)

Arguments

Value

Data frame with one row per contrast/repeated-measure level

Description

For objects that are not GDS objects or plans (for example factors), the default method delegates to stats::contrasts(), so attaching fmrigds does not break base model-contrast code.

Usage

contrasts(x, ...)

Arguments

Value

Character vector of contrast names

Description

Record a derivation operation in a plan

Usage

derive(x, what = c("var", "se", "t", "z"), options = list())

Arguments

Value

Updated plan

Description

Detect the best adapter for a source

Usage

detect_adapter(source, prefer = NULL)

Arguments

Value

Adapter name

Description

examination_control() validates the bounded execution, residual-geometry, review, staging, and numerical settings used by examine_group(). Keeping these settings in a typed object makes defaults visible and reproducible.

Usage

examination_control(
  block_size = 1024L,
  geometry = list(rank = 32L, oversample = 8L, cap = 8, balance_contrasts = TRUE,
    stability_replicates = 2L),
  review = list(surprise = list(energy_threshold = 2.5, tail_threshold = 0.01,
    residual_threshold = 3), influence = list(energy_threshold = 1, max_abs_threshold =
    2), quality = list(coverage_fraction = list(direction = "low", threshold = 0.8)),
    min_stability = 0.7),
  exact_refit_n = 5L,
  retain_n = 5L,
  staging = list(tempdir = NULL),
  tolerance = list(rank = sqrt(.Machine$double.eps), leverage = 1e-08, degeneracy =
    1e-12)
)

Arguments

Value

An object of class gds_examination_control.

Description

examine_group() branches from subject-level data at a group reducer. It reports model-conditioned predictive surprise separately from each subject's exact influence on requested group estimands. It never deletes a subject or rewrites the source analysis.

Usage

examine_group(
  x,
  method = NULL,
  formula = NULL,
  options = list(),
  quality = NULL,
  estimands = NULL,
  retain = NULL,
  control = examination_control(),
  na_action = c("fail", "exclude")
)

Arguments

Details

When x already contains one reducer, the examination inherits that reducer's method, formula, options, and weighting semantics. Supplying model overrides in that case is an error. When no reducer is present, method is required and formula-driven reducers default to ~ 1.

Value

A gds_examination object.

Result contract

The returned object keeps spatial maps in ordinary GDS objects and keeps subject, contrast, estimand, availability, sensitivity, and provenance data in tables or named lists. subject_data$review_priority orders inspection; subject_data$review_status changes to "review" only when an absolute, stability-aware criterion is met. Random-effects screening is labeled "tau2_fixed_full"; exact retained-subject refits are labeled "tau2_refit_exact" and never alter the original review queue.

Examples

subject_ids <- paste0("sub-", 1:8)
participant_data <- data.frame(
  group = factor(rep(c("control", "patient"), each = 4)),
  row.names = subject_ids
)
beta <- array(rnorm(12 * 8, sd = 0.2), c(12, 8, 1))
beta[, participant_data$group == "patient", 1] <-
  beta[, participant_data$group == "patient", 1] + 0.4
variance <- array(0.1, dim(beta))
subject_gds <- new_gds(
  assays = list(beta = beta, var = variance),
  space = space_sample_labels(paste0("feature-", 1:12)),
  subjects = subject_ids,
  contrasts = "task",
  col_data = participant_data
)
analysis <- as_plan(subject_gds) |>
  reduce(method = "meta:re_reg", formula = ~ group)
exam <- examine_group(
  analysis,
  estimands = "grouppatient",
  control = examination_control(retain_n = 2L)
)
summary(exam)
if (requireNamespace("ggplot2", quietly = TRUE)) plot(exam)

Description

Human-readable summary of a realised GDS or a lazy gds_plan.

Usage

explain(x)

## S3 method for class 'gds'
print(x, ...)

## S3 method for class 'gds_plan'
print(x, ...)

Arguments

Value

Invisibly returns x (and prints a summary)

Description

Explain a plan's operations in a tidy table

Usage

explain_plan(plan)

Arguments

Value

A data.frame with one row per node (printed and returned invisibly)

Description

Convenience function that combines split.gds() and as_neurovol_list() to extract neuroimaging volumes for subjects in a specific group.

Usage

extract_group(x, group_var, group_level, assay = "beta", ...)

Arguments

Value

A named list of neuroim2::NeuroVol objects for subjects in the specified group.

Examples

if (requireNamespace("neuroim2", quietly = TRUE)) {
  sp4 <- neuroim2::NeuroSpace(c(4, 4, 2, 4), spacing = c(2, 2, 2))
  vec4d <- neuroim2::NeuroVec(array(rnorm(128), c(4, 4, 2, 4)), sp4)
  gds <- as_gds(vec4d, along = "subject", subjects = paste0("sub0", 1:4))
  gds <- with_col_data(gds, data.frame(
    diagnosis = c("patient", "control", "patient", "control"),
    row.names = subjects(gds)
  ))

  # Get beta maps for all patients
  patient_vols <- extract_group(gds, "diagnosis", "patient", assay = "beta")
  print(names(patient_vols))

  # Get beta maps for controls
  control_vols <- extract_group(gds, "diagnosis", "control", assay = "beta")
  print(names(control_vols))
}

Description

Convenience helper to discover NIfTI map files on disk using a flexible regular-expression pattern. This is intended for quick "scooping up" of first-level maps spread across a directory tree (e.g. ⁠.*/maps/AUC.nii⁠).

Usage

find_maps(
  root,
  pattern = "\\.nii(\\.gz)?$",
  recursive = TRUE,
  subject_fun = NULL,
  contrast_fun = NULL
)

Arguments

Details

The function does not impose any file naming convention. Instead, callers can provide optional subject_fun and contrast_fun hooks to derive subject and contrast labels from file paths.

Value

A data.frame with columns file, subject, and contrast.

Description

fit_group() is the eager convenience wrapper for group_plan() followed by compute(). The default known-variance random-intercept model is ⁠diag(sampling_variance) + vc_resid I + vc_intercept Z Z'⁠; other registered frame kernels may use different input and model contracts.

Usage

fit_group(
  frame,
  estimate = "beta",
  variance = "variance",
  design,
  memory_budget = 256 * 1024^2,
  block_size = NULL,
  fit = c("REML", "ML"),
  method = "lmm:ri_knownvar",
  options = list()
)

Arguments

Value

An fmri_group_fit whose result is an fmri_frame sharing the input feature IDs and spatial domain.

Description

Create a Group Data Set (GDS)

Adapter front door for building a plan

Usage

new_gds(
  assays,
  space,
  subjects,
  contrasts,
  col_data = NULL,
  row_data = NULL,
  metadata = list()
)

gds(source, format = c("auto", ls(.adapter_registry)), prefer = NULL, ...)

Arguments

Value

An object of class c("gds", "group_data")

A gds_plan

Description

The most flexible import function for creating GDS objects from neuroim2 data. Supports multiple subjects and multiple contrasts, with proper variance/SE handling.

Usage

gds_from_neurovol_nested(
  beta,
  var = NULL,
  se = NULL,
  contrasts = NULL,
  mask = NULL,
  col_data = NULL,
  metadata = list(),
  ...
)

Arguments

Value

A gds object with dimensions ⁠samples x subjects x contrasts⁠.

Examples

if (requireNamespace("neuroim2", quietly = TRUE)) {
  sp <- neuroim2::NeuroSpace(c(4, 4, 2), spacing = c(2, 2, 2))
  make_vol <- function(x) neuroim2::NeuroVol(array(x, c(4, 4, 2)), sp)
  subj <- c("sub-01", "sub-02")

  # Example 1: Nested list structure (subjects x contrasts)
  beta <- lapply(stats::setNames(subj, subj), function(s)
    list(faces = make_vol(rnorm(32)), places = make_vol(rnorm(32))))
  var <- lapply(stats::setNames(subj, subj), function(s)
    list(faces = make_vol(runif(32, 0.5, 1.5)),
         places = make_vol(runif(32, 0.5, 1.5))))

  gds_obj <- gds_from_neurovol_nested(beta, var = var)
  print(gds_obj)

  # Example 2: List of 4D NeuroVecs (each subject has a multi-contrast 4D image)
  sp4 <- neuroim2::NeuroSpace(c(4, 4, 2, 3), spacing = c(2, 2, 2))
  beta_vecs <- lapply(stats::setNames(subj, subj), function(s)
    neuroim2::NeuroVec(array(rnorm(96), c(4, 4, 2, 3)), sp4))
  # Without variance maps a unit-variance placeholder is used (with a warning)
  gds_obj <- gds_from_neurovol_nested(beta_vecs,
                                      contrasts = c("faces", "places", "objects"))
  print(contrasts(gds_obj))
}

Description

Import matched lists of NeuroVol objects (e.g., beta and variance maps) into a GDS. This handles the common case of multiple subjects with a single contrast. For multiple contrasts, use gds_from_neurovol_nested().

Usage

gds_from_neurovols(
  beta,
  var = NULL,
  se = NULL,
  contrast = "contrast1",
  mask = NULL,
  col_data = NULL,
  ...
)

Arguments

Value

A gds object.

Examples

if (requireNamespace("neuroim2", quietly = TRUE)) {
  sp <- neuroim2::NeuroSpace(c(4, 4, 2), spacing = c(2, 2, 2))
  make_vol <- function(x) neuroim2::NeuroVol(array(x, c(4, 4, 2)), sp)

  # Beta and variance maps for each subject
  beta_vols <- list(
    `sub-01` = make_vol(rnorm(32)),
    `sub-02` = make_vol(rnorm(32)),
    `sub-03` = make_vol(rnorm(32))
  )
  var_vols <- lapply(beta_vols, function(v) make_vol(runif(32, 0.5, 1.5)))

  gds_obj <- gds_from_neurovols(beta_vols, var = var_vols)
  print(gds_obj)

  # With subject covariates
  covars <- data.frame(age = c(25, 30, 35), group = c("A", "B", "A"),
                       row.names = c("sub-01", "sub-02", "sub-03"))
  gds_obj <- gds_from_neurovols(beta_vols, var = var_vols, col_data = covars)
  print(col_data(gds_obj))
}

Description

This helper builds on the NIfTI adapter to materialise a realised GDS from a set of NIfTI map files, typically obtained via find_maps(). The heavy lifting (reading NIfTI, spatial metadata, masking) is delegated to the existing NIfTI adapter and the neuroim2 package.

Usage

gds_from_nifti_maps(maps, mask = NULL, ...)

Arguments

Details

Subject and contrast labels can be injected post-hoc using the subject and contrast columns when available in maps. This avoids hard-coding any filename convention while still allowing callers to impose semantics via hooks.

This helper is single-contrast: every file in maps$file is loaded as one map per subject along a single contrast axis. A contrast column is used only to label that one contrast (all non-missing values must agree); it does not pivot a long subject x contrast table into a grid. For multi-contrast workflows, call gds_from_nifti_maps() once per contrast and combine the results, or assemble the source manually with nifti_source().

Beta-only raw maps are accepted. When no variance or standard-error maps are available, the realised GDS contains a synthetic var assay filled with 1 and a warning is emitted. This placeholder variance is useful for satisfying the GDS assay contract, but it is not meaningful subject-level uncertainty. For group analyses over subject-level searchlight or stat-map metrics, prefer an unweighted reducer such as method = "ols:voxelwise" instead of fixed/random-effects meta-analysis.

Value

A realised GDS object.

Examples

if (requireNamespace("neuroim2", quietly = TRUE) &&
    requireNamespace("RNifti", quietly = TRUE)) {
  # Write tiny 4x4x2 subject-level maps for four subjects
  dir <- tempfile("maps_")
  dir.create(dir)
  subj <- c("1001", "1002", "1003", "1004")
  files <- file.path(dir, paste0(subj, "_naive_diag_mean.nii.gz"))
  for (f in files) RNifti::writeNifti(array(rnorm(32), c(4, 4, 2)), f)

  # NOTE: `contrast` is a single label here. gds_from_nifti_maps() is
  # single-contrast; to analyse several contrasts, subset `maps` and call
  # once per contrast (a multi-valued `contrast` column triggers a warning).
  maps <- data.frame(
    file = files,
    subject = subj,
    contrast = "naive_diag_mean"
  )

  group_info <- data.frame(
    group = c("control", "control", "patient", "patient"),
    row.names = maps$subject
  )

  # Beta-only maps: a unit-variance placeholder is added (with a warning)
  g <- gds_from_nifti_maps(maps) |>
    with_col_data(group_info)

  fit <- reduce(g, method = "ols:voxelwise", formula = ~ group) |>
    compute()
  print(names(assays(fit)))

  unlink(dir, recursive = TRUE)
}

Description

gds_from_scalar_maps() is a semantic wrapper for beta-only/stat-map workflows: each NIfTI is a subject-level metric map rather than a first-level beta image with meaningful uncertainty. The resulting GDS uses the NIfTI adapter's unit-variance placeholder behavior for beta-only sources.

Usage

gds_from_scalar_maps(
  files,
  subject = NULL,
  contrast = "map",
  col_data = NULL,
  mask = NULL,
  ...
)

as_scalar_map_gds(
  files,
  subject = NULL,
  contrast = "map",
  col_data = NULL,
  mask = NULL,
  ...
)

Arguments

Value

A realised gds object.

Examples

if (requireNamespace("neuroim2", quietly = TRUE) &&
    requireNamespace("RNifti", quietly = TRUE)) {
  # Write tiny 4x4x2 subject-level metric maps for four subjects
  dir <- tempfile("scalar_maps_")
  dir.create(dir)
  subj <- c("sub-01", "sub-02", "sub-03", "sub-04")
  files <- file.path(dir, paste0(subj, "_auc.nii.gz"))
  for (f in files) RNifti::writeNifti(array(rnorm(32), c(4, 4, 2)), f)
  participants <- data.frame(subject = subj,
                             group = c("control", "control", "patient", "patient"))

  # Beta-only maps: a unit-variance placeholder is added (with a warning)
  g <- gds_from_scalar_maps(
    files = files,
    subject = subj,
    contrast = "auc",
    col_data = participants
  )
  print(g)
  fit <- group_ols(g, ~ group) |> compute()

  unlink(dir, recursive = TRUE)
}

Description

Construct default metadata for a GDS object

Usage

gds_metadata(
  schema_version = "0.1.0",
  units = list(),
  provenance = list(graph = list(), log = character(), digest = NULL),
  software = list(package = "fmrigds", version = .pkg_version(), R_version =
    getRversion()),
  alignment = NULL,
  map_families = list(),
  mask_info = NULL,
  contrast_info = NULL,
  design_mats = NULL,
  notes = NULL,
  created = Sys.time()
)

Arguments

Value

Metadata list

Description

Define a plan source (adapter binding)

Usage

gds_source(adapter, source_spec, probe_result = NULL)

Arguments

Value

Source descriptor

Description

Public wrapper around the internal tidy frame builder used by CSV/Parquet exporters. Returns a data.frame; if you prefer a tibble, wrap with tibble::as_tibble().

Usage

gds_to_tibble(gds, assays = NULL, drop_na = FALSE, include_col_data = FALSE)

Arguments

Value

A data.frame in long form with columns sample, subject, contrast, plus one column per requested assay.

Description

Retrieve a registered adapter

Usage

get_adapter(name)

Arguments

Value

Adapter list

Description

Retrieve a registered map family by name

Usage

get_map_family(x, name)

Arguments

Value

A MapFamily object

Description

Get post-hoc method by name

Usage

get_posthoc(name)

Arguments

Value

A list with fields name, fun, requires, provides, or NULL if not found

Description

Get reducer by name

Usage

get_reducer(name)

Arguments

Value

Reducer list or NULL if not found

Description

These helpers wrap reduce(method = "ols:voxelwise") for subject-level map workflows. They return a lazy GDS plan; call compute() to materialise the fitted maps.

Usage

group_ols(x, formula = ~1, col_data = NULL, options = list(), ...)

one_sample(x, subset = NULL, col_data = NULL, options = list(), ...)

two_sample(
  x,
  group = "group",
  baseline = NULL,
  level = NULL,
  col_data = NULL,
  options = list(),
  ...
)

Arguments

Value

A gds_plan with an OLS reduce node.

Examples

# Synthetic voxel-like data: 5 samples x 4 subjects x 1 contrast
beta <- array(rnorm(5 * 4), c(5, 4, 1))
var <- array(1, c(5, 4, 1))
g <- new_gds(list(beta = beta, var = var), space_sample_labels(letters[1:5]),
             subjects = paste0("s", 1:4), contrasts = "c1",
             col_data = data.frame(group = c("control", "control",
                                             "patient", "patient"),
                                   row.names = paste0("s", 1:4)))

fit <- group_ols(g, ~ group) |> compute()
names(assays(fit))
one <- one_sample(g) |> compute()
two <- two_sample(g, group = "group", baseline = "control") |> compute()

Description

group_plan() compiles design metadata and resolves stable axis IDs without reading imaging assays. Numerical values are read only by compute(), in bounded feature blocks, and dispatched through the selected reducer's frame execution contract.

Usage

group_plan(
  frame,
  design,
  method = "lmm:ri_knownvar",
  estimate = "beta",
  variance = "variance",
  memory_budget = 256 * 1024^2,
  block_size = NULL,
  options = list()
)

Arguments

Value

A serializable fmri_group_plan.

Description

Harmonise contrast names in a GDS

Usage

harmonise_contrasts(g, map)

Arguments

Value

Updated GDS with renamed contrasts

Examples

beta <- array(0, dim = c(2,1,2), dimnames = list(NULL, "s1", c("a","b")))
var <- beta
g <- new_gds(list(beta = beta, var = var), space_sample_labels(c("x","y")), "s1", c("a","b"))
harmonise_contrasts(g, c(a = "A", b = "B"))

Description

Sweeps a directory tree for files matching a glob pattern and extracts metadata from file paths using regex capture groups.

Usage

image_catalog(root, pattern = "**/*.nii*", path_regex = NULL, recursive = TRUE)

Arguments

Value

An image_catalog object.

Examples

# Create a small study tree (empty placeholder files are enough for discovery)
root <- tempfile("study_")
for (s in c("01", "02", "03")) {
  d <- file.path(root, paste0("sub-", s), "analysis")
  dir.create(d, recursive = TRUE)
  invisible(file.create(file.path(d, c("cope1.nii.gz", "varcope1.nii.gz"))))
}

# Discover files with subject extraction
catalog <- image_catalog(
  root = root,
  pattern = "sub-*/analysis/*.nii.gz",
  path_regex = "sub-(?<subject>[^/]+)"
)
catalog
catalog$metadata[, c("basename", "subject")]

unlink(root, recursive = TRUE)

Description

Merge a data frame with the catalog metadata by a key column.

Usage

join_meta(catalog, data, by, suffix = ".external")

Arguments

Value

Updated image_catalog.

Examples

# Build a tiny study tree with empty placeholder files
root <- tempfile("study_")
for (s in c("01", "02")) {
  d <- file.path(root, paste0("sub-", s))
  dir.create(d, recursive = TRUE)
  invisible(file.create(file.path(d, c("cope1.nii.gz", "varcope1.nii.gz"))))
}
catalog <- image_catalog(root, "sub-*/*.nii.gz",
                         path_regex = "sub-(?<subject>[^/]+)")

demographics <- data.frame(subject = c("01", "02"), age = c(25, 30))
catalog <- join_meta(catalog, demographics, by = "subject")
catalog$metadata[, c("basename", "subject", "age")]

unlink(root, recursive = TRUE)

Description

Discoverability helper for finding assay names to pass to assay(), write_nifti_assays(), or write_out() without having to run a job and inspect names(assays(fit)). Works on a realised gds, a lazy gds_plan/gds_source (reporting the input assays the source probed), or—when reducer is supplied—reports a reducer's declared output stems without computing anything.

Usage

list_assays(x, reducer = NULL, info = TRUE)

Arguments

Value

A data frame (or a character vector when info = FALSE).

See Also

assays(), assay(), assay_info(), list_reducers(), list_posthoc(), write_nifti_assays()

Examples

beta <- array(rnorm(5 * 4), c(5, 4, 1))
var <- array(1, c(5, 4, 1))
g <- new_gds(list(beta = beta, var = var), space_sample_labels(letters[1:5]),
             subjects = paste0("s", 1:4), contrasts = "c1")

fit <- one_sample(g) |> compute()
list_assays(fit)                       # names + roles of computed assays
list_assays(reducer = "meta:re")       # what random-effects would produce

Description

List registered map families

Usage

list_map_families(x)

Arguments

Value

Character vector of family names

Description

List registered post-hoc methods

Usage

list_posthoc()

Value

A sorted character vector of registered post-hoc method names.

See Also

posthoc-methods for what each method outputs.

Description

List registered reducers

Usage

list_reducers()

Value

A sorted character vector of registered reducer names.

See Also

list_assays() to preview a reducer's output assays.

Description

Load a plan from JSON

Usage

load_plan(file)

Arguments

Value

A gds_plan. A warning is issued when the digest stored in the file does not match the reconstructed plan (e.g. the file was edited).

Security

Map families and map_linear operators are restored with base::unserialize(), which can execute arbitrary code embedded in a crafted file. Only call load_plan() on files you created or otherwise trust.

Description

Convenience helpers to create and register alignments

Usage

make_linear_family(
  name,
  from,
  to,
  operators_by_subject,
  uncertainty = UncertaintyRule("independent")
)

Arguments

Value

A MapFamily

Examples

from <- space_parcels(c("R1","R2"))
to   <- space_parcels(c("G1","G2"))
ops <- list(s1 = diag(2), s2 = diag(2))
fam <- make_linear_family("lin", from, to, ops)

Description

Create a warp-based alignment family from on-disk paths

Usage

make_warp_family(
  name,
  from,
  to,
  warp_paths,
  loader,
  uncertainty = UncertaintyRule("independent")
)

Arguments

Value

A MapFamily (type = deform3d)

Examples

loader <- function(path) as.matrix(utils::read.csv(path, header = FALSE))
# paths <- c(s1 = "warp_s1.csv", s2 = "warp_s2.csv")
# fam <- make_warp_family("warp", from, to, paths, loader)

Description

Specify which files correspond to which statistical assays (beta, se, var, t). This mapping is used by as_gds.image_catalog() to construct the GDS.

Usage

map_assays(catalog, ...)

Arguments

Value

Updated image_catalog with assay_map.

Examples

# Build a tiny study tree with empty placeholder files
root <- tempfile("study_")
for (s in c("01", "02")) {
  d <- file.path(root, paste0("sub-", s))
  dir.create(d, recursive = TRUE)
  invisible(file.create(file.path(d, c("cope1.nii.gz", "varcope1.nii.gz"))))
}
catalog <- image_catalog(root, "sub-*/*.nii.gz",
                         path_regex = "sub-(?<subject>[^/]+)")

# By filename pattern (regex matched against basenames)
catalog <- map_assays(catalog,
  beta = "^cope[0-9]+\\.nii",
  var = "^varcope[0-9]+\\.nii"
)

# By metadata column value
catalog <- assign_meta(catalog, "stat_type", "^([a-z]+)[0-9]+")
catalog <- map_assays(catalog,
  beta = list(stat_type = "cope"),
  var = list(stat_type = "varcope")
)
summary(catalog)

unlink(root, recursive = TRUE)

Description

Create a linear map between spaces

Usage

map_linear(
  from_space,
  to_space,
  operator,
  by_subject = NULL,
  traits = list(orthogonal = FALSE, mass_preserving = FALSE),
  uncertainty = UncertaintyRule("independent"),
  name = NULL
)

Arguments

Value

Object of class c("map_linear", "gds_map")

Description

Add a space transformation to a plan

Usage

map_to(
  x,
  target_space,
  map,
  uncertainty = UncertaintyRule("independent"),
  combine = NULL
)

Arguments

Value

Updated plan

Description

Create a subject-aware map family

Usage

MapFamily(
  name,
  from_space,
  to_space,
  type = c("linear", "orthogonal", "affine3d", "deform3d", "ot"),
  by_subject,
  traits = list(orthogonal = FALSE, mass_preserving = FALSE),
  uncertainty = UncertaintyRule("independent")
)

Arguments

Value

Object of class c("gds_map_family", "gds_map")

Description

Apply a mask policy lazily

Usage

mask(x, policy = MaskPolicy())

Arguments

Value

Updated plan

Description

Define a mask policy

Usage

MaskPolicy(
  scope = c("group", "subject"),
  rule = c("intersection", "union", "threshold", "custom"),
  threshold = 0.95,
  custom = NULL
)

Arguments

Value

A mask policy object

Description

Extract metadata from a GDS object

Usage

metadata(x)

Arguments

Value

Metadata list

Description

Convenience helper to construct a model matrix using subject-level covariates already attached to a plan via with_col_data() or stored in a realised GDS.

Usage

model_matrix(x, formula)

Arguments

Value

A numeric model matrix

Description

Low-level constructor for image_catalog objects. Users should typically use image_catalog() for file discovery instead.

Usage

new_image_catalog(
  files,
  metadata = NULL,
  root_dir = NULL,
  pattern = NULL,
  assay_map = list()
)

Arguments

Value

An object of class c("image_catalog", "list").

Description

Build an explicit NIfTI source list for use with gds(..., format = "nifti"). If beta is provided without se, materialising the GDS creates a unit variance placeholder with a warning. This supports raw beta/stat-map workflows; the synthetic variance should not be interpreted as subject-level uncertainty, and variance-weighted reducers will refuse such a GDS.

Usage

nifti_source(
  beta = NULL,
  se = NULL,
  subject = NULL,
  subjects = NULL,
  contrast = NULL,
  contrasts = NULL
)

Arguments

Details

When both beta and se are supplied, files are paired by subject key unless explicit subject/subjects labels are supplied. The fallback key is the file basename (extension removed) with a trailing statistic token stripped, matching ⁠([_.-](beta|cope|varcope|var|variance|effect|se|stderr|sterr|sigma|std(err)?))+$⁠ (case insensitive). For example ⁠sub-01_beta.nii.gz⁠ and ⁠sub-01_se.nii.gz⁠ both reduce to the key sub-01. Filenames where the statistic token is not last (e.g. ⁠sub-01_stat-beta_sm-2.nii.gz⁠) will fail to pair unless explicit subject labels are provided. For beta/stat-only maps, prefer gds_from_scalar_maps(), which takes an explicit subject vector and avoids filename heuristics entirely.

Value

A list suitable for ⁠gds(source = <returned>, format = "nifti")⁠

Examples

src <- nifti_source(beta = c("sub-01_beta.nii.gz", "sub-02_beta.nii.gz"),
                    se   = c("sub-01_se.nii.gz",   "sub-02_se.nii.gz"))
str(src)

Description

Orthogonal map family helper

Usage

OrthogonalFamily(
  name,
  from_space,
  to_space,
  matrices_by_subject,
  uncertainty = UncertaintyRule("independent")
)

Arguments

Value

A MapFamily object with orthogonal traits

Description

Optimal transport family helper

Usage

OTFamily(
  name,
  from_space,
  to_space,
  plans_by_subject,
  uncertainty = UncertaintyRule("independent")
)

Arguments

Value

A MapFamily object with mass-preserving traits

Description

The default action plane places model surprise on the horizontal axis and influence on the requested group estimand on the vertical axis. Secondary views show subject-by-diagnostic summaries or the residual geometry. When subject is supplied, the retained observed, expected, predictive-residual, and deletion maps are shown for that subject.

Usage

## S3 method for class 'gds_examination'
plot(
  x,
  subject = NULL,
  type = c("action", "heatmap", "embedding"),
  contrast = NULL,
  estimand = NULL,
  group_by = NULL,
  assays = NULL,
  slice = NULL,
  ...
)

Arguments

Value

A ggplot object.

Description

Add a post-hoc operation to a plan

Usage

posthoc(x, method, options = list())

Arguments

Value

Updated gds_plan

See Also

posthoc-methods for the built-in methods and the assays each adds.

Examples

df <- data.frame(
  sample = rep(c("ROI_1","ROI_2"), each = 2),
  subject = rep(c("s1","s2"), times = 2),
  contrast = "c1",
  beta = c(0.5,0.6,0.7,0.8),
  var = c(0.04,0.05,0.06,0.07)
)
tmp <- tempfile(fileext = ".csv"); utils::write.csv(df, tmp, row.names = FALSE)
plan <- gds(tmp) |> reduce(method = "fixed") |> posthoc("fdr:bh")
# g <- compute(plan)  # returns q-values

Description

Methods are selected by name in posthoc() and add their adjusted-p assays to the realised GDS. The FDR methods adjust the object's p-value assay(s): a genuine bare p (from meta/combine reducers or a tabular p column) yields a single q; a per-term ⁠p_coef:<term>⁠ family (from regression/LMM reducers such as ols:voxelwise) yields one ⁠q_coef:<term>⁠ per term. Pass options = list(source = "p_coef:<term>") to adjust one specific term.

Value

This is a documentation page (no return value).

Methods and outputs

• "fdr:bh", "fdr:by": add q (or per-term ⁠q_coef:<term>⁠), Benjamini-Hochberg / Benjamini-Yekutieli adjusted p-values, computed column-wise per subject x contrast.

• "fdr:spatial": adds q (or per-term ⁠q_coef:<term>⁠), group-wise spatial FDR. Requires a discrete spatial grouping (one parcel/cluster id per sample) via options$group or a recognised row_data column (feature_group, spatial_group, group, parcel, parcel_id).

• "nt:tfce_fwer" (needs the optional neurothresh package): adds p_fwer (TFCE FWER-corrected p-values), sig_mask (1/0 at alpha), and tfce (the TFCE-enhanced statistic map).

• "nt:cluster_fdr_perm" (needs neurothresh): adds q (cluster-FDR q broadcast to voxels) and sig_mask.

Required input assays are auto-derived (and persisted) when absent: e.g. fdr:bh on a z-only GDS adds a derived p alongside q.

See Also

posthoc(), list_posthoc(), list_assays()

Description

Executes the plan with a small sample block to quickly inspect shapes or values. If assays is provided, returns raw arrays from the adapter stage (pre-operations); otherwise returns a realised GDS of the small block after applying plan nodes.

Usage

preview(plan, n = 3, assays = NULL)

Arguments

Value

Either a list of arrays (when assays provided) or a small gds

Description

Print validation report

Usage

## S3 method for class 'catalog_validation_report'
print(x, ...)

Arguments

Value

Invisibly returns the report.

Description

Print method for image_catalog

Usage

## S3 method for class 'image_catalog'
print(x, ...)

Arguments

Value

Invisibly returns the catalog.

Description

Load an image catalog previously saved with write_catalog().

Usage

read_catalog(file)

Arguments

Value

An image_catalog object.

Examples

# Build a tiny study tree with empty placeholder files
root <- tempfile("study_")
for (s in c("01", "02")) {
  d <- file.path(root, paste0("sub-", s))
  dir.create(d, recursive = TRUE)
  invisible(file.create(file.path(d, c("cope1.nii.gz", "varcope1.nii.gz"))))
}
catalog <- image_catalog(root, "sub-*/*.nii.gz",
                         path_regex = "sub-(?<subject>[^/]+)")

manifest <- tempfile(fileext = ".json")
write_catalog(catalog, manifest)

catalog2 <- read_catalog(manifest)
catalog2

unlink(c(manifest, root), recursive = TRUE)

Description

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

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.

Value

Updated plan

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.

See Also

gds(), compute(), as_plan(), new_gds(), gds_source()

Description

fmrigds includes four specialized repeated-measures Gaussian mixed-model reducers that are optimized for the case where every sample shares the same observation layout and the same fixed/random design.

Details

• method = "lmm:ri" fits a random-intercept model.

• method = "lmm:ri_slope1" fits a random intercept plus one within-subject slope supplied through options$slope.

• method = "lmm:ri_knownvar" and "lmm:ri_slope1_knownvar" fit the corresponding variance-aware models using the input var assay as known diagonal sampling variance.

These reducers operate on the full contrast axis jointly. Repeated-measure metadata therefore needs to be attached as contrast-level metadata, either with with_contrast_data() or during tabular ingestion via gds(..., contrast_data_cols = ...).

Supported contract:

• one grouping factor only

• Gaussian outcomes only

• shared observation layout and shared fixed/random design across samples

• unweighted reducers support theta_mode = "pooled" for one shared random-effect-to-residual covariance shape across samples or theta_mode = "voxelwise" for sample-specific parameters

• known-variance reducers currently support voxelwise covariance estimation only

• no crossed random effects and no general lmer() random-effects grammar

Value

This is a documentation page (no return value); these reducers are invoked via reduce().

Input variance contract

The unweighted lmm:ri and lmm:ri_slope1 reducers require beta only. An input var or se assay is ignored by their likelihood. Their sigma2 and ⁠vc_*⁠ outputs are second-level variance components estimated from the supplied effects.

The ⁠*_knownvar⁠ reducers require aligned beta and strictly positive var assays. For each sample, they fit marginal covariance ⁠diag(var) + vc_resid * I + Z G Z'⁠. Thus, var is treated as known sampling variance, vc_resid (sigma2) is additional observation-level heterogeneity, and G contains the subject random-effect covariance. Only diagonal sampling covariance is currently accepted; correlated first-level estimates require a future full sampling-covariance input rather than pretending their marginal variances are independent.

Fixed-effect standard errors use the fitted covariance as a plug-in estimate, and ⁠p_coef:*⁠ uses per-coefficient containment degrees of freedom (reported in ⁠df_coef:*⁠): coefficients of between-subject columns use N - rank(X_between), all others the residual df N*K - p. Satterthwaite and Kenward–Roger corrections are not applied.

Output assays

Both reducers expand fixed effects per model term (⁠<term>⁠ = design-matrix column names of formula): ⁠coef:<term>⁠, ⁠se_coef:<term>⁠, ⁠t_coef:<term>⁠, ⁠p_coef:<term>⁠. In addition:

• lmm:ri provides sigma2, vc_intercept, vc_resid, df_res, logLik, converged (1/0), and lambda (random-intercept-to-residual variance ratio).

• lmm:ri_slope1 provides sigma2, vc_intercept, vc_slope, vc_cov_intercept_slope, vc_resid, df_res, logLik, converged, lambda_intercept, lambda_slope, lambda_cov_intercept_slope, and corr_intercept_slope.

• lmm:ri_knownvar provides sigma2, vc_intercept, vc_resid, and sampling_var_mean; lmm:ri_slope1_knownvar additionally provides vc_slope, vc_cov_intercept_slope, and corr_intercept_slope. The relative ⁠lambda_*⁠ assays are intentionally omitted because known sampling variance breaks the single residual-scale parameterization. Pass these names verbatim (including the colon and any parentheses) to write_nifti_assays() / write_out().

Usage

rm_df <- data.frame(
  sample = rep(c("ROI_1", "ROI_2"), each = 12),
  subject = rep(paste0("sub-", sprintf("%02d", 1:4)), each = 3, times = 2),
  contrast = rep(c("pre", "mid", "post"), times = 8),
  time = rep(c(-1, 0, 1), times = 8),
  beta = c(
    0.40, 0.80, 1.20, 0.55, 0.95, 1.35, 0.65, 1.05, 1.45, 0.85, 1.25, 1.65,
    0.70, 1.20, 1.70, 0.85, 1.35, 1.85, 0.95, 1.45, 1.95, 1.15, 1.65, 2.15
  )
)

g <- gds(rm_df, contrast_data_cols = "time") |>
  reduce(
    method = "lmm:ri_slope1",
    formula = ~ time,
    options = list(
      slope = "time",
      covariance = "diag",
      fit = "REML",
      theta_mode = "voxelwise"
    )
  ) |>
  compute()

names(assays(g))
assay(g, "coef:time")

rm_df_known <- transform(rm_df, var = 0.04)
g_known <- gds(rm_df_known, contrast_data_cols = "time") |>
  reduce(
    method = "lmm:ri_slope1_knownvar",
    formula = ~ time,
    options = list(slope = "time", covariance = "diag", fit = "REML")
  ) |>
  compute()

Degrees of freedom (between/within)

Fixed-effect tests use per-coefficient degrees of freedom, exposed as ⁠df_coef:<term>⁠ assays (the scalar df_res assay is unchanged and still reports N*K - p). A design column that is constant within every subject (a between-subject term, including the intercept) uses df = N - rank(X_between), where X_between holds all between-subject columns at one row per subject. All other (within-subject) columns use the residual N*K - p. ⁠p_coef:<term>⁠ is computed from ⁠df_coef:<term>⁠. This supersedes the single residual-df rule described above for between-subject terms; it is a containment-style approximation, not Satterthwaite or Kenward–Roger.

converged reflects the covariance-parameter optimizer: it is 0 when the optimizer reports failure or a variance parameter is pinned at its upper search bound (a diverging variance), and 1 otherwise (zero-variance boundary estimates count as converged).

Description

The reducer identified by method = "ols:voxelwise" performs unweighted ordinary least squares across subjects independently for each sample and contrast. It accepts a model formula via reduce(..., formula = ~ 1 + cov) (design is built from with_col_data() or gds(..., col_data=...)).

Details

Outputs are expanded into per-term assays to preserve the 3-axis invariant:

• ⁠coef:<term>⁠ and ⁠se_coef:<term>⁠ (one assay per model term)

• ⁠t_coef:<term>⁠ and ⁠p_coef:<term>⁠ convenience statistics

• sigma2 (residual variance) and df_res (residual degrees of freedom)

• n_obs (number of finite subjects contributing at each sample)

Optionally, a packed triangular covariance for the coefficient vector can be attached per contrast using options = list(return_cov = "tri"), which also promotes per-pair ⁠cov:<term_i>:<term_j>⁠ assays. Retrieve the packed form from a realised GDS via coef_cov_tri().

Missing data are handled by per-sample listwise deletion: subjects whose effect is non-finite at a given sample are dropped for that sample only and the model is refit on the remaining rows. Samples with fewer than p + 1 finite observations (override with options = list(min_subjects = ...)) cannot be estimated and are returned as NA; n_obs records the effective sample size and a summary warning is emitted when any sample is reduced.

Value

This is a documentation page (no return value); the reducer is invoked via reduce(), one_sample(), or group_ols().

Output assays

For an intercept-only fit (formula = ~ 1): coef:(Intercept), se_coef:(Intercept), t_coef:(Intercept), p_coef:(Intercept), plus sigma2, df_res, and n_obs. Each additional model term adds a matching ⁠coef:<term>⁠/⁠se_coef:<term>⁠/⁠t_coef:<term>⁠/ ⁠p_coef:<term>⁠ quartet. Pass these names verbatim (including the colon and any parentheses) to write_nifti_assays() / write_out().

Usage

# Attach subject-level covariates; build design via formula
plan <- gds("group.csv", col_data = subj_cov) |
  reduce(method = "ols:voxelwise", formula = ~ 1 + age + sex,
         options = list(return_cov = "tri"))
g <- compute(plan)

# Per-term assays
assay(g, "coef:(Intercept)"); assay(g, "coef:age"); assay(g, "coef:sex")

# Packed covariance for first contrast
cov_info <- coef_cov_tri(g, contrast = contrasts(g)[1])
cov_info$terms   # term order
cov_info$cov_tri # L x samples packed upper triangle

# Stack all coefficients into [samples x terms x contrasts]
coef_arr <- coef_array(g)

Description

Register a storage adapter

Usage

register_adapter(
  name,
  detect,
  open,
  probe,
  read,
  close,
  capabilities = NULL,
  scan = NULL,
  ...
)

Arguments

Value

Invisibly, the adapter entry

Description

Register an assay type

Usage

register_assay(
  name,
  role,
  units = NULL,
  variance_of = NULL,
  derive_from = NULL
)

Arguments

Value

Invisibly, the registered assay definition

Description

Register a map family on a plan or realised GDS

Usage

register_map(x, family, overwrite = FALSE)

Arguments

Value

Updated object (gds_plan or gds)

Description

Makes nftab objects from the neurotabs package a first-class data source for gds(). Called automatically during .onLoad() when neurotabs is installed; can also be called manually.

Usage

register_nftab_adapter()

Value

Invisibly, the adapter entry.

Description

Register or replace a post-hoc handler identified by name.

Usage

register_posthoc(
  name,
  fun,
  requires,
  provides,
  overwrite = TRUE,
  case_deletion = NULL
)

Arguments