Create a GDS from subject-level scalar NIfTI maps

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

files

Character vector of NIfTI paths, a data.frame with a file column, or an image_catalog().

subject

Optional subject identifiers. Required for character files unless files is named; ignored when files already has a subject column.

contrast

Contrast label(s). A scalar value is recycled across files. Ignored when files already has a contrast column unless explicitly supplied.

col_data

Optional subject-level covariates. If a subject column is present and row names are absent, it is used as the row key.

mask

Optional mask passed to gds_from_nifti_maps().

...

Additional arguments forwarded to gds_from_nifti_maps().

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)
}
#> GDS
#>   dims: 32 x 4 x 1 [sample x subject x contrast]
#>   space: voxel dim=4x4x2, storage=packed
#>   subjects: 4 (sub-01, sub-02, sub-03, ...)
#>   contrasts: 1 (auc)
#>   assays: beta[location], var[variance]