This tutorial explains how to register functional MRI data to a participant's T1-weighted anatomical image and then to an MNI template. Each step introduces the required inputs, the command to run, its outputs, and how to inspect the result.
We use FSL's boundary-based EPI registration and ANTs' nonlinear anatomical registration. This tutorial presents one workflow combining the two tools. Processing runs from a Linux terminal; visual inspection uses FSLeyes in a graphical desktop session.
My earlier article, Installing FSL and FIX on Linux, covers the FSL setup. ANTs must also be installed and available on your PATH; see the ANTs installation guide.
Scope: The examples follow the linked official documentation and use generic filenames. These exact commands have not been validated end to end on an imaging dataset. This tutorial starts with prepared inputs; it does not cover a complete fMRI preprocessing pipeline.
1. Understand the three spaces
| Space | Image used here | Role |
|---|---|---|
| Functional EPI space | Mean of a motion-corrected BOLD run | Reference for the functional data |
| Individual anatomical space | The same participant's T1w image | Anatomical reference for EPI registration |
| Standard space | FSL's MNI152 T1 2 mm template | Destination for spatial normalization |
There are two separate tasks:
- Estimate a transformation: determine the spatial relationship between images.
- Apply a transformation: resample an image using that relationship and a chosen output grid.
We estimate EPI-to-T1w registration with FSL and T1w-to-MNI registration with ANTs. We then apply the transformations to the BOLD time series in two stages.
The two-stage example makes each transformation explicit, at the cost of an additional resampling step. For a production workflow, compatible transformations can be composed to resample the BOLD data once. Intermediate registration checks can still use 3D reference images; they do not require resampling the full time series twice.
2. Prepare the inputs
Use a separate working directory containing these files:
| File | Required contents |
|---|---|
bold_preproc.nii.gz |
A 4D BOLD run, motion-corrected to a common EPI reference, still in functional space, and retaining anatomical contrast in its temporal mean |
T1w.nii.gz |
The participant's whole-head T1w image |
Any susceptibility-distortion correction required by your acquisition should already be applied consistently to the BOLD data used here. This article does not cover motion correction, distortion correction, or ICA denoising. Registration does not replace these steps.
Use an anatomical image with adequate tissue contrast, and address substantial intensity bias before registration. The next subsection creates and checks the brain-extracted T1w image needed for registration.
Run the following blocks in the same Bash session, from that working directory:
export FSLOUTPUTTYPE=NIFTI_GZ
mkdir -p registration
MNI_BRAIN="$FSLDIR/data/standard/MNI152_T1_2mm_brain.nii.gz"
MNI_HEAD="$FSLDIR/data/standard/MNI152_T1_2mm.nii.gz"
check_registration_inputs() {
local image
local missing=0
for image in bold_preproc.nii.gz T1w.nii.gz \
"$MNI_BRAIN" "$MNI_HEAD"; do
if [ ! -r "$image" ]; then
printf 'ERROR: Cannot read %s\n' "$image" >&2
missing=1
fi
done
return "$missing"
}
check_registration_inputs
cat "$FSLDIR/etc/fslversion"
antsRegistration --version
fslhd bold_preproc.nii.gz
fslhd T1w.nii.gz
If an ERROR message appears, resolve it before proceeding; subsequent commands do not stop automatically. Also resolve any missing commands. Record the software versions and the exact template used. “MNI space” alone is not a sufficiently specific template description for reproducible work.
Extract the T1w brain with BET
If you already have a suitable brain-extracted T1w image that has been visually inspected, use it and skip the BET command below. The subsequent commands refer to this image as T1w_brain.nii.gz; adjust the path if your existing file has a different name.
Otherwise, create a brain-extracted image from the whole-head T1w image:
bet T1w.nii.gz T1w_brain.nii.gz -m
fsleyes T1w.nii.gz T1w_brain.nii.gz
BET writes T1w_brain.nii.gz; -m additionally writes the binary mask T1w_brain_mask.nii.gz. The mask is available for inspection but is not an input to the commands below.
Adjust overlay opacity and inspect all three planes. Check that cortex and cerebellum are retained and that non-brain tissue around the skull and orbits is excluded. The brain-extracted image must retain the voxel grid and spatial mapping of T1w.nii.gz.
This example uses BET's default fractional intensity threshold (-f 0.5). If brain tissue is excluded, a lower -f value may help; if too much non-brain tissue remains, a higher value may help. Inspect the result before changing the threshold, and check the extraction after each adjustment. No single threshold is appropriate for all images. See the BET documentation.
Continue only after BET completes successfully and the extraction is acceptable. Brain extraction removes non-brain tissue; it does not estimate the EPI-to-T1w registration.
Create the EPI reference
Create an EPI reference from a BOLD run whose temporal mean retains anatomical contrast. Do not use voxelwise demeaned, temporally standardized, or residual data with a near-zero mean for this step:
fslmaths bold_preproc.nii.gz -Tmean registration/epi_ref.nii.gz
A temporal mean of the transformed BOLD series is also used for the final visual check.
Using the mean keeps the reference tied to the time series being transformed. A suitable SBRef is another option, but it must correspond spatially to the processed BOLD run; sharing a participant identifier is not enough.
The header and arithmetic utilities used here are documented in the FSL utilities guide.
3. Register EPI to T1w
FSL's epi_reg uses the white-matter boundary of the anatomical image to help align EPI with T1w. It requires sufficient tissue contrast in the EPI image and a T1w image from which a usable white-matter boundary can be obtained. The script can generate the required white-matter segmentation; a separately prepared segmentation is not mandatory. See the official epi_reg documentation.
epi_reg \
--epi=registration/epi_ref.nii.gz \
--t1=T1w.nii.gz \
--t1brain=T1w_brain.nii.gz \
--out=registration/epi_to_T1w
--out is a basename, without .nii.gz. The main outputs used below are:
-
registration/epi_to_T1w.nii.gz: the EPI reference resampled into T1w space. -
registration/epi_to_T1w.mat: the FSL transformation matrix.
This example does not supply fieldmaps to epi_reg; it does not perform fieldmap-based distortion correction.
Inspect the result before applying the matrix to the full run:
fsleyes T1w.nii.gz registration/epi_to_T1w.nii.gz
Adjust the overlay opacity and inspect axial, coronal, and sagittal slices. Look for consistent alignment of the brain outline and internal structures. Consider EPI coverage and signal dropout when interpreting differences; a dark region is not automatically a registration error.
4. Register T1w to the MNI template
Use the brain-extracted T1w image as the moving image and the brain-extracted template as the fixed image:
antsRegistrationSyNQuick.sh \
-d 3 \
-f "$MNI_BRAIN" \
-m T1w_brain.nii.gz \
-o registration/T1w_to_MNI_ \
-t s
The ANTs script defines -t s as rigid, affine, and deformable SyN stages. Here, -d 3 specifies a three-dimensional registration.
| Option | Role in this workflow |
|---|---|
-f in antsRegistrationSyNQuick.sh
|
Fixed image: the MNI template |
-m in antsRegistrationSyNQuick.sh
|
Moving image: the participant's T1w brain |
-r in antsApplyTransforms (Section 5) |
Reference image defining the output grid |
These option meanings are command-specific: BET's -m, for example, requests a mask.
The relevant outputs are:
| Output | Purpose |
|---|---|
T1w_to_MNI_0GenericAffine.mat |
Combined linear transformation |
T1w_to_MNI_1Warp.nii.gz |
Forward nonlinear displacement field |
T1w_to_MNI_Warped.nii.gz |
Moving T1w brain image resampled into template space |
These files are under registration/. Check the warped anatomy:
fsleyes "$MNI_BRAIN" registration/T1w_to_MNI_Warped.nii.gz
Inspect the cortex, ventricles, and cerebellum across multiple slices. Treat this configuration as a starting point and assess registration quality for your dataset.
5. Apply the transformations to the BOLD time series
Apply the estimated transformations in the following order.
EPI space to T1w space
Apply the same EPI-to-T1w matrix to every volume:
applyxfm4D \
bold_preproc.nii.gz \
T1w.nii.gz \
registration/bold_in_T1w.nii.gz \
registration/epi_to_T1w.mat \
-singlematrix
-singlematrix selects one matrix for the entire run. This assumes the volumes have already been motion-corrected into the reference space; it does not estimate or correct motion between volumes. The argument order is input, reference, output, matrix, then options (FSL wrapper source).
T1w.nii.gz sets the intermediate output grid. This can create a large file when the anatomical resolution is finer than the functional resolution. Resampling to a finer grid does not increase the spatial detail acquired in the original BOLD data.
The FLIRT user guide documents applyxfm4D and its default sinc interpolation. Check your installed command's help before changing interpolation options.
T1w space to MNI space
Apply the ANTs transformations to that intermediate time series:
antsApplyTransforms \
-d 3 \
-e 3 \
-i registration/bold_in_T1w.nii.gz \
-r "$MNI_HEAD" \
-o registration/bold_in_MNI.nii.gz \
-n Linear \
-t registration/T1w_to_MNI_1Warp.nii.gz \
-t registration/T1w_to_MNI_0GenericAffine.mat
-d 3 describes the spatial transformation, while -e 3 identifies the input as a time series. A 4D BOLD file does not require a four-dimensional spatial registration. The reference is a 3D image defining the output grid (ANTs dimensionality guide).
For this forward image transformation, list the nonlinear warp before the affine. ANTs uses a transform stack: the last-listed transform acts first. See the ANTs transform guide.
The full-head template supplies the output grid here; registration was estimated using the corresponding brain-extracted template. This relies on the two templates having matching geometry.
The FSL matrix is used only by FSL in the first step. Do not pass epi_to_T1w.mat directly to ANTs: FSL and ANTs transform representations are not interchangeable merely because both files end in .mat. Combining the stages requires an explicit, validated conversion with the correct source and reference images.
6. Check the final output
First compare the volume count and temporal spacing:
fslval bold_preproc.nii.gz dim4
fslval registration/bold_in_MNI.nii.gz dim4
fslval bold_preproc.nii.gz pixdim4
fslval registration/bold_in_MNI.nii.gz pixdim4
fslhd registration/bold_in_MNI.nii.gz
fslhd "$MNI_HEAD"
Use the header output to check the following fields:
| Fields | What to check |
|---|---|
dim1–dim3, pixdim1–pixdim3
|
Spatial dimensions and voxel sizes agree with the chosen output reference |
qform/sform codes and matrices (qto_xyz / sto_xyz in fslhd) |
The voxel-to-world mapping is consistent with the intended reference; investigate conflicting valid mappings |
dim4 |
The output retains the input number of time points |
pixdim4, time_units
|
The TR and its units are preserved |
Matching array dimensions alone does not establish that the output occupies the correct space. Header checks also do not replace visual inspection.
Then inspect the temporal mean in standard space:
fslmaths registration/bold_in_MNI.nii.gz \
-Tmean registration/mean_bold_in_MNI.nii.gz
fsleyes "$MNI_HEAD" registration/mean_bold_in_MNI.nii.gz
Before using the result downstream, confirm that:
- EPI aligns with the participant's T1w image.
- The warped T1w image aligns with the chosen template.
- Final BOLD coverage is plausible and no unexpected clipping or gross displacement appears.
- The time axis is preserved.
- The exact input files, software versions, commands, and template are recorded.
If the final overlay looks wrong, return to the two intermediate overlays. A good T1w-to-MNI result cannot compensate for an incorrect EPI-to-T1w registration. Likewise, a correct spatial grid does not prove anatomical alignment.
This workflow leaves both transformations and intermediate images available for inspection. That makes each stage understandable and gives you a clear place to investigate when the final result does not look right.
AI disclosure: An LLM was used to help draft, organize, and edit the English text and command examples. I remain responsible for the article's technical accuracy.


Top comments (0)