Write Results from fMRI Linear Model — write_results.fmri

Exports statistical maps from an fmri_lm object with BIDS-compliant naming and JSON metadata sidecars. Supported image outputs are HDF5 LabeledVolumeSet files and NIfTI files; an fmrigds representation can also be requested.

Usage

# S3 method for class 'fmri_lm'
write_results(
  x,
  path = NULL,
  subject = NULL,
  task = NULL,
  space = NULL,
  desc = "GLM",
  format = c("h5", "nifti", "gds"),
  strategy = c("by_stat", "by_contrast"),
  save_betas = TRUE,
  contrasts = NULL,
  contrast_match = c("auto", "exact", "regex"),
  contrast_stats = c("beta", "tstat", "pval", "se"),
  overwrite = FALSE,
  validate_inputs = TRUE,
  ...
)

Arguments

x: An fmri_lm object containing fitted model results
path: Output directory path. If NULL, uses current working directory
subject: Subject identifier (e.g., "01", "1001"). Required.
task: Task identifier (e.g., "nback", "rest"). Required for BIDS compliance.
space: Spatial reference (e.g., "MNI152NLin2009cAsym"). Optional but recommended.
desc: BIDS desc- label of the analysis (default: "GLM"), sanitised to letters and digits. Beta files are labelled desc-<desc>; statistic maps desc-<desc><stat> (e.g. desc-run1tstat), except that the default "GLM" is omitted (desc-tstat), the naming collect_results() reads by default.
format: Output format(s). One or more of "h5" (BIDS-style HDF5 outputs), "nifti" (BIDS-style NIfTI outputs, written as .nii.gz), and "gds" (fmrigds-compatible assays plus an .rds plan). Pass a character vector to write multiple formats at once (e.g. c("h5", "nifti")). Defaults to "h5" only; "h5" requires the suggested package fmristore, "nifti" does not. NIfTI maps are stored as 32-bit floats (datatype FLOAT32), so their values are the fitted values rounded to single precision.
strategy: Storage strategy: "by_stat" (group contrasts by statistic) or "by_contrast" (separate files)
save_betas: Logical. Save raw regressor betas (default: TRUE)
contrasts: Character vector of contrast names to save. NULL saves all contrasts
contrast_match: How to match contrasts: "auto" first matches exact contrast names and treats unmatched selectors as regular expressions; "exact" uses literal names only; "regex" treats all selectors as regular expressions.
contrast_stats: Character vector of contrast statistics to save (default: c("beta", "tstat", "pval", "se"))
overwrite: Logical. Overwrite existing files (default: FALSE)
validate_inputs: Logical. Validate fmrilm object structure (default: TRUE)
...: Additional arguments passed to internal functions

Value

Invisible list of file paths created

Examples

if (FALSE) { # \dontrun{
# Save all results using default settings
write_results(fitted_model, subject = "01", task = "nback")

# Save only specific contrasts and statistics
write_results(fitted_model,
              subject = "01", task = "nback", space = "MNI152NLin2009cAsym",
              contrasts = c("FacesVsPlaces", "GoVsNoGo"),
              contrast_stats = c("beta", "tstat"))
} # }