Skip to content

Voxel stats guide

Jump to bottom
etiaum edited this page May 21, 2025 · 6 revisions

By Brandon J. Hall, Gleb Bezgin & Étienne Aumont

1. When to use VoxelStats?

RMINC has limited functionality since only the dependent variable can be an imaging variable.
VoxelStats is a MATLAB package that allows us to run models that…

  • Use images as predictors
  • Use images as both outcome and predictor(s)
  • Use images of any type (PET, MRI, diffusion, etc) as long as they are co-registered into the same space.
  • Use images that are in .mnc format.

Table of contents

  1. Setting up
  2. Preparing models
  3. Adjusting and saving the results

1. Setting up VoxelStats

Step 1: open Terminal and start MATLAB (version 2018a)

   matlab  
   #if your default matlab is a different version:   
   /opt/matlab/R2018a/bin/matlab

Note: Other MATLAB might have issues with writing the files at the end of the process

Step 2: add the modified VoxelStats package to your MATLAB path:

   >> addpath(genpath('/data/data02/brandon/bin/VoxelStats'))

**Step 3: input your data file. **
MATLAB uses Excel format. Have .xlsx sheet with your data that you wish to analyze.
NOTE: it must have no blanks in ANY variable that you wish to use.
To tell MATLAB that this .xlsx file is what you'd like to use for the data table:

   >> data_file = '/data/data02/tevy/try/voxelwise_test_2025_02_19_lumipulse/validation_1_voxelwise.xlsx'; mainDataTable = readtable(data_file);

2. Preparing models

First, define your model with image type, the variables and role in your model (same as the lm() function in R), in addition to specifying which variables are images and which are categorical.

Note: You should use a mask that corresponds to the area you're interested in, such as:

  • Grey matter: /data/data05/masks/miscellaneous/whole_cortex_cer_and_basal_ganglia_stuart.mnc
  • Cortex only: /data/data05/masks/miscellaneous/whole_cortex_only_stuart.mnc
  • Whole brain (no CSF): /data/data05/masks/miscellaneous/mni_adni_TissPrior_GM_WM_bin05_dilated_manual_fix.mnc

Note: The “multivalueVariables” input should include all of the images in your model.
Note: The “categoricalVars” input should include all of the categorical variables in your model. There is no special command for specifying continuous variables.

Example:

>> imageType = 'minc';  
>> stringModel = 'nav_adni_suvr_fullcg ~ plasma_ptau217_lumipulse + mk_adni_suvr_infcg + age + sex';  
>> mask_file = '/data/data02/brandon/Templates/mni_adni/mni_adni.mnc';   
>> multivalueVariables = {'nav_adni_suvr_fullcg', 'mk_adni_suvr_infcg'};  
>> categoricalVars = {'sex'};

Next, simply copy and paste this; do not modify. Adds a "passed QC==TRUE" value to each row, necessary for processing.

>> qc4table = array2table(ones(size(mainDataTable,1),1));  
>> %qc4table = array2table(num2str(ones(size(mainDataTable,1),1)));  
>> qc4table.Properties.VariableNames = {'QC'};  
>> mainDataTable_full = [mainDataTable qc4table];

Run the model and save the resulting MATLAB environment

Note: the larger the mask, the longer this will take. For a full head, expect 2.5+ hours. For grey matter ribbon, expect ~20 minutes.

>> [ c_struct, slices_p, image_height_p, image_width_p, coeff_vars, voxel_num, df, voxel_dims] = …
>> VoxelStatsLM( imageType, stringModel, mainDataTable_full, mask_file, multivalueVariables, categoricalVars, ‘mdt.QC==1’);  
    save(‘/data/data02/tevy/try/voxelstat_nav_plasma217_cor_mk_0220/voxelstat_nav_217_cor_mk.mat’);

3. Adjusting and saving the results

First, perform the multiple comparisons correction to obtain adjusted t-values
Note: In creating the corrected_stats_mat file, you will need to select the predictor of interest to name in the VoxelStatsDoRFT function. Here, we are using the predictor “plasma_ptau217_lumipulse”.

>> image_dims = [slices_p image_height_p image_width_p];
>> search_vol = voxel_num*1;
>> fwhm = 8;
>> pfdr = 0.05;
>> clus_th = 0.001;	
>> corrected_stats_mat = VoxelStatsDoRFT( c_struct.tValues.plasma_ptau217_lumipulse, image_dims, search_vol, voxel_num, fwhm, df, pfdr, clus_th);

Finally, write the results to a NifTI image (The write MINC function is broken) Note: you will need to repeat steps 7 and 8 for each predictor of interest for which you’d like to make a corrected t-value map.
Note: the directory in which you wish to save the t-value map needs to be created beforehand.
Note: the final input is the mask file that you used to create the model, back in step 4.

>> VoxelStatsWriteNifti(corrected_stats_mat, '/data/data02/tevy/try/voxelstat_nav_plasma217_cor_mk_0220/voxelstat_nav_217_cor_mk.nii',  
    '/data/data02/brandon/Templates/mni_adni/mni_adni.nii')

Clone this wiki locally