Princeton FCMA Toolbox
Generate an FCMA file for voxel selectionThe 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:
- Online: Run the FCMA File Generator to generate one online OR
- Text editor:Edit the FCMA file directly. Some templates with lots of comments and minimal templates without:
- FCMA Voxel Selection Template, and
- FCMA Prediction Testing Template
- Leave-one-subject-out Minimal Template: Selection
- Leave-one-subject-out Minimal Template: Testing
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 directoryYour 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 selectionOnce 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:
Monitor progress including estimated run timeVoxel 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.oJOBIDwhere 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 -tIf something is horribly wrong you can delete the job (which will also kill all the related subtasks) via:
Make mask(s) for top k voxelsThe 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 repeatThis 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:
- 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.
- 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.