From NITRC Wiki

Contents 1 Overview 2 Workflow 3 Inverse solutions to obtain source activity 4 Calculate FCMs 4.1 FCM GUI 4.1.1 Configuration 4.1.2 Files 4.1.3 Seed Voxels 4.1.4 Time Windows 4.1.5 Frequency 4.1.6 Run! 4.1.7 Calculate Output Volume 4.1.8 View 4.2 Command line functions 5 Statistics across subjects 5.1 GUI 5.1.1 Get Population Button 5.1.2 P-images 5.1.3 Correlation 5.2 Command Line 6 Looking for help on the old FCM functions?

Overview

The functional connectivity map (FCM) toolbox has been written by Dr. Adrian G. Guggisberg from the University of Geneva. It allows you to calculate source functional connectivity (FC) from MEG or EEG data. You can use continuous recordings or event-locked settings. Currently, the following measures of FC are performed:

• Coherence (magnitude squared as well as the imaginary and real component)
• Phase lag index
• Amplitude envelope correlation

FC can be calculated for all connections between voxel pairs of for selected regions of interest. The toolbox also includes visualization features and statistical tools.

Workflow

• Run the time-frequency source analysis to obtain source activity.
• Calculate and visualize FCMs
• Perform statistics across subjects

Inverse solutions to obtain source activity

• See NUTMEG's Time-frequency Source Analysis for general help on this step.
• It is usually sufficient to use only 1 long time window with the entire data and one relatively broad frequency band. However, you may want to check the effect of using separate weights for time windows and freq bands.
• You will need a scalar inverse solution (SAM or MinNorm_Scalar).
• Choose "single state"
• Make sure to output the filtered data and the weights.

Calculate FCMs

FCM GUI

• Type fcm_gui, which opens a new interface.

Configuration

• Click the "Set Configuration" Button.
• You can load and save frequently used configurations. Some example config files are already available.
• Seed voxels: For which voxels do you want to calculate FC? Use "All" if you want to analyze the entire brain, or you can define "Selected" voxels or regions of interest. For cortico-peripheral connectivity, e.g., corticomuscular coherence, choose "Extracerebral".
• Connection voxels: Which connections of your seed voxels to you want to analyze? I recommend choosing "All". The option "Grid" has been used previously to reduce computation time, but is now obsolete because the algorithm for computing all-to-all connection is much much much faster.
• Average across: How do you want to calculate the mean FC score of each voxel? Usually, the option "All" works nicely, but you may want to restrict the averaging to certain types of connections. You can also choose the option "Seed" to average across the voxels of the seed regions rather than across all connection voxels. If you use Extra seed data, the averaging is set to "None".
• Data Type: This is more or less self-explanatory. The "Non-Event-Locked Multi-Trial Data" option is useful if you have continuous data, from which you want to remove periods with artifacts. In this case, you can arrange the artifact-free periods as separate 'trials' and choose this option.
• Functional Connectivity Measure: Just what it says.
• Output:
  • Mean: the FC between seed voxels and connection voxels, averaged across the selected connection types.
  • Z normalized mean: The same as above, but expressed as a z-score for each analyzed frequency bin/band. It is extremely important to use z-normalized maps when performing analyses across subjects.
  • L image: This option performs a t-test of the FC of each seed voxel against the mean FC of homologous contralateral voxels.
• Optionally you can save your settings to file.
• Click on "Close" to return to the main GUI and use the selected settings. Some of the selected settings should be displayed on top of the main GUI.

Files

• Push the "Browse" buttons to load the following files:
  • The NUTMEG session file. You have to use the same session file as for the time-frequency source analysis.
  • The filtered sensor data (filtdata_*.mat) created with NUTMEG's Time-frequency Source Analysis.
  • The inverse solution weight matrix (W_*.mat) created with NUTMEG's Time-frequency Source Analysis.
  • Optionally, if you want to calculate FC to extra channels (e.g., corticomuscular coherence), the extra channel data. The file must contain a variable named "ext" with the extra channel data (time x channel x trials).

Seed Voxels

If you chose "Selected" seed voxels in the configuration, you can define the seed voxels you want to analyze here.

• If you want to define a seed region (= more than one voxel), push the corresponding button. This will allow you to manually delineate the region on the coregistered structural MRI. First make a circle around the area of interest in the axial plane, then in the coronal plane, and finally in the sagittal plane.
• If you want to seed only one voxel you can either select the one currently marked by green crosshairs in the SPM window, or enter the coordinates.

Time Windows

• In event-locked multi-trial datasets, this defines the time windows relative to 0, for which you want to calculate FC.
• In continuous single-trial datasets subjected to a calculation of coherence, this defines the data segments (Welch time windows) used for FFT.
• In all other cases, this panel is not needed and inactive.

Frequency

• If you are calculating complex coherence:
  • you can look at coherence spectrograms or frequency bands.
  • Enter the lowest and highest frequencies of the spectrum or band.
  • If you want to assess multiple frequency bands, you can enter multiple cutoff values (separated by space), but currently only for event-locked multi-trial datasets. For other datatypes, you currently have to run single bands in multiple calls.
  • Set the number of frequency bins calculated by the FFT. This will determine the frequency resolution: e.g., if you have a sampling rate of 512, a nfft of 512 will yield a frequency resolution of 1 Hz, a nfft of 1024 of 0.5 Hz.
  • Optionally, you can apply multiple tapers, which leads to a smoothing across frequency bins. The taper bandwith has to be set in Hz.

• For amplitude correlation and PLI:
  • only frequency bands can be analyzed.
  • By default, if you leave the frequency cutoff fields empty, the FC values are calculated for the entire frequency band used in the Time-Frequency Source Analysis.
  • Optionally, you can re-bandpass filter the prefiltered data (saved in filtdata*.mat) within a smaller bandwidth by entering the corresponding cutoff values.

Run!

• For calculation of coherence and amplitude envelope correlation, a local computer is now usually sufficient even for calculating very large numbers of connections, so you do not need to submit to Linux cluster anymore in most of these cases. (Yes the functions are now much much much much much much much much ... faster than they used to be!)
• For calculation of the phase lag index, large numbers of connections (e.g., all-to-all voxels) will take a very long time on a single computer. In this case, you might want to distribute the task to multiple computers on a Linux cluster. For this, you will have to compile one or several of the functions in the [NUTMEGbase]/fcm/src subfolder on one of the used Linux computers and setup a script similar to the examples in [NUTMEGbase]/fcm/scripts. You can then prepare your data by clicking on "Prepare for Linux cluster" for any number of jobs. You may have to transfer this data to the cluster. After running on the cluster with the script, transfer the outputs back to your local computer (the outputs are saved in a directory named either "ccohere", "pli", or "ampcorr"), and assemble the multiple outputs to a single file by pushing the corresponding button.
• A File dialogue pops up to let you select the file name of the FC data. Make sure to leave the proposed prefix (e.g., "ccohere", "pli", or "ampcorr") unchanged!!
• If everything worked correctly (and if you did not change the prefix in the file name), a new file will appear in the listbox on the bottom left.

Calculate Output Volume

• Just hit the button.
• This will create a new s_beam*.mat file listed in the listbox on the bottom right.

View

• Select the file you want to visualize and hit "View". This will open the Results Viewer.
• Typically, the mean FC of each voxel to your selected other voxels will be plotted in up to 5 dimensions (space, time, and frequency).
• If you calculated a spectrogram, the Frequency will be displayed in the x-axis instead of the y-axis, for easier viewing.
• If you calculated complex coherence, you can switch between magnitude squared coherence, the imaginary, and the real component.
• If you calculated all-to-all FC and are viewing the "Mean" output data (not the z-normalized or the L-images), you can seed selected voxels or regions within the viewer and look at the FC to these seed regions (i.e., you can explore 8 dimensions: space x space x time x frequency!)
• The "Ref" button refreshes the file lists in both listboxes of the FCM GUI. This may be useful if you change the MATLAB working directory.

Command line functions

Command line functions are useful for batching multiple subjects. Also some features are currently only available via command line, e.g., usage of ICA data.

Type help fcm to get an overview of the available functions and the workflow. Use the help text of each function to see the usages.

 [Set config]
1. fcm_start                    Sets the FCM configuration: seed voxels, connections, output, etc.        
2. fcm_selvoxidx                (optional) Select seed voxels of interest
3. fcm_conndef                  Defines the connections between voxels to be analyzed.

[Calculate functional connectivity on a single computer]
4. fcm_sourceconnectivity       Calculates functional connectivity metrics for voxels

[Calculate functional connectivity on a linux cluster]
4a. fcm_preparejobs             Creates text files with job descriptions for Linux cluster. 
                                Output is stored in a new directory named "comps".
4b. sccohere1/3/31, spli1/3/31, sampcorr1/3/31  
                                Calculate source connectivity on a linux cluster (compiled binary)
4c. fcm_assemble                Assembles the cluster data 

[Calculate and visualize maps]
5. fcm_comcoh2beam              Creates maps from complex coherence results.
6. nut_results_viewer           View maps.

Statistics across subjects

GUI

Call the GUI for across-subject statistics with fcm_across_subject_gui or by pushing the button "Across Subject Stats" in the FCM GUI.

The listbox on the left lists all s_beam*.mat files in the current directory which are available for viewing or analysis. You can refresh the list by clicking on the "Refresh" Button.

Get Population Button

This creates "Population Files" with the data of multiple subjects or patients. You will need them for the stats. When clicking on this button, you will be asked for a Pointer File containing the paths to the s_beam*.mat files of the individual subjects or patients. Then, enter the name of the new Population File to be created. You then have the option to index these files together with a short description of the population for easy access in the menus below.

P-images

P-images contain a statistical comparison between the FCM of an invidivual patient and a control population. T-tests for one sample test the null hypothesis that the difference between patient and controls is 0 at each voxel. The variance at each voxel is smoothed with a 20x20x20 Gaussian kernel.

• Choose a spatially normalized(!) s_beam*_spatnorm.mat file of a patient in the listbox on the left.
• Choose a control population, either by clicking on "File" to locate the population file, or by clicking on "Menu" to choose among the populations that you have indexed previously.
• Push "Calculate P-image".
• The new P-image file will be listed on the left. You can visualize it by clicking on "View".

Correlation

You can correlate the FCMs at each voxel with a clinical or behavioral score. Pearson correlation coefficients and staticitical sigificance between the FCM value and the score will be calculated at each voxel.

• Choose an "active" population, either by clicking on "File" to locate the population file, or by clicking on "Menu" to choose among the populations that you have indexed previously.
• Enter the variable containing the behavioral score. You can use variables in the MATLAB workspace or in files. You also have the option to index to parts of this variable by using the MATLAB indexing convention, e.g., B(:,5), and to process the score before correlation, e.g., abs(B).
• Optionally, you can enter co-variable(s) for calculating partial correlations.
• Push "Calculate Correlation" (or "Partial Correlation").
• Enter the name of the new correlation file to be saved.
• The new correlation file will be listed on the left. You can visualize the correlations by clicking on "View". In addition to the usual windows, you will also see a correlation plot updating to currently selected voxels, time windows, and frequencies. Click the right mouse button over the plot axis to change colors or to display the subject numbers. Right click over the regression line to change the line color.

By default, corrections for testing multiple voxels are performed with a false discovery rate (FDR) of 10% and a cluster threshold of 15. You can change the FDR to other values (e.g., 5%), by typing:

load s_beam_somecorr.mat
beam.corr.FDR = 0.05;
save s_beam_somecorr.mat
tv s_beam_somecorr.mat

The cluster threshold of 15 is clearly insufficient to correct the familywise error, it is merely used for an exploration of the data! To obtain a sufficient cluster-based correction, you can use the SnPM correlation which will determine the cluster threshold based on permutations.

Command Line

The following functions are available. Use the help texts to get more information.

fcm_beam2Pimage               Calculates "P-images".
fcm_corr                      Correlates maps with behavioral/clinical variables.
fcm_partialcorr               Calculates partial correlations between maps and behavioral/clinical variables.

Looking for help on the old FCM functions?

The old functions should not be used anymore, as they are buggy and work only for CTF datasets. However, if you absolutely need to see the corresponding help again, you can find it here: Old FCM functions.