BrainSuite Statistics Toolbox

Overview

The BrainSuite Statistics toolbox allows the application of advanced statistical models to volumetric image, cortical surface and sulcal curve based outputs generated from BrainSuite. This enables population or group analysis of cortical or sulcal morphology. Some features of the toolbox are:

  • a python interface for manipulating morphological data using R through Rpy2
  • a python interface for using statsmodels with pandas for a pure python implementation
  • (coming soon) ability to plot graphs, charts and visualizations on surfaces

Available statistical models/tests are:

  • Pearson correlation
  • General linear model
  • ANOVA test
  • Paired sample t-test

Installation

Mac/Linux
Ensure Python is installed on the system. On the terminal, type pip install bss .

Windows
Ensure Python, scipy and numpy are installed on the system.
An easier way to install scipy, numpy and all the dependencies is to install Miniconda Python.
On the terminal, type pip install bss.

To upgrade, simply type pip install bss --upgrade.

For more information about running BSS please refer here.

Usage

Tensor Based Morphometry

This is a statistical analysis of Jacobian determinants for a population What do you need to do first?

    1. Make sure that svreg is executed on your imaging data and that the output directories for each subject exist and are writable.If you did not complete SVReg, please go here for instructions on how to complete this step.
    2. Create a demographics csv file that specifies the subject IDs, other demographic variables such as gender, age, diagnosis etc… Click here for a sample csv file. Normally all population studies will have a demographics/study variable spreadsheet that contains the covariates and factors of interest for each row-wise subject.
    3. On the command line run
      <path to bss installation>/bin/bss_prepare_data_for_tbm.py master_subj_dir demographics_csv modelspec [-sigma] smoothing_kernel_(mm)
Usage
Inputs/Options Description Example
master_subj_dir Path to the directory containing the subject’s SVReg output files and directories On Mac: /Users/Sally/Study1/Subject_001 On Windows: C:\Users\Sally\Study1\Subject_001
demographics_csv Name of CSV file that contains a column of subject IDs, whose header MUST be labeled subjID subject_demographics.csv
modelspec Name of output modelspec.ini text file (which will be generated by this script) modelspec_cbm.ini
[-sigma] Smoothing kernel value (if this option is not called, default: 0) -sigma 2.5

Example command line for Mac:

/Applications/BSS/bin/bss_prepare_data_for_tbm.py /Users/Sally/Study1/Subject_001 subject_demographics.csv modelspec_tbm.ini -sigma 2.5

The script will add a new column called File to demographics_csv. The modelspec.ini text file contains the information about the subjects and the statistical model.The script creates a skeleton modelspec.ini that you can edit to specify/modify additional parameters. Click here for a sample modelspec.ini file.

What do you need to do next?

Edit the modelspec.ini to specify your model. The following two examples show how the statistical analysis can be performed.

Example 1: Perform ANOVA to determine the main effect of Age on the Jacobian determinants when controlling for Sex.
If you want to find the main effect of Age controlling for sex, you can specify the model as

[model] modeltype=glm fullmodel=Age + Sex nullmodel=Sex test=anova

as shown in the picture.

modelspec_modelinfo

Example 2: Determine the Correlation between Age and Jacobian determinants

If you want to find the Pearson correlation of Age with the Jacobian determinants, you can create a new section called [measure] and specify the analysis as

[measure] coeff=corr variable=Age

as shown in the picture.

modelspec_modelinfo_corr

Important!! The modelspec.ini can only contain either the [model] or the [measure] section but not both. Final Step — Running TBM statistics Just run

<path to bss installation>/bin/bss_run.py <modelspec.ini> <output_directory>

Output files If you run both anova and correlations separately as shown above, bss_run.py will create the following files.

Example Volume Files
Filename Description
anova_Age_mri.bfc.nii_atlas_log_pvalues.nii.gz Logarithmic (-log10(p)) p-values denoting the significance of main effect Age
anova_Age_mri.bfc.nii_atlas_log_pvalues_adjusted.nii.gz FDR thresholded logarithmic p-values denoting the significance of Age
corr_Age_mri.bfc.nii_atlas_log_pvalues.nii.gz Logarithmic p-values denoting the significance of correlation with Age
corr_Age_mri.bfc.nii_atlas_log_pvalues_adjusted.nii.gz FDR thresholded logarithmic p-values for significance of correlation with Age
corr_Age_mri.bfc.nii_corr.nii.gz Pearson correlation coefficients for Age
corr_Age_mri.bfc.nii_atlas_log_pvalues_adjusted.nii.gz FDR thresholded Pearson correlation coefficients for Age
Example Color look up tables (LUT)
Filename Description
anova_Age_mri.bfc.nii_atlas_log_pvalues.lut Logarithmic colormap for p-values denoting the significance of main effect Age
anova_Age_mri.bfc.nii_atlas_log_pvalues_adjusted.lut Logarithmic colormap for FDR adjusted p-values for main effect Age
corr_Age_mri.bfc.nii_atlas_log_pvalues.lut Logarithmic colormap for p-values for the significance of correlation with Age
corr_Age_mri.bfc.nii_corrvalues_adjusted.lut Logarithmic colormap for FDR adjusted p-values for the significance of correlation with Age
corr_Age_mri.bfc.nii_corrvalues.lut Colormap for Pearson correlation coefficients for Age
corr_Age_mri.bfc.nii_corrvalues_adjusted.lut Colormap for FDR thresholded Pearson correlation coefficients for Age

Visualizing outputs To visualize the significant main effects or correlations, open Brainsuite, load the atlas mri.bfc.nii.gz located in your Svreg installation directory and load the above output files as overlays. To display the color, drag and drop the color look up table files (.lut) in BrainSuite and right click on the overlay color bar in the Image Display tab and select the colormap lut. Important!! For visualizing p-values, please make the bottom and the top values of the colormap the same as the value. For e.g., after loading the *.log_pvalues.lut, if you see -5.346 at the bottom, and 2.345 at the top, you should leave the bottom value as it is, and make the top value +5.346.

Cortical Based Morphometry

This is a statistical analysis of Jacobian determinants for a population

What do you need to do first?

    1. Make sure that SVReg is executed on your imaging data and that the output directories for each subject exist and are writable.If you did not complete SVReg, please go here for instructions on how to complete this step.
    2. Create a demographics csv file that specifies the subject IDs, other demographic variables such as gender, age, diagnosis etc… Click here for a sample csv file. Normally all population studies will have a demographics/study variable spreadsheet that contains the covariates and factors of interest for each row-wise subject.
    3. On the command line run
      <path to bss installation>/bin/bss_prepare_data_for_cbm.py master_subj_dir demographics_csv modelspec {left,right} [-sigma] smoothing_kernel_(mm)
Usage
Inputs/Options Description Example
master_subj_dir Path to the directory containing the subject’s SVReg output files and directories On Mac: /Users/Sally/Study1/Subject_001 On Windows: C:\Users\Sally\Study1\Subject_001
demographics_csv Name of CSV file that contains a column of subject IDs, whose header MUST be labeled subjID subject_demographics.csv
modelspec Name of output modelspec.ini text file (which will be generated by this script) modelspec_cbm.ini
{left,right} Indicate which hemisphere you would like to analyze left
[-sigma] Smoothing kernel value (if this option is not called, default: 0) -sigma 2.5

Example command line for Mac:

/Applications/BSS/bin/bss_prepare_data_for_cbm.py /Users/Sally/Study1/Subject_001 subject_demographics.csv modelspec_cbm.ini left -sigma 2.5

The script will add a new column called File to demographics_csv. The modelspec.ini text file contains the information about the subjects and the statistical model.The script creates a skeleton modelspec.ini that you can edit to specify/modify additional parameters. Click here for a sample modelspec.ini file.

What do you need to do next?

Edit the modelspec.ini to specify your model. The following two examples show how the statistical analysis can be performed.

Example 1: Perform ANOVA to determine the main effect of Age on the Jacobian determinants when controlling for Sex.

If you want to find the main effect of Age controlling for sex, you can specify the model as

[model] modeltype=glm fullmodel=Age + Sex nullmodel=Sex test=anova

as shown in the picture.

modelspec_modelinfo

Example 2: Determine the Correlation between Age and Jacobian determinants

If you want to find the Pearson correlation of Age with the Jacobian determinants, you can create a new section called [measure] and specify the analysis as

[measure] coeff=corr variable=Age

as shown in the picture.

modelspec_modelinfo_corr

Important!! The modelspec.ini can only contain either the [model] or the [measure] section but not both. Final Step — Running CBM statistics

Just run

<path to bss installation>/bin/bss_run.py <modelspec.ini> <output_directory>

Output files If you run both anova and correlations separately as shown above, bss_run.py will create the following files.

Example Surface Files
Filename Description
anova_Age_mri.left.mid.cortex_atlas_log_pvalues.dfs Logarithmic (-log10(p)) p-values denoting the significance of main effect Age on the left hemisphere
anova_Age_mri.left.mid.cortex_atlas_log_pvalues_adjusted.dfs FDR thresholded logarithmic p-values denoting the significance of Age on the left hemisphere
corr_Age_mri.left.mid.cortex_atlas_log_pvalues.dfs Logarithmic p-values denoting the significance of correlation with Age on the left hemisphere
corr_Age_mri.left.mid.cortex_atlas_log_pvalues_adjusted.dfs FDR thresholded logarithmic p-values for significance of correlation with Age on the left hemisphere
corr_Age_mri.left.mid.cortex_corr.dfs Pearson correlation coefficients for Age on the left hemisphere
corr_Age_mri.left.mid.cortex_corr_adjusted.dfs FDR thresholded Pearson correlation coefficients for Age on the left hemisphere
Example Text Files
Filename Description
anova_Age_mri.left.mid.cortex_unadjusted_pvalue_range.txt Logarithmic (-log10(p)) p-value range denoting the significance of main effect Age on the left hemisphere
anova_Age_mri.left.mid.cortex_adjusted_pvalue_range.txt FDR thresholded logarithmic p-value range denoting the significance of Age on the left hemisphere
corr_Age_mri.left.mid.cortex_unadjusted_pvalue_range.txt Logarithmic p-value range denoting the significance of correlation with Age on the left hemisphere
corr_Age_mri.left.mid.cortex_adjusted_pvalue_range.txt FDR thresholded logarithmic p-value range for significance of correlation with Age on the left hemisphere
corr_Age_mri.left.mid.cortex_corr_range.txt Pearson correlation coefficient range for Age on the left hemisphere
corr_Age_mri.left.mid.cortex_adjusted_corr_range.txt FDR thresholded Pearson correlation coefficient range for Age on the left hemisphere

Visualizing outputs To visualize the significant main effects or correlations, open BrainSuite, load the output surface files onto BrainSuite (File > Open > Surface) or drag and drop the surface files anywhere on the BrainSuite window.

ROI-Based Analysis

This is a statistical analysis of Cortical ROIs What do you need to do first?

    1. Make sure that SVReg is executed on your imaging data and that the output directories for each subject exist and are writable.If you did not complete SVReg, please go here for instructions on how to complete this step.
    2. Create a demographics csv file that specifies the subject IDs, other demographic variables such as gender, age, diagnosis etc… Click here for a sample csv file. Normally all population studies will have a demographics/study variable spreadsheet that contains the covariates and factors of interest for each row-wise subject.
    3. On the command line run
      <path to bss installation>/bin/bss_prepare_data_for_roi.py master_subj_dir demographics_csv modelspec roi_measure roii_id
Usage
Inputs/Options Description Example
master_subj_dir Path to the directory containing the subject’s SVReg output files and directories On Mac: /Users/Sally/Study1/Subject_001 On Windows: C:\Users\Sally\Study1\Subject_001
demographics_csv Name of CSV file that contains a column of subject IDs, whose header MUST be labeled subjID subject_demographics.csv
modelspec Name of output modelspec.ini text file (which will be generated by this script) modelspec_roi.ini
roi_measure Indicate which ROI you would like to analyze (gmthickness, gmvolume, area) gmthickness
roii_id ID number that corresponds to the a certain ROI (as listed here) 500,501

Example command line for Mac:

/Applications/BSS/bin/bss_prepare_data_for_roi.py /Users/Sally/Study1/Subject_001 subject_demographics.csv modelspec_roi.ini gmthickness 500,501

What do you need to do next?

Edit the modelspec.ini to specify your model. Then, just run:

<path to bss installation>/bin/bss_run.py <modelspec.ini> <output_directory>

Output Files

Filename Description
results.txt Result of ROI analysis in a text format
report.R Result of ROI analysis in an R-compatible script (which can be executed in R)
roidata.csv A copy of demographics csv file with the added columns of ROIs

Visualizing outputs Go to the output directory for ROI analysis (which was generated in the step above) and open results.txt to inspect or execute report.R in R.

Longitudinal Analysis

This section will show how you can perform a paired sample t-test using any of the three analyses from the above section. What do you need to do first?

      1. Make sure that SVReg is executed on your imaging data and that the output directories for each subject exist and are writable.If you did not complete SVReg, please go here for instructions on how to complete this step.
      2. Important!! Create a demographics csv file that only contains subject information of TWO time points. The csv should consist of columns of subject IDs, indices that indicate the group that the subjects belong to, and time points. Click here for a sample csv file.
      3. Follow step number 3 under “What do you need to do first?” section of your specific analysis (Tensor Based Morphometry, Cortical Based Morphometry). Return back to this section after the completion of this step.

What do you need to do next? Edit the modelspec.ini file to specify your model. The following is an example modelspec.ini file that is compatible with this csv file.

This is a section of an example modelspec file for paired sample t-test for tbm analysis (if you are using Cortical Based Morphometry, replace “tbm” with “cbm” under [analysis] in your modelspec.ini file)

 

[analysis] type=tbm

[hypothesis]

group=caseID pair=timepoint test=paired_ttest

Please click here for an example of a full modelspec file.

Final step! Just run

<path to bss installation>/bin/bss_run.py <modelspec.ini> <output_directory>

You can go to the “Output files” and/or “Visualizing outputs” sections of your specific analysis to understand and view the results.

If you would like more help getting started, please go to this page for tutorials on BSS. We provide instructive information on running correlation and ANOVA tests on TBM, CBM, and ROI-based analyses.