Construct a NIfTI source specification — nifti

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

beta: Character vector of NIfTI paths or a directory containing beta/effect images (optional, can be NULL if only se is provided)
se: Character vector of NIfTI paths or a directory containing standard error images (optional, can be NULL if only beta is provided)
subject, subjects: Optional subject labels. When both beta and se are supplied, these labels declare that the vectors are already aligned in matching subject order and bypass filename-key pairing.
contrast, contrasts: Optional contrast labels. Length must match the number of contrasts in each NIfTI image (one for ordinary 3D maps).

Value

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

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.

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)
#> List of 2
#>  $ beta: chr [1:2] "sub-01_beta.nii.gz" "sub-02_beta.nii.gz"
#>  $ se  : chr [1:2] "sub-01_se.nii.gz" "sub-02_se.nii.gz"