Work flow example for multimodal, multisurface regression (MMR)

Using tm_multimodal mmr to analyze multimodal neuroimaging data with TFCE enhancement

1) Creation of the TMI file with multiple surface (of either voxel or vertex images)

Say that your study includes five different types data (4 freesurfer surface projected, 1 voxel-based):

Note: all data MUST have the same set of subjects.

In your current directory, an example of data files from multiple modalities would be:

Vertex-based:

• Surface area (?h.all.area.03B.mgh)
• Cortical thickness (?h.all.thickness.03B.mgh)
• Grey Matter Neurite Density (?h.all.ICVF.03B.mgh)
• N-Back 2v0 contrast (?h.all.nbackS8.03B.mgh)

Voxel-based:

• TBSS FA skeleton (all_FA_skeletonised.nii.gz; mean_FA_skeletonised_mask.nii.gz)

The TMI file will have to be created in multiple steps.

(1) Add the surface data, surface objects, adjacency sets:

tm_multimodal create-tmi -o all.multimodal.tmi \
-i ?h.all.area.03B.mgh ?h.all.thickness.03B.mgh ?h.all.ICVF.03B.mgh ?h.all.nbackS8.03B.mgh \
-i_fs $TFCE_mediation/tfce_mediation/adjacency_sets/?h.midthickness $TFCE_mediation/tfce_mediation/adjacency_sets/?h.midthickness $TFCE_mediation/tfce_mediation/adjacency_sets/?h.midthickness $TFCE_mediation/tfce_mediation/adjacency_sets/?h.midthickness \ 
-i_adj $TFCE_mediation/tfce_mediation/adjacency_sets/?h_adjacency_dist_3.0_mm.npy

Explanation: In total eight surfaces have been included in the file (left and right hemisphere for each modality). For each surface, a corresponding surface objects must be added. In this case, the midthickness project fsaverage that is packaged with TFCE_mediation. Last, one set of adjacency objects is added for the left and right hemispheres. Again in this case, the adjacency set is the one packaged with TFCE_mediation and it is the adjacency geodesic distance based on the midthickness surface object.

(2) Add the TBSS data and mask:

tm_multimodal create-tmi -a all.multimodal.tmi \
-i all_FA_skeletonised.nii.gz \ 
-i_masks mean_FA_skeletonised_mask.nii.gz

Explanation: The all.multimodal.tmi file is appended to included the all_FA_skeletonised.nii.gz after the data mask has been applied (-i_masks mean_FA_skeletonised_mask.nii.gz). The file isn't ready for analysis until an adjacency set is created for the voxel mask.

(3) Add the adjacency set for the voxel mask:

tm_multimodal multimodal-adjacency -a all.multimodal.tmi \
-t voxel \
-va 26 \
-i mean_FA_skeletonised_mask.nii.gz

Explanation: The all.multimodal.tmi file is appended to included adjacency set for the mean_FA_skeletonised_mask.nii.gz. The voxel adjacency is set to 26 directions (-va 26), see this is a skeleton mask (i.e., adjacency in all directions). For fMRI or VBM, 6 directions should be used. Now the TMI is ready for analysis

(Optional 4) Check the TMI file:

tm_multimodal read-tmi-header -i all.multimodal.tmi 

Did you make a mistake with appending the TMI file? No problem! TMI files have a history function. Just 'roll-back' the file to an earlier version using tm_multimodal edit-tmi --revert {time-point}

2) Statistical analysis using tm_multimodal mmr OR tm_multimodal mmr-lr

The mmr (multimodal, multisurface regression) and mmr-lr (mmr low ram) scripts perform the regression, randomisation, and correct images for multiple comparison among all surfaces (vertex or voxel-based). The main difference between mmr and mmr-lr is that mmr performs TFCE across the entire dataset which can be RAM intensive. Conversely, mmr-lr creates memory-mapped files for each surface/adjacency set/etc. and runs them separately. This allows more parallel process for randomisation; therefore, mmr-lr is theoretically faster (and recommended).

Two steps are necessary: analysis/randomisation, FWER correction

(1) Statistical analysis using mmr-lr

tm_multimodal mmr-lr -i_tmi all.multimodal.tmi \
-i predictor_resids.csv -c covars_std_dm.csv \
-sa 0 1 0 1 0 1 0 1 2 --tfce 2 .67 2 1 -st 0 0 0 0 0 0 0 0 1 \
-os -n 10000 -p 12

Inputs:

• all.multimodal.tmi (TMI file)
• predictor_resids.csv (residuals of the variable of interest)
• covars_std_dm.csv (unit variance and demean covariates file)

Input explanation:

• -sa specifies the adjacency sets to be used with each surface. In this case, the left and right side for each surface (the first eight inputs), the last one is for the TBSS skeleton (26 neighbour connectivity).
• --tfce specifies the TFCE settings of H and E. It must be entered in pairs. In this case, the first [0] setting is for the surface (2 .67), and the second [1] setting (2 1) is for analysis using the TBSS skeleton.
• -st specifies the TFCE settings to be used with each surface. In this case, the first eight surfaces use the '0' setting, and the TBSS skeleton uses '1'.
• -os outputs the stats file.
• -n and -p specifies the randomisation should be used with 10000 permutations, and that GNU parallel should be used, respectively.

Outputs:

• output_all.multimodal/stats_all.multimodal.tmi (the uncorrected stats file containing the T-stats (or Z stats for mediation), positive TFCE transformed T-stats, negative TFCE transformed T-stats)
• output_all.multimodal/output_stats_all.multimodal.tmi/perm_maxTFCE_surf{SURF#}_tcon1.csv (the output permutation file for each surface)

(2) Correct the stats file for family-wise error rate among all images modalities.

If you are going to view your stats using TMI viewer (highly recommended). Otherwise, there's two options: (a) use the -op option to output PLY files with vertex painting for each surface (even the white matter skeleton stats) that can viewed using blender, meshlab, or any other 3D viewer. (b) use the '--outtype auto' output the stats files as mgh or nifti files depending if the images were originally vertex or voxel based.

cd output_all.multimodal/
tm_multimodal mmr -i_tmi stats_all.multimodal.tmi -mfwe

3) [Recommended] View the results using tmi_viewer!

If not installed, the instructions are at the bottom here