Running BOLD functional connectivity analyses#

This section describes how to run various types of BOLD functional connectivity analyses at the single-session level using either resting-state or task-based BOLD time series. Importantly, before proceeding, please ensure that all the data has been put through the relevant preprocessing steps, which are described in detail in the section on BOLD task-evoked and resting-state functional connectivity preprocessing.

Functional connectivity analysis Matlab functions#

All types of functional connectivity analysis rely on QuNex Matlab functions that can perform the analyses both on individual sessions as well as a list of sessions to also provide group-level results. The Matlab functions can be used in a number of ways: (i) they can be called and scripted from within Matlab or Octave; (ii) they can be run through the qunex command, which starts up Matlab or Octave and invokes the functions; or (iii) they can be run through the fc_compute_wrapper bash command.

The relevant Matlab functions are:

fc_compute_gbc3 – compute single subject and group level GBC maps
fc_compute_gbcd – compute single subject and group level GBC maps for individual distance from ROI bands
fc_compute_roifc – compute single subject ROI functional connectivity matrices
fc_compute_roifc_group – compute ROI functional connectivity matrices for a list of subjects
fc_compute_seedmaps – compute functional connectivity seed-maps for a single subject
fc_compute_seedmaps_group – compute functional connectivity seed-maps for a list of subjects
fc_extract_roi_timeseries – extract fMRI timeseries for a single subject
fc_extract_roi_timeseries_group – extract fMRI timeseries for a list of subjects

For a detailed description of each of the Matlab functions, please consult the inline help by running qunex <command> or help <command> in Matlab or Octave.

Running the functional connectivity analyses using the bash wrapper command#

fc_compute_wrapper is a bash wrapper that offers an alternative interface for running the above-listed functions and provides some additional functionality. Note that to make full use of the options and analysis flexibility provided by the Matlab functions, it is advisable to run them directly.

The rest of the document describes the use of the fc_compute_wrapper functionality.

Computing seed-based functional connectivity maps#

Fundamentally, a 'seed-based' or 'ROI-based' functional connectivity analysis requires a specification of a 'seed' location from which the desired measure of statistical dependence with all other desired locations (e.g. whole brain or some other restricted area) is computed. To achieve this one would run fc_compute_wrapper with the specification below. Note that the seed-based connectivity relies on a Region of interest (ROI) specification "names" file (*.names).

Example for an individual run#

qunex fc_compute_wrapper \
    --sessionsfolder='<folder_with_sessions>' \
    --calculation="seed" \
    --runtype="individual" \
    --sessions="<session_id1>,<session_id2>,...,<session_idN>" \
    --inputfiles="<name_of_input_BOLD_timeseries>.dtseries.nii" \
    --inputpath="<path_for_input_file>" \
    --overwrite="<yes/no>" \
    --extractdata="<yes/no>" \
    --roinfo="<path_to_file>/<name_of_file>.names" \
    --outname="<output_name_of_BOLD_fc_file>" \
    --ignore="<frames_to_ignore>" \
    --options="<calculations_to_save>" \
    --method="<method_to_get_timeseries> " \
    --targetf="<path_for_output_file>" \
    --mask="<which_frames_to_use>" \
    --covariance="<compute_covariance>" \
    --scheduler="<scheduler_name>,<parameter>=<value>,...,<parameter>=<value>"

The breakdown of the parameters is as follows:

sessionsfolder

Path to sessions folder within the study folder.
calculation

Run <seed> or <gbc> calculation for functional connectivity.
runtype

This flag specifies the 'individual' seed run on a series of single session, rather than a group run. You can run this calculation on a <list> (requires a list input), on <individual> sessions (requires manual specification) or a <group> of individual sessions (equivalent to a list, but with manual specification).
sessions

List of sessions to run.
inputfiles

Specify the comma separated file names you want to use (e.g.'bold1_Atlas_MSMAll.dtseries.nii,bold2_Atlas_MSMAll.dtseries.nii').
inputpath

Specify path of the file you want to use relative to the master study folder and session directory (e.g. /images/functional/). Default: [<study_folder>/sessions/<session_id>/images/functional].
overwrite

Delete prior run for a given session. Default is [no].
extractdata

Specify if you want to save out the matrix as a CSV file (only available if the file is a ptseries) <yes/no>. Default is [no].
roinfo

Region of interest (ROI) specification "names" file (*.names).
outname

Specify the suffix name of the output file name.
ignore

The column in *_scrub.txt file that matches bold file to be used for ignore mask. All if empty. Default is [].
options

A string defining which session files to save. Default assumes all ['']. r --> save map of correlations. f --> save map of Fisher z values, cv -> save map of covariances, z --> save map of Z scores.
method

Method for extracting timeseries - 'mean' or 'pca' Default is ['mean'].
targetf

Specify the absolute path for group result output folder. If using --runtype='individual' the output will default to --inputpath location for each individual session".
mask

An array mask defining which frames to use (1) and which not (0). All if empty. If single value is specified then this number of frames is skipped.
covariance

Whether to compute covariances instead of correlations (true / false). Default is [false].
scheduler

Scheduler and relevant options. E.g. Specific scheduler string example for SLURM is: --scheduler="SLURM,jobname=fc,time=24:00:00,cpus-per-task=2,mem-per-cpu=1500,partition=day".

Example for a group run#

The 'seed' command can also be used on an entire group of sessions simultaneously as opposed to each session individually. This will generate group-level summary statistics as well as a file with all the single sessions saved as individual volumes, as opposed to each session's results being saved inside <study_folder>/sessions/<session_id>/images/functional single-session structure. Note that the --targetf flag is mandatory here because the group calculation needs an explicit specification where to save the group output files.

qunex compute_bold_fc \
    --sessionsfolder='<folder_with_sessions>' \
    --calculation="seed" \
    --runtype="group" \
    --sessions="<session_id1>,<session_id2>,...,<session_id#>" \
    --inputfiles="<name_of_input_BOLD_timeseries>.dtseries.nii" \
    --inputpath="<path_for_input_files>" \
    --targetf="<path_to_study_folder>/<some_analysis_folder>" \
    --overwrite="no" \
    --extractdata="no" \
    --roinfo="<path_to_file>/<name_of_file>.names" \
    --outname="<output_name_of_BOLD_fc_file>" \
    --ignore="" \
    --options="" \
    --method="" \
    --mask="" \
    --covariance="no" \
    --scheduler="<scheduler_name>,<parameter>=<value>,...,<parameter>"

Note that --runtype is now set to "group" and that --targetf is now mandatory.

Resting-state global brain Connectivity (GBC)#

GBC is an extrapolation of 'seed-based' connectivity it computes 'seed-based' connectivity from one location (e.g. a specific 'greyordinate', voxel, or parcel) to all other locations and then computes a summary of this vector (e.g. mean). Because of this added complexity to compute GBC the command requires further specification:

--target="<which_roi_to_use>" ................ Array of ROI codes that define target ROI 
                                               [default: FreeSurfer cortex codes]
--rsmooth="<smoothing_radius>" ............... Radius for smoothing (no smoothing if empty). Default is []
--rdilate="<dilation_radius>" ................ Radius for dilating mask (no dilation if empty). Default is []
--command="<type_of_gbc_to_run>" ............. Specify the type of gbc to run. 
                                               This is a string describing GBC to compute. 
                                               E.g. 'mFz:0.1|mFz:0.2|aFz:0.1|aFz:0.2|pFz:0.1|pFz:0.2' 

                    > 'mFz:t'  ... computes mean Fz value across all voxels (over threshold t) 
                    > 'aFz:t'  ... computes mean absolute Fz value across all voxels (over threshold t) 
                    > 'pFz:t'  ... computes mean positive Fz value across all voxels (over threshold t) 
                    > 'nFz:t'  ... computes mean positive Fz value across all voxels (below threshold t) 
                    > 'aD:t'   ... computes proportion of voxels with absolute r over t 
                    > 'pD:t'   ... computes proportion of voxels with positive r over t 
                    > 'nD:t'   ... computes proportion of voxels with negative r below t 
                    > 'mFzp:n' ... computes mean Fz value across n proportional ranges 
                    > 'aFzp:n' ... computes mean absolute Fz value across n proportional ranges 
                    > 'mFzs:n' ... computes mean Fz value across n strength ranges 
                    > 'pFzs:n' ... computes mean Fz value across n strength ranges for positive correlations 
                    > 'nFzs:n' ... computes mean Fz value across n strength ranges for negative correlations 
                    > 'mDs:n'  ... computes proportion of voxels within n strength ranges of r 
                    > 'aDs:n'  ... computes proportion of voxels within n strength ranges of absolute r 
                    > 'pDs:n'  ... computes proportion of voxels within n strength ranges of positive r 
                    > 'nDs:n'  ... computes proportion of voxels within n strength ranges of negative r 

Example of an individual GBC run#

qunex fc_compute_wrapper \
    --sessionsfolder="<folder_with_sessions>" \
    --calculation="gbc" \
    --runtype="individual" \
    --sessions="<session_id1>,<session_id2>,...,<session_id#>" \
    --inputfiles="<name_of_input_BOLD_timeseries>.dtseries.nii" \
    --inputpath="<path_for_input_file>" \
    --overwrite="<yes/no>" \
    --extractdata="<yes/no>" \
    --outname="<output_name_of_BOLD_fc_file>" \
    --ignore="<frames_to_ignore>" \
    --command="<type_of_gbc_to_run>" \
    --targetf="<path_for_output_file>" \
    --mask="<which_frames_to_use>" \
    --target="<which_roi_to_use>" \
    --rsmooth="<smoothing_radius>" \
    --rdilate="<dilation_radius>" \
    --time="<print_time_needed>" \
    --vstep="<how_many_voxels>" \
    --covariance="<compute_covariance>" \
    --scheduler="<scheduler_name>,<parameter>=<value>,...,<parameter>=<value>"

The breakdown of the parameters is as follows:

sessionsfolder

Path to sessions folder within the study folder.
calculation

Run <seed> or <gbc> calculation for functional connectivity.
runtype

This flag specifies the 'individual' seed run on a series of single session, rather than a group run. You can run this calculation on a <list> (requires a list input), on <individual> sessions (requires manual specification) or a <group> of individual sessions (equivalent to a list, but with manual specification).
sessions

List of sessions to run.
inputfiles

Specify the comma separated file names you want to use (e.g.'bold1_Atlas_MSMAll.dtseries.nii,bold2_Atlas_MSMAll.dtseries.nii').
inputpath

Specify path of the file you want to use relative to the master study folder and session directory (e.g. /images/functional/). Default: [<study_folder>/sessions/<session_id>/images/functional].
overwrite

Delete prior run for a given session. Default is [no].
extractdata

Specify if you want to save out the matrix as a CSV file (only available if the file is a ptseries) <yes/no>. Default is [no].
outname

Specify the suffix name of the output file name.
ignore

The column in *_scrub.txt file that matches bold file to be used for ignore mask. All if empty. Default is [].
command

Specify the type of gbc to run. This is a string describing GBC to compute. E.g. 'mFz:0.1|mFz:0.2|aFz:0.1|aFz:0.2|pFz:0.1|pFz:0.2'.
targetf

Specify the absolute path for group result output folder. If using --runtype='individual' the output will default to --inputpath location for each individual session".
mask

An array mask defining which frames to use (1) and which not (0). All if empty. If single value is specified then this number of frames is skipped.
target

An array of ROI codes that define target ROI [default: FreeSurfer cortex codes].
rsmooth

Radius for smoothing (no smoothing if empty). Default is [].
rdilate

Radius for dilating mask (no dilation if empty). Default is [].
time

Whether to print timing information. [false]
vstep

How many voxels to process in a single step. Default is [1200].
covariance

Whether to compute covariances instead of correlations (true / false). Default is [false]
scheduler

Scheduler and relevant options. E.g. Specific scheduler string example for SLURM is: --scheduler="SLURM,jobname=gbc,time=24:00:00,cpus-per-task=2,mem-per-cpu=1500,partition=day".

Example of a group GBC run#

qunex fc_compute_wrapper \
    --sessionsfolder="<folder_with_sessions>" \
    --calculation="gbc" \
    --runtype="group" \
    --sessions="<session_id1>,<session_id2>,...,<session_idN>" \
    --inputfiles="<name_of_input_BOLD_timeseries>.dtseries.nii" \
    --inputpath="<path_for_input_file>" \
    --overwrite="no" \
    --extractdata="no" \
    --outname="<output_name_of_BOLD_fc_file>" \
    --ignore="<frames_to_ignore>" \
    --command="<type_of_gbc_to_run>" \
    --targetf="<path_for_output_file>" \
    --mask="<which_frames_to_use>" \
    --target="<which_roi_to_use>" \
    --rsmooth="<smoothing_radius>" \
    --rdilate="<dilation_radius>" \
    --time="<print_time_needed>" \
    --vstep="<how_many_voxels>" \
    --covariance="<compute_covariance>" \
    --scheduler="<scheduler_name>,<parameter>=<value>,...,<parameter>=<value>" # Scheduler and relevant options

Note that --runtype is now set to "group" and that --targetf is now mandatory.

Pseudo resting-state connectivity using task-based BOLD data#

BOLD task data can be processed (e.g. removal of mean task effect) to yield "pseudo" resting-state time series, which can subsequently be used for functional connectivity analyses. Pseudo resting-state is based on the premise that the task signal is a linear combination of two distinct components: the task-evoked signal and the underlying spontaneous resting-state signal. Put differently, if task effects are modeled with a GLM and regressed from the combined signal, the residual time series should closely resemble that of standard resting-state. Task modeling and regression using preprocess_conc are described in detail in the Running first-level and second-level task activation analyses section. Note that, for pseudo resting-state, un-assumed response .fidl files should be used with one event code per entire trial (e.g. --event_string="motor" when using function preprocess_conc).

In the first step, a GLM-based removal of the task structure needs to be performed. The residual BOLD time series can serve as input into the subsequent connectivity calculation.

The preprocess_conc will produce a new *.nii.gz or *.dtseries.nii residual timeseries that remains after regressing the relevant nuisance variables and the task structure. This residual BOLD time series can be used as the input file for computing GBC or seed-based functional connectivity using fc_compute_wrapper or individual Matlab functions.

Task-based functional connectivity using time point selection#

Task-activation analyses use the same principles as pseudo-resting-state. Task effects are once again modeled with a GLM using preprocess_conc to regress out both the nuisance signal as well as the mean task response. While removing mean task response from all trials, the trial-to-trial task-related variability is still retained in the signal. To compute task-based functional connectivity, a trial timeseries capturing trial-by-trial variability is composed by extracting the relevant frame (or an average of frames, e.g., frames corresponding to delay-related working memory activity) from each of the trials. This trial timeseries is then used to compute task-related functional connectivity.

Task modeling and regression are described in detail in the section on Running first-level and second-level task activation analyses. Note that, for task-based analyses, assumed response .fidl files should be used with multiple events per trial epoch (e.g. --event_string="Event1:boynton|Event2:boynton|" when using function preprocess_conc).

The preprocess_conc command will produce a new *.nii.gz or *.dtseries.nii residual timeseries that can be used as the input file for computing GBC or seed-based functional connectivity using compute_bold_fc or individual Matlab functions.

Resting-state parcellated connectivity#

Parcellated connectivity analyses may be run as an alternative to voxel-wise or greyordinate-wise connectivity. Cortical parcellation divides the cortex into non-overlapping regions that are anatomically or functionally distinct, with voxels within the same parcel sharing common characteristics. This approach has been demonstrated to improve signal-to-noise of the parcels that are functionally meaningful. In the example below parcellate_bold implements parcellation on the BOLD dense file using a whole-brain parcellation (e.g. Glasser parcellation with subcortical labels included based on a unified network partition. See: https://doi.org/10.1101/206292).

Example command for generating parcellated data using parcellate_bold:

qunex parcellate_bold \
    --sessions="<comma_separated_list_of_cases>" \
    --sessionsfolder="<folder_with_sessions>" \
    --overwrite="<yes/no>" \
    --inputfile="<name_of_input_timeseries>.dtseries.nii" \
    --inputpath="<path_for_input_file>" \
    --parcellationfile="<dlabel_file_for_parcellation>" \
    --computepconn="<yes/no>" \
    --outname="<name_of_output_pconn_file>" \
    --outpath="<path_for_output_file>" \
    --inputdatatype="<type_of_dense_data_for_input_file>" \
    --scheduler="<scheduler_name>,<parameter>=<value>,...,<parameter>=<value>"

The parcellate_bold command above will produce a new .ptseries.nii that can be used as the input file (specified with the --inputfile flag) for computing GBC or seed-based functional connectivity using compute_bold_fc.

The breakdown of the parameters is as follows:

sessions

Location of the batch file.
sessionsfolder

Path to study folder that contains sessions.
overwrite

Delete prior run for a given session; default is [no].
inputfile

Specify the name of the file you want to use for parcellation (e.g. bold1_Atlas_MSMAll_hp2000_clean)
inputpath

Specify path of the file you want to use relative to the master study folder and session directory; e.g. [/images/functional/]; default [<study_folder>/sessions/<session_id>/images/functional].
parcellationfile

Specify path of the file you want to use for parcellation relative to the master study folder; e.g. [/images/functional/bold1_Atlas_MSMAll_hp2000_clean.dtseries.nii].
computepconn Specify if a parcellated connectivity file should be computed (pconn). This is done using covariance and correlation (yes/no) [no]
outname

Specify the suffix output name of the pconn file.
outpath

Specify the output path name of the pconn file relative to the master study folder; e.g. [/images/functional/].
inputdatatype

Specify the type of data for the input file; e.g. [dscalar] or [dtseries].
scheduler

Scheduler and relevant options.

QuNex documentation

Running BOLD functional connectivity analyses

Contents

Running BOLD functional connectivity analyses#

Functional connectivity analysis Matlab functions#

Running the functional connectivity analyses using the bash wrapper command#

Computing seed-based functional connectivity maps#

Example for an individual run#

Example for a group run#

Resting-state global brain Connectivity (GBC)#

Example of an individual GBC run#

Example of a group GBC run#

Pseudo resting-state connectivity using task-based BOLD data#

Task-based functional connectivity using time point selection#

Resting-state parcellated connectivity#