In this practical, you will discover how to use whim to run fixel-based analysis, including creating a fixel template, extracting fibre-specific information from diffusion MRI, and running group-level comparisons.
A fixel represents an individual fibre population within a voxel, allowing for the resolution of crossing fibres. Fixel-based analysis (FBA) models these fibre populations separately to extract fibre-specific metrics, enabling more precise and anatomically informed comparisons across subjects.
WHIM constructs a fixel template using a discrete fibre orientation distribution model that explicitly defines fixels. This template serves as a prior for estimating subject-level fibre orientations and extracting fixel-specific metrics such as signal fractions or diffusivities. Because fixels are consistently defined across subjects, WHIM enables robust statistical comparisons of microstructural properties related to ageing, disease, or other group-level factors in diffusion MRI.
To run whim for a study, you will need the following:
topup and eddy).input.tree) that specifies the file structure and template keys for each subjectThe fixel template is a probabilistic representation of white matter fibre architecture across subjects in a common space. For each voxel, it defines the number of fixels (distinct fibre populations), their average orientations (dyads), and the variance of these orientations across subjects. This structure ensures fibre-specific consistency and comparability across individuals.
The fixel template is stored in the template directory, which contains the following files:
n_fibres.nii.gz: Number of fixels per voxeldyads_i_mean.nii.gz / dyads_i_var.nii.gz: Orientation priors per fibref_i_mean.nii.gz / f_i_var.nii.gz: Signal fraction priors per fibretemplate_mask.nii.gz: Brain mask in template space
To visualise the fixel template, use the following fsleyes command:
fsleyes "$FSLDIR/data/omm/Oxford-MM-1/OMM-1_T1_brain.nii.gz" \
"template/f_1_mean.nii.gz" --disabled \
"template/dyads_1_mean.nii.gz" --overlayType linevector --lineWidth 2 \
--clipImage template/f_1_mean.nii.gz --clippingRange 0.001 1 \
"template/f_2_mean.nii.gz" --disabled \
"template/dyads_2_mean.nii.gz" --overlayType linevector --lineWidth 2 \
--clipImage template/f_2_mean.nii.gz --clippingRange 0.001 1 \
"template/f_3_mean.nii.gz" --disabled \
"template/dyads_3_mean.nii.gz" --overlayType linevector --lineWidth 2 \
--clipImage template/f_3_mean.nii.gz --clippingRange 0.001 1
This command renders fibre orientation lines (dyads) in each voxel, thresholded by their corresponding signal fractions (f_i_mean). Use axial, sagittal, and coronal views to explore major fibre crossings across the brain.
💡 Hint: Look around the centrum semiovale or near where the corpus callosum intersects with the corticospinal tracts. These areas often exhibit clear fibre crossings.
Once a fixel template is created (or an existing one is used), the next step involves extracting fibre-specific microstructural features for each subject. These features are aligned to the fixel template, ensuring spatial and structural consistency across subjects for meaningful comparisons.
WHIM performs this extraction using the whim metrics command.
It fits a biophysical model to the subject's diffusion MRI data, using the fixel template to provide prior information about fibre orientations.
You can automate metric extraction across all subjects using a Bash for loop.
For example, if your subject folders are named ./data/001, ./data/002, etc., you can run:
for subj in ./data/*; do id=$(basename "$subj") whim metrics --template ./template \ --data $subj/diffusion/data.nii.gz \ --bvals $subj/diffusion/bvals \ --bvecs $subj/diffusion/bvecs \ --xfm $subj/xfms/mmorf_diff2OMM.nii.gz \ --mask slice_mask_2mm.nii.gz \ --output fixels/$id done
To extract fixel-specific metrics for a single subject, run:
whim metrics --template ./template \
--data ./data/001/diffusion/data.nii.gz \
--bvals ./data/001/diffusion/bvals \
--bvecs ./data/001/diffusion/bvecs \
--xfm ./data/001/xfms/mmorf_diff2OMM.nii.gz \
--mask slice_mask_2mm.nii.gz \
--output fixels/001
Arguments:
--template: Path to the fixel template containing prior means and variances for each parameter.--data, --bvals, --bvecs: The subject's diffusion-weighted data and acquisition protocol.--xfm: Transformation from subject space to template space.--mask: Brain mask in template space defining the region for model fitting.--output: Directory where fixel-specific parameter estimates will be saved.
This command produces a set of parameter maps (e.g. f_1_std.nii.gz, d_perp_1_std.nii.gz) in template space, each corresponding to a specific fixel.
The whim metrics command produces a set of fixel-wise parameter maps that characterise the white matter microstructure in each subject.
The most important outputs include
f_i_std.nii.gz: Signal fraction of each fibre population in standard space.d_per_i_std.nii.gz: Perpendicular diffusivity, sensitive to microstructural integrity (e.g. demyelination).dyads_i_std.nii.gz: Orientation (unit vector) of each fixel in standard space.*_native.nii.gz: Same parameters as above, but in subject's native space.
You can visualise the output of whim metrics for a single subject using FSLeyes.
The following command overlays the estimated fibre orientations (dyads_i_std.nii.gz) as line vectors, modulated by their corresponding signal fractions (f_i_std.nii.gz):
fsleyes ./fixels/001/f_1_std.nii.gz --disabled \ ./fixels/001/dyads_1_std.nii.gz --overlayType linevector \ --modulateImage ./fixels/001/f_1_std.nii.gz --lineWidth 2.0 \ --modulateRange 0.0 0.3 --modulateMode alpha \ ./fixels/001/f_2_std.nii.gz --disabled \ ./fixels/001/dyads_2_std.nii.gz --overlayType linevector \ --modulateImage ./fixels/001/f_2_std.nii.gz --lineWidth 2.0 \ --modulateRange 0.0 0.3 --modulateMode alpha \ ./fixels/001/f_3_std.nii.gz --disabled \ $subj/dyads_3_std.nii.gz --overlayType linevector \ --modulateImage ./fixels/001/f_3_std.nii.gz --lineWidth 2.0 \ --modulateRange 0.0 0.3 --modulateMode alpha
This display allows you to examine the spatial distribution of fibre orientations and their relative strengths within each voxel. The line opacity is modulated by the signal fraction, so stronger fixels appear more prominently. This helps you inspect fibre crossings and confirm that the fixel estimates align well with white matter structures.
d_per_i_std.nii.gz) maps for each fibre using FSLeyes.
How do these values differ across the brain?
Bonus: Can you repeat the visualisation using the *_native.nii.gz outputs to see the results in the subject's native space? What changes do you notice?
Once fixel-specific metrics have been extracted for all subjects, you can perform group-level statistical analysis using the whim glm command.
This step tests for differences in fixel metrics (e.g., signal fractions, diffusivities) between groups, using the General Linear Model (GLM) framework.
WHIM's GLM implementation aligns closely with FSL-style design, where you provide a matrix of explanatory variables (EVs), a set of contrast vectors, and a mask defining where to analyse.
To run a GLM on the fixel features of all subjects, use:
whim glm --subjectdirs fixels/001 fixels/002 fixels/003 fixels/004 fixels/005 fixels/006 \
--des design.mat \
--con design.con \
--mask slice_mask_2mm.nii.gz \
--output stats
Arguments:
--subjectdirs: List of subject directories containing fixel parameter maps (e.g., f_1_std.nii.gz).--mask: Brain mask in template space specifying which voxels to include in the analysis.--des: CSV file with one row per subject and one column per explanatory variable (e.g., group, age).--con: Text file of contrast vectors to test specific hypotheses (e.g., group differences).--output: Directory where statistical outputs will be saved.WHIM will perform the GLM fit for each fixel metric separately and generate output files including:
<param>_cope.nii.gz: Contrast of parameter estimates<param>_zscore.nii.gz: Z-statistics for each contrast<param>_pe.nii.gz: Parameter estimates (betas)<param>_varcope.nii.gz: Variance of contrastsYou can visualise group differences using FSLeyes. For example, to view z-scores for the first contrast:
To visualise the results of the group-level GLM on fixel metrics, you can overlay each dyad orientation and colour it by the corresponding z-score using FSLeyes. The following shell loop iterates over each fibre (1 to 3), adds the dyad vectors, and colours them using the render3 colormap based on the statistical z-scores. It also clips the display using the signal fraction to only show meaningful fixels:
stats=./stats
template=./template
struct="$FSLDIR/data/omm/Oxford-MM-1/OMM-1_T1_brain.nii.gz" \
args="$struct"
for nf in 1 2 3; do
args="$args \
$stats/f_${nf}_zscore.nii.gz --disabled \
$template/f_${nf}_mean.nii.gz --disabled \
$template/dyads_${nf}_mean.nii.gz --overlayType linevector \
--cmap render3 --colourImage $stats/f_${nf}_zscore.nii.gz \
--clipImage $template/f_${nf}_mean.nii.gz --lineWidth 2.0 \
--colourRange -100.0 100.0 --clippingRange 0.001 1"
done
eval "fsleyes ${args}"
This will open FSLeyes with all visible fixels coloured according to their GLM z-scores, while suppressing low-signal regions to enhance visual clarity.
design.con and design.mat, refer to FSL's GLM documentation. In this case the desing.mat contains three columns, the bias term, dummie variable to indicate sex (1 and -1), and age of the subjects.
The contrast indicates to test for sex and keep age as a covariate.
f_1_zscore.nii.gz and how does it relate to your study hypothesis?
The first step in fixel-based analysis is to build a fixel template. This template defines the number of fixels in each voxel, the average fibre orientations, and the variance of those orientations across subjects.
WHIM uses a hierarchical modelling framework to estimate fibre-specific microstructural properties.
To simplify template construction, WHIM provides the whim EM command, which internally alternates between fitting individual subjects (whim subject) and updating the group-level priors (whim group) over several EM iterations.
For efficient data handling and parallel processing, WHIM leverages fsl-pipe and file-tree.
Instead of specifying individual file paths, you provide a single file-tree text file that describes where to find the necessary inputs (e.g. dMRI data, bvecs, bvals, transforms) for each subject.
fsl-pipe uses this structure to automatically generate and manage the required tasks, either submitting them to a compute cluster or running them locally in the correct order.
This process must be repeated for models with 1, 2, and 3 fibres per voxel. WHIM then applies voxel-wise model selection - typically using the BIC criterion - to determine the optimal number of fibres per voxel.
--xfm) can technically be derived from any modality, but we strongly advise using multimodal registration that includes diffusion data. T1-weighted images offer poor contrast in white matter, which can lead to misalignment of fibre structures if used alone. For optimal fixel correspondence across subjects, we recommend using a multimodal tool such as MMORF and registering to a multimodal template like the Oxford Multi-Modal Template (OMM-1) rather than the traditional MNI template.
To run the full EM fitting for a single fibre model, use:
whim EM --file-tree ../data/data.tree --mask slice_mask_2mm.nii.gz --nf 1 --iters 3 --output ./pes
Arguments:
--file-tree: A file-tree description of all subjects' file locations (including dMRI, bvecs, bvals, and xfm).--mask: Brain mask in the standard space.--nf: Number of fibres to fit in this run (1, 2, or 3).--iters: Number of EM iterations to perform.--output: Directory where intermediate and final outputs will be saved.input.tree
The input.tree file defines the layout of your dataset using file-tree syntax.
It tells WHIM and fsl-pipe where to find required input files for each subject, enabling automated and scalable processing.
In your setup, the data directory looks like this:
data
{subject}
diffusion
bvals (bvals)
bvecs (bvecs)
data.nii.gz(data)
nodif_brain_mask.nii.gz
xfms
T1.nii.gz
dti2mni_transf.nii.gz (diff2std)
WHIM expects that the input.tree file maps each required file (e.g., data, bvals, bvecs, diff2std) using the corresponding template keys defined with those exact names.
The actual folder structure can vary as long as the keys are correctly assigned.
After running this process separately for --nf 1, 2, and 3, we need to select the right number of fixels per voxel. This can be done by bayesian model selection.
You can create the final fixel template using:
whim select --modeldirs ./pes/iteration_3/group/bas1 \
./pes/iteration_3/group/bas2 \
./pes/iteration_3/group/bas3 \
--mask slice_mask_2mm.nii.gz \
--output ./study_template/
This command selects the best-fitting model per voxel and generates a complete fixel template containing:
n_fibres.nii.gz: Number of fibres per voxeldyads_i_mean.nii.gz / dyads_i_var.nii.gz: Orientation priors per fibref_i_mean.nii.gz / f_i_var.nii.gz: Signal fraction priors per fibrebedpostx. What aspects are shared, and what are fundamentally different?The End.