# 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](../UsageDocs/BOLDPreprocessing). ## 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`](../../api/gmri/fc_compute_gbc3.rst) – compute single subject and group level GBC maps * [`fc_compute_gbcd`](../../api/gmri/fc_compute_gbcd.rst) – compute single subject and group level GBC maps for individual distance from ROI bands * [`fc_compute_roifc`](../../api/gmri/fc_compute_roifc.rst) – compute single subject ROI functional connectivity matrices * [`fc_compute_roifc_group`](../../api/gmri/fc_compute_roifc_group.rst) – compute ROI functional connectivity matrices for a list of subjects * [`fc_compute_seedmaps`](../../api/gmri/fc_compute_seedmaps.rst) – compute functional connectivity seed-maps for a single subject * [`fc_compute_seedmaps_group`](../../api/gmri/fc_compute_seedmaps_group.rst) – 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 ` or `help ` 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)](../Overview/file_names). ### Example for an individual run ``` bash qunex fc_compute_wrapper \ --sessionsfolder='' \ --calculation="seed" \ --runtype="individual" \ --sessions=",,...," \ --inputfiles=".dtseries.nii" \ --inputpath="" \ --overwrite="" \ --extractdata="" \ --roinfo="/.names" \ --outname="" \ --ignore="" \ --options="" \ --method=" " \ --targetf="" \ --mask="" \ --covariance="" \ --scheduler=",=,...,=" ``` The breakdown of the parameters is as follows: * `sessionsfolder` Path to sessions folder within the study folder. * `calculation` Run `` or `` 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 `` (requires a list input), on `` sessions (requires manual specification) or a `` 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: [/sessions//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) . 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 */sessions//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. ``` bash qunex compute_bold_fc \ --sessionsfolder='' \ --calculation="seed" \ --runtype="group" \ --sessions=",,...," \ --inputfiles=".dtseries.nii" \ --inputpath="" \ --targetf="/" \ --overwrite="no" \ --extractdata="no" \ --roinfo="/.names" \ --outname="" \ --ignore="" \ --options="" \ --method="" \ --mask="" \ --covariance="no" \ --scheduler=",=,...," ``` 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: ``` bash --target="" ................ 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 [] --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' > '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 ``` bash qunex fc_compute_wrapper \ --sessionsfolder="" \ --calculation="gbc" \ --runtype="individual" \ --sessions=",,...," \ --inputfiles=".dtseries.nii" \ --inputpath="" \ --overwrite="" \ --extractdata="" \ --outname="" \ --ignore="" \ --command="" \ --targetf="" \ --mask="" \ --target="" \ --rsmooth="" \ --rdilate="" \ --time="" \ --vstep="" \ --covariance="" \ --scheduler=",=,...,=" ``` The breakdown of the parameters is as follows: * `sessionsfolder` Path to sessions folder within the study folder. * `calculation` Run `` or `` 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 `` (requires a list input), on `` sessions (requires manual specification) or a `` 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: [/sessions//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) . 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 ``` bash qunex fc_compute_wrapper \ --sessionsfolder="" \ --calculation="gbc" \ --runtype="group" \ --sessions=",,...," \ --inputfiles=".dtseries.nii" \ --inputpath="" \ --overwrite="no" \ --extractdata="no" \ --outname="" \ --ignore="" \ --command="" \ --targetf="" \ --mask="" \ --target="" \ --rsmooth="" \ --rdilate="" \ --time="" \ --vstep="" \ --covariance="" \ --scheduler=",=,...,=" # 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](../UsageDocs/BOLDTaskActivation) 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](../UsageDocs/BOLDTaskActivation). 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`](../../api/gmri/parcellate_bold.rst) 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](https://doi.org/10.1101/206292)). Example command for generating parcellated data using `parcellate_bold`: ``` bash qunex parcellate_bold \ --sessions="" \ --sessionsfolder="" \ --overwrite="" \ --inputfile=".dtseries.nii" \ --inputpath="" \ --parcellationfile="" \ --computepconn="" \ --outname="" \ --outpath="" \ --inputdatatype="" \ --scheduler=",=,...,=" ``` 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 [/sessions//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.