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.
Change the directory to the whim folder:
cd ~/fsl_course_data/whim
The fixel template is stored in the template directory, you can see its contents by running:
ls template
Here is a brief description of the files in the template directory:
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.
In this practical, we use preprocessed diffusion MRI data from six young healthy subjects (3 female, 3 male, age 20-30). For each subject, the dataset includes the diffusion MRI scans and a transformation to the Oxford Multimodal Template (OMM) space, computed using MMORF.
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. We will use a pre-baked fixel template (but see the optional section at the end on how to create a template for your own study).
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.
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 or axon packing).dyads_i_std.nii.gz: Orientation (unit vector) of each fixel in standard space.d_a_std.nii.gz: Axial diffusivity, sensitive to axonal integrity and myelination.*_native.nii.gz: Same parameters as above, but in subject's native space.
The f_i_std.nii.gz images contain the signal fractions for each fibre population, while d_per_i_std.nii.gz provides the perpendicular diffusivity for each fibre. The dyads_i_std.nii.gz images represent the fibre orientations in standard space, which are crucial for visualising fixels and understanding their spatial distribution. Also, the d_a_std.nii.gz images provide the axial diffusivity, that is assumed to be the same across all fixels in a given voxel.
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 \ fixels/001/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.
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. In this practical, we use sex as the grouping variable and age as a covariate.
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. Open the design.mat and design.con files in a text editor to see the design matrix format.
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: Text 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 are 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 contrasts.You 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:
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.
f_1_zscore.nii.gz and how does it relate to your study hypothesis?n_fibres.nii.gz image, not in the z-score map.f_1_mean.nii.gz or similar, not the z-score maps.design.con and design.mat, refer to FSL's GLM documentation. In this case the design.mat contains three columns, the intercept term, a dummy variable to indicate sex (1 and -1), and age of the subjects.
The contrast indicates to test for sex differences.
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 along with Expectation-Maximization (EM) optimisation 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.
Peek inside the file-tree text file to see how it is organised:
cat data.tree
The advantage of using file-tree is that we don't have to worry about specifying the individual subjects files. We can simply pass on the text file and the location of the base directory where the data resides, then fsl-pipe uses this structure to automatically detect the files/subjects. It also generates and manages 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.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.
This command will create a directory structure under pes/iteration_"i"/group/bas1 containing the results of each iteration for the single fibre model.
The output includes:
dyads_i_mean.nii.gz / dyads_i_var.nii.gz: Mean and variance of fibre orientations (dyads)f_i_mean.nii.gz / f_i_var.nii.gz: Mean and variance of signal fractions for each fibre
After running this process separately for --nf 1, 2, and 3 (with using the same output directory), 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 fibre
You can visualise the resulting template using FSLeyes, similar to how you did for the pre-generated template.
The command is the same as before, just replace template with study_template.
bedpostx. What aspects are shared, and what are fundamentally different?bedpostx uses MCMC, but WHIM uses Expectation-Maximization (EM) for parameter estimation.bedpostx which estimates locally.bedpostx.The End.