Princeton FCMA Toolbox

JavaScript is disabled! This Website REQUIRES JavaScript to function. Please enable JavaScript in your browser´s settings or choose another browser.

The Princeton Full Correlation Matrix Analysis (FCMA) Toolbox is a suite of tools for correlating, analyzing, and classifying patterns of correlation in fMRI time-series data.

The key data structure in FCMA is the Full Correlation Matrix (FCM), which contains the correlations between all pairs of voxels and time-intervals. Computing the entire FCM is intractable: the FCM for two one-hour fMRI sessions requires approx. 1.5 x 1019 correlations, nearly 20 years of compute time on a 4000-core computer cluster. The FCMA Toolbox correlates a given set of fixed time-intervals (blocks of TRs you specify) which together with some custom optimizations reduces the computational load to a matter of hours. A modest-sized cluster is still required to do unbiased calculations-- ones that use a wholebrain mask initially rather than depending on a preselected ROI based on activation (such as a GLM or an ANOVA). This is due to the ~40k voxels that will undergo autocorrelation and classification.

Here are the steps for running an FCMA analysis from a user perspective, including how to create an .fcma config file, without discussing the config settings in detail. Please see the config file and reference page for details, and the FCMA Toolbox Tutorial for a discussion in the context of a real analysis. To install FCMA and set up a machine or cluster of machines, system administrators should consult the cluster setup page.

Using FCMA

Generate an FCMA file for voxel selection
The FCMA program input parameters are provided via a configuration file with the ".fcma" extension (see description of the key parameters.) You can create an .fcma file:
1. Online: Run the FCMA File Generator to generate one online OR
2. Text editor:Edit the FCMA file directly. Some templates with lots of comments and minimal templates without:
  These are for the first and second phase of the analysis, respectively (described below.) The templates contains lines of instructions above each parameter setting, in the comments. The process starts with getting an fcma file:
```
cp [Downloads folder]/template.fcma [Analysis folder]/myparams.fcma
```
  You can then edit the file with a text editor.
Copy your FCMA file to your FCMA analysis directory
Your analysis directory is usually where your data files and masks reside, on a machine (or set of machines) that are set up to run MPI programs. If you have an account on a compute cluster:
```
scp myparams.fcma user@server:
```
This will copy the file to your home directory. Once you've logged in you can move it into your analysis directory (which might not be accessible from the login node. On the PNI cluster you must start up an interactive qrsh session first to get access to lab directories where data resides.) If you use the generator you have the option of copying the generated file contents directly into your editor window.
Run FCMA voxel selection
Once you have your .fcma file transferred and you are in your analysis directory where data is easily accessible and loaded, the pni_fcma_submit bash script will parse your .fcma file into command-line arguments for the pni_fcma compiled MPI program:
```
pni_fcma_submit myparams.fcma 
```
Monitor progress including estimated run time
Voxel selection is the most time-consuming step, and you'll want to get an estimate of the running time. The pni_fcma program will print out timing information so you can get a sense of how long the analysis will take. At the start it will write out the number of tasks required, and each task will report its run time in seconds upon completion. Multiply the run time reported (once it has settled) by the number of tasks to get an estimate of the run time. Note that this output may be to a file if the job was submitted to a cluster resource management system. In that case you can "tail -f" the output to get live updates:
```
tail -f myparams.oJOBID
```
where JOBID is the job number associated with your job (printed to console; you can also look for the file most recently updated in your current directory.) This example is for an SGE-based cluster like the PNI's. You can check the status of the job via the scheduler command:
```
qstat -t
```
If something is horribly wrong you can delete the job (which will also kill all the related subtasks) via:
```
qdel JOBID
```
Make mask(s) for top k voxels
The output of the first FCMA run will give you all voxels in order of their predictive performance (using SVM). Choose the top k voxels (where k below 2000 is typically sufficient) using the voxel ordering file ("_seq.nii.gz" suffix output) or via a threshold on the voxels scores ("_score.nii.gz" suffix output file).
Create an FCMA file to test accuracy and repeat
This time, choose "2 - Testing predictive accuracy" (if using the FCMA File Generator), or edit the testing template file, and run a second time. The testing phase does not require multiple tasks, but uses the same MPI-based pni_fcma program and submission mechanism: pni_fcma_submit mytestingparams.fcma.

Notes

Code by Yida Wang and Ben Singer, as part of research being carried out at the Princeton Neuroscience Institute in the Turk-Browne, Li, and Cohen labs.

Publications

Wang, Y., Cohen, J. D., Li, K., & Turk-Browne, N. B. (submitted). Full correlation matrix analysis (FCMA): A high-performance toolbox and case study for unbiased functional connectivity in human brain imaging.

Getting Help

Please contact Yida Wang or Ben Singer

Acknowledgements

This project is a collaboration between Psychology and Computer Science faculty and staff belonging to the Princeton Neuroscience Institute, and several organizations providing significant support. Development of the FCMA toolbox was made possible through the support of grants from the John Templeton Foundation and the National Science Foundation.

PNI