Volumes#

How modewise turns a 4D NIfTI run into region signals, so pipelines can start from preprocessed volumes (for example fMRIPrep output) instead of parcellated files.

Parcellation#

Each region’s signal is the mean over its atlas label’s voxels, at every volume, as nilearn’s NiftiLabelsMasker computes it (Abraham et al., 2014):

  • Resampling: the atlas is resampled onto the data grid by nearest neighbour, through both images’ voxel-to-world affines. A data voxel that falls outside the atlas is background.

  • Affines: each image’s affine is its sform when the sform code is set, otherwise its qform, as the NIfTI-1 standard specifies.

  • Labels: 0 is background, and regions come out in ascending label order.

  • Standardising: standardize = "zscore_sample" subtracts each region’s mean and divides by its sample standard deviation. It is off by default.

Labels with no voxel on the data grid (an atlas that does not cover the field of view) give a NaN channel and a warning. Keeping the channel keeps names from a label table aligned. Recent nilearn versions drop such labels, which would shift every later name.

Several atlases (for example Schaefer cortex and Tian subcortex) are parcellated one after the other and concatenated in the order given. Name the channels with a [channels] section that lists the matching label tables in the same order (regions).

Volumes are not stored. A run is parcellated when it is loaded, as maskers do; a whole BOLD run would be gigabytes per recording.

Use#

In a dataset spec (datasets):

[[input]]
name = "bold"
pattern = "derivatives/fmriprep/sub-{subject}/func/sub-{subject}_task-{task}_space-MNI152NLin2009cAsym_res-2_desc-preproc_bold.nii.gz"
format = "nifti"
atlases = ["atlases/Schaefer400_17Networks.nii.gz", "atlases/Tian_S2.nii"]
standardize = "zscore_sample"
sidecar = "sub-{subject}/func/sub-{subject}_task-{task}_bold.json"   # optional; else the header's TR

In Python: modewise.read_nifti(path, [atlas, ...], standardize="zscore_sample").

References#

  • Abraham, A., Pedregosa, F., Eickenberg, M., et al. (2014). Machine learning for neuroimaging with scikit-learn. Frontiers in Neuroinformatics, 8, 14. https://doi.org/10.3389/fninf.2014.00014

  • Cox, R. W., et al. (2004). A (sort of) new image data format standard: NIfTI-1. NeuroImage, 22(Supplement 1), e1440.