# 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](https://qunex.readthedocs.io/en/latest/wiki/Overview-FileList.html). ### 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](https://qunex.readthedocs.io/en/latest/wiki/Overview-FileROI.html) 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 `:` 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](https://qunex.readthedocs.io/en/latest/wiki/Overview-FileFidl.html) 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` 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` 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 `:` 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](https://qunex.readthedocs.io/en/latest/wiki/UsageDocs-MovementScrubbing.html) 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.