Functional connectivity analysis in QuNex

QuNex 0.100.0 introduced a set of updated MATLAB functions and corresponding QuNex commands that extend its functionality for running functional connectivity analyses. Specifically, the update includes the following new functions:

• fc_extract_roi_timeseries Function for extraction of ROI timeseries for further analyses.

• fc_compute_roi_fc Function for computation of ROI-based functional connectivity.

• fc_compute_seedmaps Function for computation of seed-based functional connectivity maps.

• fc_compute_gbc Function for computation of Global Brain Connectivity (GBC) maps.

Each of these functions enables:

• computation of functional connectivity for either individual participant or for a group of participants,

• flexible specification of regions of interest,

• the ability to work with continuous timeseries, concatenated trial- or block-related timeseries, and trial- or block-related averages,

• saving of results in different file formats,

• direct calls and use of resulting data from custom MATLAB/Octave scripts,

• computation of a number of different functional connectivity estimates: Pearson’s r, Spearman’s rho, covariance, cross correlation, coherence, mutual information, partial correlation, precision matrix, coherence, and multivariate autoregressive model.

This post first describes the common interface and settings for all the functions, and then specifics of each of the functions and their options.

Specifying the input files

The input files, i.e., the files over which the functional connectivity is to be computed, are specified using the flist parameter. The value of the parameter can be either a path to a valid .list file, or a string that contains the same information.

List files

.list files are text files that list files related to each session that is treated as a single ‘subject’ in the analysis. An example content of the .list file is:

session id: s01
    roi:/data/mystudy/sessions/s01/images/segmentations/freesurfer/mri/aseg.nii.gz
    conc:/data/mystudy/sessions/s01/images/functional/concs/bold_nifti_wm_g7_hpss_res-mVWMWB1de.conc
    fidl:/data/mystudy/sessions/s01/images/functional/events/wm.fidl
session id: s02
    roi:/data/mystudy/sessions/s02/images/segmentations/freesurfer/mri/aseg.nii.gz
    conc:/data/mystudy/sessions/s02/images/functional/concs/bold_nifti_wm_g7_hpss_res-mVWMWB1de.conc
    fidl:/data/mystudy/sessions/s02/images/functional/events/wm.fidl

In this example, session id specifies the session code. roi provides the path to a subject specific ROI file, in this case a FreeSurfer segmentation. conc provides the path to a .conc file listing files that constitute the set of images related to the working memory task – in this case the files were also spatially smoothed, high-pass filtered and the nuisance signal was regressed out. While fidl provides the path to a .fidl file that describes the event structure of the working memory task.

Another example of a .list file is:

session id: s01
    file:/data/mystudy/sessions/s01/images/functional/bold1_g7_hpss_res-mVWMWB1d.dtseries.nii
    file:/data/mystudy/sessions/s01/images/functional/bold2_g7_hpss_res-mVWMWB1d.dtseries.nii
    file:/data/mystudy/sessions/s01/images/functional/bold3_g7_hpss_res-mVWMWB1d.dtseries.nii
session id: s02
    file:/data/mystudy/sessions/s02/images/functional/bold1_g7_hpss_res-mVWMWB1d.dtseries.nii
    file:/data/mystudy/sessions/s02/images/functional/bold2_g7_hpss_res-mVWMWB1d.dtseries.nii
    file:/data/mystudy/sessions/s02/images/functional/bold3_g7_hpss_res-mVWMWB1d.dtseries.nii

In this example the .list file lists for each session the three preprocessed resting state bold files over which to compute functional connectivity.

For data processed using QuNex and located in the QuNex folder hierarchy, the create_list command presents a simple way of compiling list files. For more detailed information on .list files, please, consult the QuNex documentation.

List strings

In come cases, e.g., when computing functional connectivity for a single session, or when embedding the function in custom scripts, it may be cumbersome to create .list files in order to call functional connectivity functions. In these cases, it is possible to provide the same information as a string. The string has to start with the name of the list and then contain the same information as would be provided in the list file, with | character used instead of a newline.

An example of the list string is:

--FileList="listname:rest|session id:s01|file:/data/mystudy/sessions/s01/images/functional/bold1_g7_hpss_res-mVWMWB1d.dtseries.nii|session id:s02|file:/data/mystudy/sessions/s02/images/functional/bold1_g7_hpss_res-mVWMWB1d.dtseries.nii"

Specifying regions of interest

Regions of interest can specified in multiple ways using the roiinfo parameter. A few of the possibilities are described here.

Names file

If a path to a .names file is provided, then the file will be used to specify ROIs. For detailed specification of .names files, please see the QuNex documentation for additional details. Briefly, a .names files are text files in which the first line provides a path to an image that defines possible ROI, and all following lines specify the specific ROI to be used. Each line has to provide three values separated by a | character. The first value is the name of the ROI. The second is a list of integer codes that specify the voxels and/or grayordinates to be included in the ROI. The third is a list of integer codes in an optional subject specific ROI file (e.g., a FreeSurfer segmentation) to be used as a mask for the group defined ROI.

An example is:

/data/study1/ROI/master_mask.nii.gz
ACC|101|3,42
DLPFC|108|
LTh||9
RTh||48

This file specifies four ROIs. The first is ACC that consists of all the voxels with integer values 101 in the /data/study1/ROI/master_mask.nii.gz file that overlap with integer codes 3 and 42 in the subject specific file. The second is DLPFC that consists of all voxels with integer values 108 in the /data/study1/ROI/master_mask.nii.gz file. The third and fourth are the left and right thalamus that are defined using integer codes 9 and 48 from the subject specific segmentation file, respectively.

The subject specific ROI file has to be listed in the .list file or string as explained in the previous section.

.names files can be used with volume files and any CIFTI files that can provide integer values (e.g., dscalar, dtseries, dlabel).

CIFTI label image

If a path to a CIFTI label image is provided, then the labels defined in the file will be used to specify ROIs. If one wants to use only a subset of ROIs or maps defined in the label image, these can be specified using optional key-value pairs in the roiinfo parameter (see below).

CIFTI parcellated image

If a path to a parcellated file (e.g., a pscalar or ptseries) is provided, then the information about the parcels will be extracted from the file and used to define ROI. Again, if one wants to use only a subset of parcels defined in the parcellated image file, these can be specified using optional key-value pairs in the roiinfo parameter (see below).

Volume or CIFTI dense files

If a path to a volume image or a dense CIFTI image is provided, the ROI specification depends on the number of volumes in the image or the number of volumes specified to be retained by the optional volumes or maps parameter.

• One volume with integer values All the unique integer values in the volume will be used to specify ROIs. If roinames optional parameter is provided, the ROIs will be named as specified.

• One or more volumes with scalar (non-integer) values Each volume will be used to define an ROI. The extent of the ROI will be defined by all non-zero values in the map. If an optional threshold or thresholds are provided, then they will be applied before ROI is defined. The scalar values will be stored as weights. If the optional roinames parameter is provided, the ROI will be named as specified. If the file is a CIFTI scalar with named maps, then the map names will be used to name ROI. roinames has priority.

• One or more volumes with binary values Each volume will be used as a mask to define an ROI. If the optional roinames parameter is provided, the ROI will be named as specified. If the file is a CIFTI scalar with named maps, then the map names will be used to name ROI. roinames has priority.

• Two volumes, first with integers and the second with scalars The first volume will be used to define ROIs, each integer code will be used as a mask for an ROI. The second volume will be used to define the weights for the ROIs. If the optional roinames parameter is provided, the ROI will be named as specified.

Optional parameters

Optional parameters can be specified in addition to the path to the files described above. They need to be provided as <key>:<value> pairs separated from each other and the initial path with the | character. The optional parameters are:

• volumes A comma separated list specifying indices of the volumes to be used to define ROI.

• maps A comma separated list specifying names of maps (e.g. in a dscalar image) to use to define ROI.

• rois A comma separated list specifying ROI indices or ROI names to retain and use. The specification will reorder the ROI in the order listed in the parameter.

• roinames A comma separated list of names for the ROI that are created. They should be listed in the order the ROI are created, this being the order of the sorted ROI integer codes, the order of the volumes to be used as ROI masks, or the order specified in the "rois" parameter.

• threshold One or two comma separated numbers, specifying the threshold(s) to be used when creating ROIs from scalar maps. A positive number indicates that only values equal or higher than the provided threshold are to be used. A negative number indicates that only values equal or lower than the provided threshold are to be used. If both positive and negative threshold are provided then both the values equal and higher to the positive threshold and the values equal or lower than the negative threshold will be used.

An example use of optional parameters is:

--roi_info="/data/ROI/regions_of_interest.dlabel.nii|maps:control_roi|rois:RDLPFC,RACC,RIFC,LDLPFC,LIFC,LACC"

In the above example, regions_of_interest.dlabel.nii file is used to specify ROI. Only map control_roi, is to be used, from which RDLPFC, RACC, RIFC, LDLPFC, LIFC, LACC labeled regions are to be used.

Another example:

--roi_info="/data/results/significant_activations.dscalar.nii|volumes:1,3,8|roinames:congruent,incongruent,neutral|threshold:3"

In this example significant_activations.dscalar.nii file will be used to specify regions congruent, incongruent, neutral that will correspond to all grayordinates with values 3 or higher in volumes 1, 3, and 8, respectively.

List of parcels

When the input files for the analysis (the ones specified as the input files) are parcellated timeseries, then the parcels to be used for the analysis can be specified in a string that starts with parcels: followed by a comma separated list of parcels to work with. An example specification is:

--roi_info="parcels:LDLPFC,RDLPFC,RACC,LACC,RTh,LTh"

Specifying frames to include in the analysis

Which frames to use in the functional connectivity analysis is specified primarily by the frames parameter and additionally by the options parameter. The frames parameter takes three types of input:

• a single integer value This specifies the number of frames to skip at the onset of the file.

• a numeric array This specifies which frames to use (marked with 1) and which to skip (marked with 0).

• an event definition string A string that describes frames to extract in relation to the per-session fidl file provided in the input files list.

When calling the command from the terminal, the single integer value can be provided as a single number, whereas the numeric array has to be provided enclosed in square brackets, e.g.:

--frames_info="[0 1 1 1 1 1 1 1 1 1 0 0 1 1 1 1 0 1 1 1 1 1 1 1 1]"

Event definition string

Event definition string refers to the per-session fidl event timing file that describes the event structure of the scan. For detailed information on the fidl files, please consult the QuNex documentation for details. Briefly, a fidl file should have the following structure:

2.0 cue stimulus response
6.0  0 1 315
10.0 1 3 315
14.4 2 1 315
18.0 0 1 421
12.0 1 3 421
16.8 2 1 421
18.0 -6
34.0 0 1 374
36.0 1 3 374
41.1 2 1 374

The first line provides the TR (2.0 in this case) and then a list of event names. All the following lines describe the timing of the events and possible additional values. The first value in the line is the time of the event in seconds. The second value is the 0-based index of the event name. In the above example 0 refers to cue, 1 to stimulus and 2 to response events. The third value is the event duration in seconds. The fourth value is optional additional information. In this case the fourth value refers to the reaction time in the related trial. If the second value starts with -, the number designates, how many frames to exclude from the analysis starting at the time specified by the first value. In the example above, six frames are to be excluded starting from 18th second in the recording.

The event string itself should have the following structure:

<extraction name>:<event list>:<extraction start>:<extraction end>

extraction name is the name of the events extracted. event list is a comma separated list of events selected from the list provided in the header of the fidl file. extraction start specifies the first frame to be extracted related to the event start or end. extraction end specifies the last frame to be extracted related to the event start or end.

Extraction start and end should be specified as <s|e><frame number>. s refers to the event onset. e refers to the event end. s0 is the frame of the event onset. s2 is the second frame after the event onset, i.e., the third frame of the event. e0 is the frame of the event end, e1 is the frame following the event end, and e-2 is the frame two frames before the event end.

Visually:

| s0 | s1 | s2   ...   e-2 | e-1 | e0 | e1
|<- event start  ... event end ->|

Please, consult online documentation for img_get_extraction_matrices method for more detailed description.

The eventdata optional parameter

In cases when extraction is specified using fidl files and event definition strings, the data used to perform the analysis is further dependent on the eventdata optional parameter. How to specify optional parameters, please, see the section on optional parameters below.

eventdata parameter allows the following options:

• all Use all the frames identified across all the events in the extraction set.

• mean Compute the mean for each event specified in the extraction set and compute functional connectivity across the event means.

• min Extract the minimum value for each event specified in the extraction set and compute functional connectivity across the event minimum values.

• max Extract the maximum value for each event specified in the extraction set and compute functional connectivity across the event maximum values.

• median Extract the median value for each event specified in the extraction set and compute functional connectivity across the event median values.

Example: resting state data

When computing functional connectivity for the resting state data, it makes sense to use all the frames in the bold time series. However, if one wants to omit the first five frames of each bold run for example, the following frames specification would be used:

--frames_info="5"

Example: block design task data

Let’s assume that the participants performed a task in which they viewed negative, positive and neutral images. Each type of image was shown in blocks of 30 seconds. The user wants to compute the functional connectivity across all the frames related to the task blocks for each task separately.

The content of the fidl file in this case might be:

1 neg neu pos
10.0 0 30
55.0 1 30
95.0 2 30
135.0 2 30
175.0 1 30
215.0 0 30

The frames and eventdata parameters would be set to:

--frames_info="positive:pos:s4:e1|negative:neg:s4:e1|neutral:neu:s4:e1"
--options="eventdata:all"

With this specification functional connectivity would be computed for three conditions, positive, negative and neutral. For each of the conditions, functional connectivity would be computed on frames that started with the fourth frame after the block onset and ended with the second frame after the block end. This would take into account the slow evolution of the BOLD response, making sure to compute functional connectivity only after the response to task has reached maximum and ending before the decline in bold response after the task end.

Example: fast event related design task data

Let’s assume that the participants performed a Flanker task with congruent and incongruent stimuli in two conditions, a neutral condition and an incentive condition. The user wants to compute functional connectivity across both congruent and incongruent trials but separately for neutral and incentive conditions. The functional connectivity should be computed on the average BOLD response between the beginning of the 4-th and the end of the 6-th second after the stimulus presentation.

The content of the fidl file might be:

1 neutral_inc neutral_con incentive_inc incentive_con
16 0 2
19 1 2
24 1 2
27 0 2
...
517 3 2
521 4 2
526 4 2
530 3 2
...

The frames and eventdata parameters would be set to:

--frames_info="neutral:neutral_inc,neutral_con:s3:s5|incentive:incentive_inc,incentive_con:s3:s5"
--options="eventdata:mean"

With this specification functional connectivity would be computed across means that capture the peak of response for each of the trials in the neutral and in incentive conditions.

What data to save and where

The data to save, how it is named and where it is saved is specified using the targetf and a number of optional parameters.

The targetf parameter specifies the location in which the group level data are to be saved. Which group level data are saved is specified using the savegroup optional parameter. This can specify the combination of the type of data to be saved and the format in which it is to be saved. The specific options are function dependent. For instance, when running fc_compute_roifc, setting:

--options="savegroup:all_long,mat"

would instruct the function to save the results from all the sessions in a long format tab separated .tsv file as well as a MATLAB file.

Which individual level data to save is specified using the saveind optional parameter. This again specifies the type of data and data format depending on a specific function used. Additionally, itargetf optional parameter specifies, whether individual data are to be saved in the group folder specified in the targetf parameter (gfolder) or in the session specific images/functional folder (’sfolder’). In the latter case, the savesessionid additionally specifies whether session id should be part of the file name. When the target location is the group folder, session id is always added to the file name.

For instance, when using fc_compute_seedmap, setting:

--options="saveind:jr|itargetf:gfolder"

would instruct the function to save all the resulting functional connectivity estimates in seed-based maps located in a single file per each session saved in the group folder.

Alternatively, setting:

--options="saveind:fz|itargetf:sfolder|savesessionid:true"

would save Fisher-z transformed seed-based maps each in a separate file in the session specific images/functional folder adding session id to the file name.

Both savegroup and saveind can also specify ‘none’ in which case group or individual session data will not be saved.

Optional parameters

All functions also accept a number of optional parameters that should be provided as | separated <key>:<value> pairs to the options parameter. The following are some of the key settings enabled by optional parameters:

Functional connectivity measure used

The functions can compute functional connectivity using a number of measures. Some of the complex measures might only be available when computing ROI-based functional connectivity and not when computing seed-based maps or GBC. What functional connectivity measure to use is specified by fcmeasure optional parameter. The options are:

• r Compute Pearson’s r coefficient of correlation.

• rho Compute Spearman’s rho coefficient of correlation.

• cv Compute covariance estimate.

• cc Compute cross correlation.

• coh Compute coherence estimate.

• mi Compute mutual information estimate.

In case of ROI-based functional connectivity additional options are:

• icv Compute inverse covariance estimate (i.e. precision matrix or partial correlation).

• mar Compute autoregressive model coefficients.

The default is r. For some functional connectivity additional parameters can be specified using the fcarg optional parameter. For instance when computing mutual information the k parameter (number of nearest neighbors) can be set:

--options="fcmeasure:mi|fcargs>k:2"

When computing inverse covariance, the standardize and shrinkage parameters can be set:

--options="fcmeasure:icv|fcargs>standardize:partialcorr,shrinkage:LW"

Method for computing ROI signal

In cases where ROI signal is to be computed (e.g., when computing ROI-based functional connectivity matrices or seed-based functional connectivity maps), the roimethod optional parameter specifies how the ROI signal is to be computed. The options are:

• mean Compute the mean value across the ROI for each timepoint.

• median Compute the median value across the ROI for each timepoint.

• min Extract the minimum value across the ROI for each timepoint.

• max Extract the maximum value across the ROI for each timepoint.

• pca Compute the first eigenvariate across all the timepoints for the ROI.

The default value for the parameter is mean.

Motion scrubbing

To omit frames that were identified as bad due to excessive movement and/or large signal changes, use the ignore optional parameter. Please see the motion scrubbing section of the QuNex documentation for additional details. The parameter accepts a comma separated list of the following values:

• use Ignore frames as marked in the .use file after the motion scrubbing step.

• fidl Ignore frames as specified in the .fidl file.

• Ignore frames identified as bad in the column of the .scrub file.

The default is use,fidl.

In addition, in case of task-based data and eventdata based specification of frames to use, badevents optional parameter specifies, what to do with events that have bad frames. The parameter expects the following values:

• use Use any number of frames that were not identified and marked as bad.

• Use the frames that were not identified and marked as bad, but only, if the current event has at least of good frames.

• ignore If any frame in the event is marked as bad, ignore the whole event.