mrGrad is a MATLAB-based toolbox for analyzing spatial gradients within deep brain structures using MRI data.
It automatically computes principal anatomical axes within subcortical regions and quantifies MRI-derived microstructural profiles along those axes.
Developed for:
Mapping Microstructural Gradients of the Human Striatum in Normal Aging and Parkinson’s DiseaseDrori, Berman, and Mezer. Science Advances, 2022
An extended implementation for the midbrain (including additional region-specific code and example data) was later described in: Spatial profiles provide sensitive MRI measures of the midbrain micro- and macrostructureBerman, Drori, and Mezer. NeuroImage, 2022
The toolbox performs a full pipeline for regional gradient analysis in MRI data:
ROI Axis Extraction Derives principal axes of subcortical ROIs (e.g., caudate, putamen) using singular value decomposition (SVD) on voxel coordinates. Axes represent dominant anatomical directions (e.g., anterior–posterior, dorsal–ventral, medial–lateral).
ROI Segmentation Divides each ROI into bins along each axis. Supports segmentation methods:
equidistance— equal spatial spacing (default)equivolume— equal voxel volume per bin
Gradient Computation Samples voxel values from one or more MRI parameter maps (e.g., R1, MTsat, Water Fraction) along each axis. Computes per-segment statistics (mean or median). Supports multiple modalities per subject (v2.0 feature).
Group-Level Summary Aggregates across subjects, producing mean, standard deviation, and standard error of the mean (SEM) profiles. Outputs both MATLAB structs and CSV tables for flexible downstream analysis.
mrGrad expects a MATLAB struct Data with subject-level file paths and metadata:
| Field | Description |
|---|---|
seg_list | {N×1} cell array of segmentation or mask NIfTI files (one per subject) |
map_list | {N×M} cell array of coregistered MRI parameter maps (M parameters per subject) |
subject_ids(optional) | {N×1} subject identifiers (e.g., 'sub-001', 'sub-002') |
| Additional fields (optional) | e.g., Age, Group, Sex — retained in results |
Example:
Data.seg_list = {'sub1_seg.nii.gz'; 'sub2_seg.nii.gz'; 'sub3_seg.nii.gz'};
Data.map_list = {
'sub1_R1.nii.gz', 'sub1_MTsat.nii.gz';
'sub2_R1.nii.gz', 'sub2_MTsat.nii.gz';
'sub3_R1.nii.gz', 'sub3_MTsat.nii.gz'};
Data.subject_ids = {'sub-1'; 'sub-2'; 'sub-3'};| Parameter | Description |
|---|---|
'ROI' | Vector of label indices (e.g., [11, 12, 50, 51]) |
'roi_names' | ROI names corresponding to labels |
'Axes' or 'PC' | Anatomical ROI axes to analyze (default: [1 2 3]) |
'n_segments' | Number of bins per axis (default: 7) |
'segmenting_method' | 'equidistance' (default) or 'equivolume' |
'stat' | Statistic used per segment: 'median' (default) or 'mean' |
'parameter_names' | Names of MRI parameters (e.g., {'R1','MTsat'}) |
'units' | Units of each parameter (e.g., {'1/s','p.u.'}) |
'output_mode' | 'minimal', 'default', or 'extended' (see below) |
'Parallel' | Use MATLAB Parallel Toolbox (optional) |
mrGrad produces both MATLAB and file-based outputs, depending on the chosen output_mode:
Saves only summary statistics:
mrGrad_out.mat— compact summary struct (subject- and group-level gradient results)mrGrad_out.csv— combined summary table across all ROIs and subjects
No subject-level axes data or NIfTI outputs.
Saves:
mrGrad_out.mat— full results (including subject-level axes data)mrGrad_out.csv— summary table suitable for statistical analysis
Includes subject-level axes data in the MATLAB struct but does not save NIfTI masks.
Includes everything from default mode, plus:
- 3D NIfTI segmentation files per subject and ROI segment.
Each corresponds to one axis (e.g.,
sub-1/mrGradSeg_left-putamen_axis1.nii.gz).
- 3D NIfTI segmentation files per subject and ROI segment.
Each corresponds to one axis (e.g.,
Recommended for visual inspection and post-hoc analyses.
ExampleResults/
│
├── mrGrad_out.mat
├── mrGrad_out.csv
└── mrGradSeg/ (only in 'extended' mode)
├── sub-1/mrGradSeg_left-putamen_axis1.nii.gz
├── sub-1/mrGradSeg_left-putamen_axis2.nii.gz
└── ...
Each ROI result (RG.Left_Putamen, RG.Right_Caudate, etc.) contains:
Results: per-axis, per-parameter gradient profiles (subject- and group-levels)individual_data: per-subject axes data (if not minimal)user_input_fields: additional input metadata (e.g., age, group)
Run the included example:
mrGrad_runThis executes a full analysis for the bilateral caudate and putamen using multiple MRI parameters (R1, WaterFraction, MTsat).
Outputs will be saved to:
example_data/ExampleResults/
| Function | Description |
|---|---|
mrgrad_show_gradients | Plot individual and group-level gradient curves |
mrgrad_axis_visualize | Visualize ROI segmentations and axes in MRI space |
mrGrad_average_LR | Compute mean left–right ROI gradients |
mrGrad_subset | Select subsets of subjects |
mrGrad_asymmetry | Compute inter-hemispheric asymmetry indices |
Example:
mrgrad_show_gradients(RG,'error_name','SEM');
RG_avg = mrGrad_average_LR(RG);
mrgrad_show_gradients(RG_avg,'error_name','SEM');An extension code adapted for the midbrain, is available in:
workflows/MidBrainProfiles/
Run:
Calc_MB_profile_example_data.mRequired:
Recommended:
boundedline-pkgfor plotting bounded mean±error curves
- Support for multiple MRI parameters per subject
- Flexible output modes (
minimal,default,extended) - Enhanced visualization utilities and summary exports
If you use mrGrad toolbox or its underlying conceptual framework in your work, please cite:
Drori, Berman, and Mezer. Mapping Microstructural Gradients of the Human Striatum in Normal Aging and Parkinson’s Disease.Science Advances, 2022.
and, if using the midbrain extension:
Berman, Drori, and Mezer. Spatial profiles provide sensitive MRI measures of the midbrain micro- and macrostructure.NeuroImage, 2022.