Custom BOLD Regressors

Custom BOLD Regressors#

Overview#

QuNex by default computes "nuisance" signal from white matter, whole-brain, and ventricular masks, which can then be regressed out of the BOLD timeseries (see BOLD preprocessing documentation for details). However, sometimes a user may wish to specify additional custom regressors to include in the BOLD nuisance signal regression (e.g. signal from draining veins). This can be done by first creating a mask for the region of interest, then extracting the signal from that mask, and finally including that signal in the nuisance regression.

Creating the custom mask#

The mask should be a binary volume with value of 1 in the ROI. This will be used to extract nuisance signal in the next step.

For example, this custom mask shows draining veins:

Note that the mask image must be in the same resolution as the BOLD image (usually 2mm^3 space) or else an error will be thrown.

Extracting the signal from the custom ROI#

Extraction of nuisance signal is supported by the extract_nuisance_signal QuNex command. bold[N].nuisance files are prepared by the extract_nuisance_signal command. The command does allow specifying additional ROI to extract the signal for (and masks that specify which ROI to exclude from WM, WB, V signal).

The specification is currently limited such that only one mask file can be provided per command. You can provide a .names file that defines the mask and the ROI that you want to additionally extract, however, the same mask would be used for all the sessions ran with the same command. There is additionally an option to limit the mask using the session-specific aparc+aseg mask.

To extract the signal with a custom mask for each session:

Prepare session-specific mask for the area of interest (e.g. draining veins) and the corresponding .names files. e.g. <session id>_DV.nii.gz and <session id>_DV.names.
Run extract_nuisance_signal command for each session separately, specifying session-specific custom mask.
Run preprocess_bold or preprocess_conc on all the sessions and add the custom regressor name (e.g. DV) to the list in bold_nuisance (see below).

An example way to run extract_nuisance_signal would be:

qunex extract_nuisance_signal \
    --batchfile="/data/mystudy/processing/batch.txt" \
    --sessionsfolder="sessions" \
    --sessionid="<session id>" \
    --overwrite=yes \
    --bolds=rest \
    --wbmask="/path/to/<session_id>_DV.names" \
    --nroi="/path/to/<session_id>_DV.names"

By adding --nroi, ROI defined in the <session_id>_DV.names file will be added as an additional column to the bold[N].nuisance file that you can then reference in the preprocess_bold command. By adding --wbmask those ROI will be excluded from the WB nuisance ROI, and the masked WB signal will be stored in the bold[N].nuisance file in the mWB column. So your final specification might be: --bold_nuisance="m,V,WM,mWB,DV,1d".

Computing the regression with custom nuisance regressors#

Lastly is the regression of nuisance parameters in the QuNex preprocess_conc or preprocess_bold command. For each bold there exists a corresponding bold[N].nuisance file in the sessions/<session id>/images/functional/movement folder. That file by default looks like this:

frame            V                WM               WB
              30769.8867187500 23982.9960937500 27385.6914062500
              30744.8984375000 24005.9609375000 27436.5781250000
              30703.8964843750 24030.8359375000 27395.1582031250
              30729.0898437500 24018.0625000000 27353.3300781250
              30828.4687500000 23980.4140625000 27358.9746093750
...

The file can have an arbitrary number of additional columns that list any other type of signal. So for instance you could have:

frame            V                WM               WB               DV
              30769.8867187500 23982.9960937500 27385.6914062500 26335.6515064500
              30744.8984375000 24005.9609375000 27436.5781250000 26446.5483257000
              30703.8964843750 24030.8359375000 27395.1582031250 26355.1283031250
              30729.0898437500 24018.0625000000 27353.3300781250 26323.3305787250
              30828.4687500000 23980.4140625000 27358.9746093750 26318.9443098750

where DV in this example would stand for “draining veins”. The DV column would be added during the extract_nuisance_signal step, if it is run as specified above. If the .nuisance file is prepared in this manner, then you can regress the DV signal in the preprocess_bold or preprocess_conc command simply by adding DV to the --bold_nuisance parameter in the call. e.g.:

qunex preprocess_bold
    --batchfile="/data/mystudy/processing/batch.txt" \
    --sessionsfolder=sessions \
    --overwrite=no \
    --bolds=rest \
    --bold_actions="s,h,r,c,l" \
    --bold_nuisance="m,V,WM,WB,DV,1d" \
    --mov_bad=udvarsme \
    --pignore="hipass=linear|regress=ignore|lopass=linear" \
    --nprocess=0

QuNex documentation