BOLD task-evoked and resting-state functional connectivity preprocessing#

Prerequisites

Before running task-evoked and especially resting-state functional connectivity analyses, BOLD data needs to be additionally preprocessed through a number of steps. First, all the relevant data needs to be prepared: BOLD brain masks need to be created, BOLD image statistics need to be computed and processed, and nuisance signals need to be extracted. These data are then used to process the images, which might include spatial smoothing, temporal high and/or low pass filtering, and regression of undesired nuisance and task signal. All of the listed steps are performed using qunex processing commands. These commands are:

create_bold_brain_masks

For each BOLD separately, the command creates a mask of brain voxels for which signal is present. This ensures that in the following steps neither the signal outside of the brain, nor the areas within the brain from which signal was not captured due to small field of view or subject movement between the BOLD image acquisitions, are used. For instance, due to small field of view, inferior parts of cerebellum might not have been imaged, and the signal is missing.
compute_bold_stats

To allow assessment of intensity changes throughout BOLD image acquisition and identification of frames with artifactual signal, a number of statistics relating to each BOLD volume, as well as the difference between successive frames, need to be computed. This command computes these statistics.
create_stats_report

To review and use the statistics computed in the previous step, reports need to be created and statistics evaluated. This command prepares reports across BOLD images for each individual, and compiles them into a joint group report. The command also evaluates movement and intensity changes statistics according to provided criteria and identifies frames that might be corrupted with movement artifacts (i.e. "bad frames") to allow their exclusion or appropriate processing in the later steps.
extract_nuisance_signal

To allow removal of artifactual signal from BOLD, a number of nuisance signals can be estimated. These usually comprise of mean signal from brain ventricles, white matter, and gray matter. This command allows extraction of these (and potentially other) signals from the brain to be used in the following step(s).
preprocess_bold or preprocess_conc

These two commands perform the actual processing of the data, that can include spatial smoothing, temporal high and/or low pass filtering, and nuisance signal regression in any desired sequence and combination. The results are preprocessed residual after removal of undesired signal (this is then used as the input for functional connectivity analyses) and GLM beta estimates, which can be used in task activation analyses or for any other purposes. Both commands perform the same steps. In the case of resting state data, where each BOLD image is preprocessed independently, preprocess_bold is used. In the case when multiple BOLD images are to be considered as a joint signal (as is the case in task designs that span multiple BOLD images) preprocess_conc is used. Note that in the case of preprocessing of task data, when task signal is to be removed, .fidl files need to be generated and provided. See the next section on Activation analysis for additional information.

BOLD preprocessing: Prerequisites and general settings#

Prerequisites

All the commands listed above are run using QuNex processing engine. To successfully run the steps, the following prerequisites need to be met:

All the BOLD files need to be registered to a volume space, movement correction parameter files and FreeSurfer segmentation files (aseg or aseg+aparc) in the resolution of BOLD images need to be prepared. These steps are usually accomplished by running HCP pipeline and mapping the results to the QuNex folder structure. Currently this is the recommended and the only actively supported pipeline for initial processing of images.
A batch file needs to be prepared with all the subjects' information and batch level parameters. For information on how to prepare the batch file, review information in Preparing data for HCP pipeline section of Running HCP pipeline page.
If task is to be modelled, relevant conc and fidl files need to be prepared.

The following parameters are relevant when running BOLD processing steps:

--batchfile       ... The batch.txt file with all the session information [batch.txt].
--sessionsfolder  ... The path to the study/sessions folder, where the imaging data is supposed to go [.].
--parsessions     ... How many sessions to run in parallel [1].
--parelements     ... How many elements (e.g. bold images) to process concurrently [1].
                      Used in all functions with the exception of create_stats_report and
                      preprocess_conc functions.
--overwrite       ... Whether to overwrite existing data (yes) or not (no) [no].
--bolds           ... Which bold images (as they are specified in the batch.txt file) are to be 
                      processed. It can be a single type (e.g. 'task'), a pipe separated list (e.g.
                      'WM|Control|rest') or 'all' to process all [rest].
--boldname        ... The default name of the bold files in the images folder [bold].
--sessions        ... An optional pipe separated list of id codes of sessions that are to be processed.
                      All sessions will be processed if not specified.
--filter          ... An optional filter specified as a "<key>:<value>|<key>:<value>" string to limit
                      processing only to those sessions that match all the specified key:value pairs.
--bold_prefix     ... An optional prefix to place in front of processing name extensions in the resulting 
                      files, e.g. bold3<bold_prefix>_s_hpss.nii.gz [].
--bold_variant    ... Optional variant of functional images to process. If specified, the data from 
                      `images/functional<bold_variant>` will be processed [].
--img_suffix      ... Specifies a suffix for 'images' folder to enable support for multiple parallel 
                      workflows. If specified, the data from `images<img_suffix>/functional` will be 
                      processed. Empty if not used [].
--nifti_tail      ... The tail of NIfTI volume images to use. []
--cifti_tail      ... The tail of CIFTI images to use. []

The commands can be run either locally or submitted to a computer cluster using PBS and SLURM scheduler. For detailed information on how to use a scheduler, how the processing is logged and how to run a test, please consult General information on running HCP preprocessing steps section of Running HCP pipeline page.

BOLD preprocessing: Running specific commands#

Creating BOLD brain masks#

In this step create_bold_brain_masks command is used to create brain masks for each of the processed BOLD files. It makes use of the following command specific parameters:

--betboldmask    ... Options to be passed to bet when creating bold brain masks. ["-R -m"]

Creating BOLD brain masks - examples#

# run from the study folder
qunex create_bold_brain_masks \
    --batchfile="processing/batch.txt" \
    --sessionsfolder="sessions" \
    --parsessions="10" \
    --parelements="4" \
    --bolds="all" \
    --overwrite="no"

Computing BOLD statistics#

In this step compute_bold_stats command is used to compute per frame statistics and assess which frames should be scrubbed due to excessive movement and signal changes. It makes use of the following command specific parameters:

--mov_radius  ... Estimated head radius (in mm) for computing frame displacement statistics [50].
--mov_fd      ... Frame displacement threshold (in mm) to use for identifying bad frames [0.5]
--mov_dvars   ... The (mean normalized) dvars threshold to use for identifying bad frames [3.0].
--mov_dvarsme ... The (median normalized) dvarsm threshold to use for identifying bad frames [1.5].
--mov_after   ... How many frames after each frame identified as bad to also exclude from further 
                  processing and analysis [0].
--mov_before  ... How many frames before each frame identified as bad to also exclude from further 
                  processing and analysis [0].
--mov_bad     ... Which criteria to use for identification of bad frames [udvarsme].

Computing BOLD statistics - examples#

# run from the study folder
qunex compute_bold_stats \
    --batchfile="processing/batch.txt" \
    --sessionsfolder="sessions" \
    --parsessions="10" \
    --parelements="4" \
    --bolds="all" \
    --overwrite="no"

Please consult Movement scrubbing page for more specific information on movement scrubbing.

Creating statistics report#

In this step create_stats_report command is used to process movement correction parameters and computed BOLD statistics to create per session plots and fidl snippets, and group reports. It makes use of the following command specific parameters:

Scrubbing specific options:

--mov_radius  ... Estimated head radius (in mm) for computing frame displacement statistics [50].
--mov_fd      ... Frame displacement threshold (in mm) to use for identifying bad frames [0.5]
--mov_dvars   ... The (mean normalized) dvars threshold to use for identifying bad frames [3.0].
--mov_dvarsme ... The (median normalized) dvarsm threshold to use for identifying bad frames [1.5].
--mov_after   ... How many frames after each frame identified as bad to also exclude from further 
                  processing and analysis [0].
--mov_before  ... How many frames before each frame identified as bad to also exclude from further 
                  processing and analysis [0].
--mov_bad     ... Which criteria to use for identification of bad frames [udvarsme].

Reporting specific options:

--TR          ... TR of the BOLD files [2.5].
--mov_pref    ... The prefix to be used for the group reports [].
--mov_plot    ... The base name of the plot files. If set to empty no plots are generated [mov_report].
--mov_mreport ... The name of the group movement report file. If set to an empty string, no file is 
                  generated [movement_report.txt].
--mov_sreport ... The name of the group scrubbing report file. If set to an empty string, no file is 
                  generated [movement_scrubbing_report.txt].
--mov_preport ... The name of group report file with stats computed with frames identified as bad 
                  excluded from analysis. If set to an empty string, no file is generated
                  [movement_report_post.txt].
--mov_post    ... The criterium for identification of bad frames that is used when generating a post 
                  scrubbing statistics group report (fd/dvars/dvars/dvarsme/idvars/idvarsme/
                  udvars/udvarsme/none) [udvarsme].
--mov_fidl    ... Whether to create a fidl file snippets with listed bad frames, and what criterium 
                  to use for the definition of bad frames (fd/dvars/dvars/dvarsme/idvars/idvarsme/
                  udvars/udvarsme). Set to none to not generate them [udvarsme].
--mov_pdf     ... The name of the folder in sessions/QC/movement in which to copy the individuals' 
                  movement plots [movement_plots].

Creating statistics report - examples#

# run from the study folder
qunex create_stats_report \
    --batchfile="processing/batch.txt" \
    --sessionsfolder="sessions" \
    --parsessions="10" \
    --bolds="all" \
    --overwrite="no"

Please consult Movement scrubbing page for more specific information on movement scrubbing.

Extracting nuisance signal#

In this step extract_nuisance_signal command 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. It makes use of the following command specific parameters:

--wbmask        ... 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          ... 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.
--sessionroi    ... 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   ... A string specifying whether to shrink ('true' or 'yes') the whole brain and 
                    white matter masks or not.

Extracting nuisance signal - examples#

# run from the study folder
qunex extract_nuisance_signal \
    --batchfile="processing/batch.txt" \
    --sessionsfolder="sessions" \
    --parsessions="10" \
    --parelements="4" \
    --bolds="all" \
    --overwrite="no"

Process BOLD files independently#

In this step preprocess_bold command is used to spatially and temporally smooth the BOLD timeseries, and remove nuisance signal and task structure. This command is best used for resting state data or single runs of task. When task spans multiple BOLD images, please use preprocess_conc command described below. The command makes use of the following command specific parameters:

General parameters
------------------
--event_file      ... The name of the fidl file to be used with each bold.
--bold_actions    ... A string specifying which actions, and in what sequence to perform [shrcl]
                      m ... Motion scrubbing.
                      s ... Spatial smoothing.
                      h ... High-pass filtering.
                      r ... Regression (nuisance and/or task).
                      c ... Saving of resulting beta coefficients (always to follow 'r').
                      l ... Low-pass filtering.

Movement scrubbing parameters
-----------------------------
--mov_radius  ... Estimated head radius (in mm) for computing frame displacement statistics [50].
--mov_fd      ... Frame displacement threshold (in mm) to use for identifying bad frames [0.5]
--mov_dvars   ... The (mean normalized) dvars threshold to use for identifying bad frames [3.0].
--mov_dvarsme ... The (median normalized) dvarsm threshold to use for identifying bad frames [1.5].
--mov_after   ... How many frames after each frame identified as bad to also exclude from further 
                  processing and analysis [0].
--mov_before  ... How many frames before each frame identified as bad to also exclude from further 
                  processing and analysis [0].
--mov_bad     ... Which criteria to use for identification of bad frames [udvarsme].

Movement scrubbing action
-------------------------
--pignore     ... A string describing how to deal with bad frames in separate phases of preprocessing
                  specified in a form:
                  "hipass:<filtering opt.>|regress:<regression opt.>|lopass:<filtering opt.>" with
                  the following possible options:

                  keep   ... Keep the bad frames.
                  ignore ... Exclude bad frames from regression (not valid for filtering).
                  mark   ... Exclude bad frames from regression and mark the bad frames
                             as NaN (not valid for filtering).
                  linear ... Replace bad frames with linear interpolated values based on
                             neighboring good frames.
                  spline ... Replace bad frames with spline interpolated values based on
                             neighboring good frames.

Volume smoothing
----------------
--voxel_smooth  ... Gaussian smoothing FWHM in voxels [2]
--smooth_mask   ... Whether to smooth only within a mask, and what mask to use 
                    (nonzero/brainsignal/brainmask/<filename>)[false].
--dilate_mask   ... Whether to dilate the image after masked smoothing and what mask to use 
                    (nonzero/brainsignal/brainmask/same/<filename>)[false].

Cifti smoothing
---------------
--surface_smooth  ... FWHM for gaussian surface smoothing in mm [6.0].
--volume_smooth   ... FWHM for gaussian volume smoothing in mm [6.0].
--omp_threads     ... Number of cores to be used by wb_command. 0 for no change of system settings [0].

Temporal filtering
------------------
--hipass_filter  ... The frequency for high-pass filtering in Hz [0.008].
--lopass_filter  ... The frequency for low-pass filtering in Hz [0.09].
--hipass_do      ... Which signal besides BOLD to also high-pass filter ['nuisance']
--lopas_do       ... Which signal besides BOLD to also low-pass filter ['nuisance,movement,task,events']

Regression
----------
--bold_nuisance  ... A comma separated list of regressors to include in the GLM. Possible values are:
                     * m     - motion parameters
                     * m1d   - motion parameters first derivatives
                     * mSq   - squared motion parameters
                     * m1dSq - squared motion parameters first derivatives
                     * V     - ventricles signal
                     * WM    - white matter signal
                     * WB    - whole brain signal
                     * n1d   - first derivatives of V, WM and WB nuisancesignals
                     * 1d    - first derivatives of motion parameters and nuisance signals
                     * e     - events listed in the provided fidl files, modeled as specified in the 
                               event_string parameter.
                     [m,V,WM,WB,1d]
--event_string   ... A string describing, how to model the events listed in the provided fidl files [].
--glm_matrix     ... Whether to save the GLM matrix as a text file ('text'), a png image file 
                     ('image'), both ('both') or not ('none') [none].
--glm_residuals  ... Whether to save the residuals after GLM regression ('save') or not ('none') [save].
--glm_name       ... An additional name to add to the residuals and GLM files to distinguish between 
                     different possible models used.

Process BOLD files independently - examples#

# run from the study folder
qunex preprocess_bold \
    --batchfile="processing/batch.txt" \
    --sessionsfolder="sessions" \
    --parsessions="10" \
    --parelements="4" \
    --bolds="all" \
    --bold_actions="shrc" \
    --bold_nuisance="m,V,WM,WB,1d" \
    --pignore="hipass=linear|regress=linear|lopass=linear" \
    --overwrite="no"

# run using absolute paths with scheduler
qunex preprocess_bold \
    --batchfile="<path_to_study_folder>/processing/batch.txt" \
    --sessionsfolder="<path_to_study_folder>/sessions" \
    --parsessions="4" \
    --parelements="4" \
    --bolds="rest" \
    --bold_actions="shrc" \
    --bold_nuisance="m,V,WM,WB,1d" \
    --pignore="hipass=linear|regress=linear|lopass=linear" \
    --overwrite="yes" \
    --scheduler="SLURM,time=24:00:00,cpus-per-task=2,mem-per-cpu=1300,partition=day"

Process concatenated BOLD files#

In this step preprocess_conc command is used to spatially and temporally smooth the BOLD timeseries, and remove nuisance signal and task structure across a concatenated set of BOLD files. This command is best used for task data that spans multiple runs. For resting state data consider using preprocess_bold command as it does not require generation of conc files. The command makes use of the following command specific parameters:

General parameters
------------------
--event_file      ... The name of the fidl file to be used with each bold.
--bold_actions    ... A string specifying which actions, and in what sequence to perform [shrcl]
                      m ... Motion scrubbing.
                      s ... Spatial smoothing.
                      h ... High-pass filtering.
                      r ... Regression (nuisance and/or task) with an optional number 0, 1, or 2
                            specifying the type of regression to use.
                      c ... Saving of resulting beta coefficients (always to follow 'r').
                      l ... Low-pass filtering.

Movement scrubbing parameters
-----------------------------
--mov_radius  ... Estimated head radius (in mm) for computing frame displacement statistics [50].
--mov_fd      ... Frame displacement threshold (in mm) to use for identifying bad frames [0.5]
--mov_dvars   ... The (mean normalized) dvars threshold to use for identifying bad frames [3.0].
--mov_dvarsme ... The (median normalized) dvarsm threshold to use for identifying bad frames [1.5].
--mov_after   ... How many frames after each frame identified as bad to also exclude from further 
                  processing and analysis [0].
--mov_before  ... How many frames before each frame identified as bad to also exclude from further 
                  processing and analysis [0].
--mov_bad     ... Which criteria to use for identification of bad frames [udvarsme].

Movement scrubbing action
-------------------------
--pignore     ... A string describing how to deal with bad frames in separate phases of preprocessing
                  specified in a form:
                  "hipass:<filtering opt.>|regress:<regression opt.>|lopass:<filtering opt.>" with
                  the following possible options:

                  keep   ... Keep the bad frames.
                  ignore ... Exclude bad frames from regression (not valid for filtering).
                  mark   ... Exclude bad frames from regression and mark the bad frames
                             as NaN (not valid for filtering).
                  linear ... Replace bad frames with linear interpolated values based on
                             neighboring good frames.
                  spline ... Replace bad frames with spline interpolated values based on
                             neighboring good frames.

Volume smoothing
----------------
--voxel_smooth  ... Gaussian smoothing FWHM in voxels [2]
--smooth_mask   ... Whether to smooth only within a mask, and what mask to use 
                    (nonzero/brainsignal/brainmask/<filename>)[false].
--dilate_mask   ... Whether to dilate the image after masked smoothing and what mask to use 
                    (nonzero/brainsignal/brainmask/same/<filename>)[false].

Cifti smoothing
---------------
--surface_smooth  ... FWHM for gaussian surface smoothing in mm [6.0].
--volume_smooth   ... FWHM for gaussian volume smoothing in mm [6.0].
--omp_threads     ... Number of cores to be used by wb_command. 0 for no change of system settings [0].

Temporal filtering
------------------
--hipass_filter  ... The frequency for high-pass filtering in Hz [0.008].
--lopass_filter  ... The frequency for low-pass filtering in Hz [0.09].
--hipass_do      ... Which signal besides BOLD to also high-pass filter ['nuisance']
--lopas_do       ... Which signal besides BOLD to also low-pass filter ['nuisance,movement,task,events']

Regression
----------
--bold_nuisance  ... A comma separated list of regressors to include in the GLM. Possible values are:
                     * m     - motion parameters
                     * m1d   - motion parameters first derivatives
                     * mSq   - squared motion parameters
                     * m1dSq - squared motion parameters first derivatives
                     * V     - ventricles signal
                     * WM    - white matter signal
                     * WB    - whole brain signal
                     * n1d   - first derivatives of V, WM and WB nuisancesignals
                     * 1d    - first derivatives of motion parameters and nuisance signals
                     * e     - events listed in the provided fidl files, modeled as specified in the 
                               event_string parameter.
                     [m,V,WM,WB,1d]
--event_string   ... A string describing, how to model the events listed in the provided fidl files [].
--glm_matrix     ... Whether to save the GLM matrix as a text file ('text'), a png image file 
                     ('image'), both ('both') or not ('none') [none].
--glm_residuals  ... Whether to save the residuals after GLM regression ('save') or not ('none') [save].
--glm_name       ... An additional name to add to the residuals and GLM files to distinguish between 
                     different possible models used.

Process concatenated BOLD files - examples#

# run from the study folder for fcMRI preprocessing
qunex preprocess_conc \
    --batchfile="processing/batch_wm.txt" \
    --sessionsfolder="sessions" \
    --parsessions="10" \
    --bolds=<Root_name_of_concatenation_files> \
    --event_file="<Root_name_of_events_files>" \
    --bold_actions="shrc" \
    --bold_nuisance="m,V,WM,WB,1d,e" \
    --event_string="<event1>:<#_frames>|<event2>:<#_frames>" \
    --pignore="hipass=linear|regress=ignore|lopass=linear" \
    --glm_residuals="save" \
    --overwrite="no"

Output naming conventions#

Consider a file called:

"bold2_Atlas_s_hpss_res-mVWMWB_lpss_YEO7_.dconn.nii"

The name expands to tags:

   "bold2_Atlas_"   # BOLD root name
   "s_"             # Spatial smoothing using a Gaussian kernel (per parameters in batch file)
   "hpss_"          # High-pass filtering performed (per parameters in batch file)
   "res-mVWMWB_"    # BOLD nuisance regression steps performed (per parameters in batch file)
                      # m - motion parameters
                      # V - ventricles signal
                      # WM - white matter signal
                      # WB - whole brain signal
   "lpss_"          # Low-pass filtering performed (per parameters in batch file)
   "YEO7_"          # Functional network parcellation used (per parcellation command used)
   ".dconn.nii"     # File extension

Comment on 'legacy' spatial smoothing tag name g7: Historically, spatial smoothing was denoted using a “Gaussian kernel 7” (thus g7 as the name of smoothing function). Now that QuNex also enables smoothing on the surface the tag is neither valid nor intuitive. This is now changed for prospective data to “s” to reflect smoothing with backward compatibility for g7.

Concluding remarks#

For more detailed instructions on how to use the listed commands, please refer to their embedded help (e.g. by running qunex preprocess_conc).
Additional information and explanations on how to set up a task GLM model with behavioral regressors is provided as part of the Running first-level and second-level task activation analyses page.
For more detailed information about movement scrubbing, please consult the Movement scrubbing page.

QuNex documentation

BOLD task-evoked and resting-state functional connectivity preprocessing

Contents

BOLD task-evoked and resting-state functional connectivity preprocessing#

BOLD preprocessing: Prerequisites and general settings#

BOLD preprocessing: Running specific commands#

Creating BOLD brain masks#

Creating BOLD brain masks - examples#

Computing BOLD statistics#

Computing BOLD statistics - examples#

Creating statistics report#

Creating statistics report - examples#

Extracting nuisance signal#

Extracting nuisance signal - examples#

Process BOLD files independently#

Process BOLD files independently - examples#

Process concatenated BOLD files#

Process concatenated BOLD files - examples#

Output naming conventions#

Concluding remarks#