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.

Downloads

• 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.

Preparation

The 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

and the data and face_house_blocks directories 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

The extra 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 step1 through 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 first_left_out_block_id and 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 or 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 the address in the footer if you have any questions and to report any issues.

1. Selection
2. Top voxel cutoff determination
3. Top voxel mask creation
4. Testing on left-out subject

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