FCMA Toolbox Tutorial
This tutorial goes through a leave-one-subject-out analysis using FCMA. In the interest of reduced time and data, the example is simplified, but the steps would be the same in a full scale analysis.
Sample data and scripts: fcma_tutorial.zip [~330MB] contains the materials that will be used in the tutorial.
The sample data is a preprocessed form of the original Haxby et al (2001) 8-category study data-- down-sampled to 4mm cubed voxels, motion-corrected and detrended, and aligned to the MNI standard brain.
fcma_tutorial directory you unzipped, or any directory you set up, should have two directories set aside for a) data and b) blockfiles. If each subject uses its own blockfile (as in the tutorial) each blockfile should have the same name as its corresponding data file, with a
.txt rather than
.nii.gz extension. In the tutorial dir you should see:
data step1_selection step3_topmask face_house_blocks step1_template.fcma step4_template.fcma MNI152_T1_4mm_brain_mask.nii.gz step2_calcranks step4_test_leftout pni_fcma_submit step2_template.fcma steps_include
face_house_blocksdirectories contain the fMRI data and corresponding block files for each subject:
> ls data/ subj1.nii.gz subj3.nii.gz subj5.nii.gz subj2.nii.gz subj4.nii.gz subj6.nii.gz > ls face_house_blocks/ subj1.txt subj3.txt subj5_orig.txt subj6.txt subj2.txt subj4.txt subj5.txt
subj5_orig.txt blockfile is there because subject 5's data has 22 unique blocks vs 24 for the other subjects; the last two blocks have been repeated in the
subj5.txt file, which is the one we'll use since
pni_fcma assumes the same number of blocks per subject.
The 4 scripts (prefixed by
step4) correspond to the four main steps of the analysis detailed below. Running each script without arguments provides a brief bit of help text. All but the step3 script take as one of their inputs a template fcma file, and output specialized versions of it, holding out a different subject for each iteration of the outer analysis loop (the
num_items_held_for_test settings required to hold out the iteration's subject are computed automatically).
The resulting fcma file can be run with either
pni_fcma_submit. The latter will launch multiple multi-threaded processes (possibly on multiple machines), as is normally done during selection. Running
pni_fcma myconfig.fcma directly will run a single copy of the program as one process, but it can contain multiple threads for partial parallelization using OpenMP. In order to run multi-threaded during direct execution of
pni_fcma, you need to set the environment variable
OMP_NUM_THREADS to the number of cores you want to use. One or two less than the total number of physical cores available is a good choice as it will allow the machine to remain responsive while running. Note that setting
omp_num_threads in the fcma file will do the same, but only if
pni_fcma_submit is used to launch the process(es).
Each selection job runs a nested, inner loop: a leave-one-out cross validation run for a subset of voxels, for all subjects, for all blocks (except those held out). The voxel subsets are combined by a master process and each voxel's average score (across included subjects & blocks) is recorded.
The tutorial has 4 steps, each with a script that generates the fcma files that will be used. The help text of each script is included below. Once the fcma files are created you run
pni_fcma_submit on each .fcma file that is created. By examining the contents of the fcma file, the appropriate settings for each step in the analysis you want to carry out should hopefully become apparent. Please contact us at pnihelp[at]princeton[dot]edu if you have any questions and to report any issues.
Step 1: Selection
usage: step1_selection config.fcma [savedir] creates updated copies of the provided fcma file -- one for each leave-one-out voxel selection run-- and saves them all in the "step1" directory, unless an optional alternative "savedir" is supplied. uses files in the provided .fcma config "datadir" directory; each file's blocks are left out in one of the resultant fcma files. voxel selection runs can then proceed, each run using one of the generated fcma files in "step1"
Step 2: Top voxel determination
usage: step2_calcranks configfile topvoxlist [savedir] reads "configfile" .fcma template and specializes it for running pni_fcma on increasing number of topvoxels. loads the "topvoxlist" output from selection and reports percent correct for an increasing number of top voxels (10,20,50,100,200,500,1000 ...) so that a minimal viable cutoff can be chosen for the next step. saves results to the "step2" directory, unless an optional alternative "savedir" is supplied.
Step 3: Top voxel mask creation
usage: step3_topmask prefix N - will use AFNI to search "prefix"_seq.nii.gz and create a mask of top "N" voxels - saves result as "prefix"_top"N"_mask.nii.gz - "prefix" can contain directory names
Step 4: Testing left-out subject
usage: step4_test_leftout sconfig mask outfile "config" is a config file created during step1 "mask" is topvoxel mask created during step3 "outconfig" is the config file name to save Note: the "sconfig" and "mask" should be for the same left-out subject