DEV Community

Cover image for A Step-by-Step Guide to fMRI Registration with FSL and ANTs
Haruki Niwa
Haruki Niwa

Posted on Edited on AI-assisted

A Step-by-Step Guide to fMRI Registration with FSL and ANTs

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.

Flat illustration representing EPI, individual T1w, and MNI template spaces.

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

--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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

-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
Enter fullscreen mode Exit fullscreen mode

-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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Flat illustration of a monitor and magnifying glass representing visual inspection of image alignment.

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)