Princeton FCMA Toolbox

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
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
```
  (at the PNI, these templates are available in /opt/pni/doc/template*). You can edit the file with your favorite text $EDITOR:
```
$EDITOR myparams.fcma 
```
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.

PNI Users: please use high-performance scratch space for your analysis (/fastscratch as of fall 2013.)

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.

References

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.
Wang, Y., Li, K., Charikar, M., Cohen, J. D., & Turk-Browne, N. B. (May, 2013). What you find depends on how you look: Category selectivity in frontal cortex revealed by whole-brain correlation analysis.. Poster presented at Vision Sciences Society, Naples, FL.
Turk-Browne, N. B., Li, K., Charikar, M., Cohen, J. D., & Singer, B.D. (2010). Computing and Mining the Full Correlation Matrix of Human Brain Imaging (fMRI) Datasets. J. Insley Blair Pyne Fund Proposal (funded)

Getting Help

Please contact Yida Wang or Ben Singer

The Princeton FCMA Toolbox

Using FCMA

Generate an FCMA file for voxel selection

Copy your FCMA file to your FCMA analysis directory

Run FCMA voxel selection

Monitor progress including estimated run time

Make mask(s) for top k voxels

Create an FCMA file to test accuracy and repeat

Notes

References

Getting Help