extract_nuisance_signal

qx_utilities.processing.workflow.extract_nuisance_signal(sinfo, options, overwrite=False, thread=0)

extract_nuisance_signal [... processing options]

Extracts nuisance signal from volume BOLD files.

Parameters

--batchfile (str, default ''):

The batch.txt file with all the session information.

--sessionsfolder (str, default '.'):

The path to the study/sessions folder, where the imaging data is supposed to go.

--parsessions (int, default 1):

How many sessions to run in parallel.

--parelements (int, default 1):

How many elements (e.g. bolds) to run in parallel.

--overwrite (str, default 'no'):

Whether to overwrite existing data (yes) or not (no).

--bolds (str, default 'rest'):

Which bold images (as they are specified in the batch.txt file) to copy over. It can be a single type (e.g. 'task'), a pipe separated list (e.g. 'WM|Control|rest') or 'all' to copy all.

--boldname (str, default 'bold'):

The default name of the bold files in the images folder.

--nifti_tail (str, default ''):

The tail of NIfTI volume images to use.

--bold_variant (str, default ''):

Optional variant of bold preprocessing. If specified, the BOLD images in images/functional<bold_variant> will be processed.

--img_suffix (str, default ''):

Specifies a suffix for 'images' folder to enable support for multiple parallel workflows. Empty if not used.

--logfolder (str, default ''):

The path to the folder where runlogs and comlogs are to be stored, if other than default.

--wbmask (str, default ''):

A path to an optional file that specifies which regions are to be excluded from the whole-brain mask. It can be used in the case of ROI analyses for which one does not want to include the ROI specific signals in the global signal regression.

--nroi (str, default ''):

The path to additional nuisance regressors file. It can be either a binary mask or a '.names' file that specifies the ROI to be used. Based on other options, the ROI can be further masked by session specific files or not masked at all (see Use section below).

--sessionroi (str, default ''):

A string specifying which session specific mask to use for further masking the additional roi. The two options are 'wb' or 'aseg' for whole brain mask or FreeSurfer aseg+aparc mask, respectively.

--shrinknsroi (str, default 'true'):

A string specifying whether to shrink ('true') the whole brain and white matter masks or not ('false').

Output files

The command generates the following files:

• bold[N]<nifti_tail>.nuisance

  A text file that lists for each volume frame the information on mean intensity across the ventricle, white matter and whole brain voxels, and any additional nuisance ROI specified using parameters. The file is stored in the images<img_suffix>/functional<bold_variant>/movement folder.

• bold[N]<nifti_tail>_nuisance.png

  A PNG image of axial slices of the first BOLD frame over which the identified nuisance regions are overlayed. Ventricles in green, white matter in red and the rest of the brain in blue. The ventricle and white matter regions are defined based on FreeSurfer segmentation. Each region is "trimmed" before use, so that there is at least one voxel buffer between each nuisance region mask. The image is stored in images<img_suffix>/ROI/nuisance<bold_variant>`.

• bold[N]<nifti_tail>_nuisance.<image format>

  An image file of the relevant image format that holds the same information as the above PNG. It is a file of five volumes, the first volume holds the first BOLD frame, the second the whole brain mask, the third the ventricles mask and the fourth the white matter mask. The fifth volume stores all three masks coded as 1 (whole brain), 2 (ventricles), or 3 (white matter). The image is stored in images<img_suffix>/ROI/nuisance<bold_variant> folder.

Notes

extract_nuisance_signal is used to extract nuisance signal from volume BOLD files to be used in the latter steps of preprocessing, specifically for regression of nuisance signals. By default, it extracts nuisance signals from ventricles, white matter and whole brain. Whole brain is defined as those parts of the brain that are not ventricles or white matter, which results in whole brain to mostly overlap with gray matter.

Using parameters listed below, it is also possible to specify additional ROIs for which nuisance signal is to be extracted and/or ROI that are to be excluded from the whole brain mask.

To exclude specific ROI from the whole brain mask, use the '--wbmask' option. This should be a path to a file that specifies, which ROI are to be excluded from the whole-brain mask. The reason for exclusion might be when one does not want the signals from specific ROI to be included in the global signal regression, thereby resolving some issues taken as arguments against using global signal regression. The file can be either a binary mask, or a '.names' file. In the latter case, it is possible to additional mask the ROI to be excluded based on session specific aseg+aparc image (see description of .names file format).

Another option is to include additional independent nuisance regions that might or might not overlap with the existing masks. Two parameters are used to specify this. The first is the '--nroi' parameter. This, again, is a path to either a binary image or a '.names' file. In the latter case, it is again possible to mask the additional ROI either by the binary whole brain mask or the individuals aseg+aparc file. To achieve this, set the additional '--sessionroi' parameter to 'wb' or 'aseg', respectively. If some additional ROI are to be excluded, even though they fall outside the brain, then these are to be listed as comma separated list of ROI names (that match the ROI names in the .names file), separated from the path by a pipe ('|') symbol. For instance if one also would like to include eyes and scull as two additional nuiscance regions, one has to create a volume mask + a .names file pair, and pass it as the '--nroi' parameter, e.g.:

--nroi="<path to ROI>/nroi.names|eyes,scull"

Extra notes and dependencies:

When 'cifti' is the specified image target, the related nifti volume files will be processed as only they provide all the information for computing the relevant parameters

The command runs the general_extract_nuisance.m Matlab function for actual nuisance signal extraction. It expects that bold images, whole brain masks, and aseg+aparc imags to be present in the expected locations.

Examples

qunex extract_nuisance_signal \
    --batchfile=fcMRI/sessions_hcp.txt \
    --sessionsfolder=sessions \
    --overwrite=no \
    --bolds=all \
    --parsessions=10