Write image-like GDS assays as NIfTI files — write_nifti

Writes each selected assay/subject/contrast image in a voxel-space GDS to a separate NIfTI file and returns a manifest describing written and skipped outputs. This is intended for model outputs such as coef:*, t_coef:*, and p_coef:* assays.

Usage

write_nifti_assays(
  g,
  out_dir,
  prefix = NULL,
  assays = NULL,
  subjects = NULL,
  contrasts = NULL,
  sanitize = TRUE,
  overwrite = FALSE
)

Arguments

g: A realised gds with voxel space.
out_dir: Output directory.
prefix: Optional filename prefix.
assays: Character vector of assays to write. Defaults to all assays.
subjects: Optional subject labels to write. Defaults to all subjects.
contrasts: Optional contrast labels to write. Defaults to all contrasts.
sanitize: Logical; if TRUE (default), make filename components filesystem-friendly. Set FALSE only with trusted prefix/labels: raw values are used verbatim, so path separators in them could write outside out_dir.
overwrite: Logical; if FALSE, existing files are skipped.

Value

A data.frame manifest with assay, subject, contrast, path, written, and skipped_reason columns.

Details

Filenames are [<prefix>_]contrast-<contrast>[_sub-<subject>]_<assay>.nii.gz. The contrast- token is always included so that writing several contrasts to the same directory/prefix (e.g. one call per contrast) never silently overwrites; the sub- token is added when the GDS has more than one subject. Existing BIDS-style labels are not double-prefixed (a "sub-01" label stays sub-01, not sub-sub-01). A within-call collision (two distinct outputs resolving to the same path, e.g. via sanitisation) raises an error.

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"))

  g <- suppressWarnings(gds_from_scalar_maps(files, subject = subj,
                                             contrast = "auc",
                                             col_data = participants))
  fit <- group_ols(g, ~ group) |> compute()
  manifest <- write_nifti_assays(fit, file.path(dir, "group_maps"),
                                 prefix = "auc",
                                 assays = c("coef:grouppatient", "t_coef:grouppatient"))
  print(manifest[, c("assay", "written")])
  print(basename(manifest$path))

  unlink(dir, recursive = TRUE)
}
#>                 assay written
#> 1   coef:grouppatient    TRUE
#> 2 t_coef:grouppatient    TRUE
#> [1] "auc_contrast-auc_coef_grouppatient.nii.gz"  
#> [2] "auc_contrast-auc_t_coef_grouppatient.nii.gz"