Registration Practical

In this practical you will explore each of the registration steps within a standard two-step registration for functional images. We will first learn to use the registration tools within the FEAT GUI (graphical user interface of the FEAT program). Then we will see how to apply and invert transformations. Being able to achieve precise registrations is CRUCIAL for structural, functional and diffusion image analysis. If registrations are not accurate, further statistics at a structural or group level will not be accurate.

There are a few open questions. These are intended to make you think about the reasons for analysis choices and will serve as a self-assessment of what you have learned. You should be able to answer those questions during the practical. Please discuss the answers with your fellow students and tutors. You can work in small groups/pairs if you would like. You can look back at the lecture notes and ask tutors for help with any of these questions.

Remember that the data you are going to use is in BIDS format. If you need to refresh your BIDS knowledge, follow this link

If you are not able to attend the practical sessions, please send your answers to the open questions by e-mail to your tutors.

Helpful hints:


1: Two-stage Registration and Unwarping with FEAT
Register functional EPI images to the individual structural image and to standard space using the FEAT GUI. This includes fieldmap-based unwarping and the preparation of these fieldmap scans.
2: Applying and Inverting Transformations
Calculate and apply transforms and inverses from linear and non-linear registration (as output from FEAT). This provides experience in transforming masks (or other images) between the different "image spaces" (functional, structural, standard). The same principles apply for registration in diffusion imaging, and the similarities and differences are highlighted here.
3: Optional extra: Multiband data registration
Include an extra registration step to register (low-contrast) multiband data. Many of you may not need to complete this section, but for those of you collecting multiband data this may be a helpful exercise. An extra (high-contrast) image is added as an intermediate step when registering between a functional EPI image and a structural image.

Before you start: a note on using the command line & other GUIs

This practical focuses on registering fMRI data using the FEAT GUI. However, registrations can be performed using the command line or various other GUIs. Knowing about these may be useful to you at a later date.

FLIRT is the FSL tool for linear registration. Linear registration is typically used to align multiple images from a single subject (e.g. to register images from different modailities or those acquired at different time points), or to initialise non-linear registration.

A typical FLIRT command to calculate a transformation:

flirt [options] -in inputvol -ref refvol -out outputvol -omat outputmatrix

and to apply a transformation to an image:

flirt [options] -in inputvol -ref refvol -applyxfm -init matrix -out outputvol

You can find more details, including descriptions of the inputs and many optional variables, by typing flirt into the terminal. FLIRT can also be run via the GUI: you can open the GUI by typing Flirt & or Flirt_gui & for Macs

FNIRT is the tool for non-linear registration. Non-linear registration is typically used when registering multiple subjects to one another, or to a standard template.

FNIRT can be run via the command line, where an example command would be:

fnirt --ref=refvol --in=inputvol --infwhm=8,4,2 --subsamp=4,2,1 --warpres=8,8,8

To apply a warpfield to an image, we typically use the command applywarp. This will be demmonstrated later in the practical.

Finally, the FDT GUI can be used for registration of diffusion MRI outputs. This will be covered in more detail in the diffusion section of the course.

Two-stage Registration and Unwarping with FEAT

We have created a step-by-step registration guide that has been uploaded onto the fslwiki for your reference. You may use this as a reminder of image registration steps in future practicals.

Take a look inside the data directory:

cd ~/fsl_course_data/registration/

This directory contains the following directories:

If you are using multiband data, have a look inside the folder sub-multiband: you will find similar images, with an additional high-contrast image called sub-multiband_task-dummy_sbref.nii.gz. The sbref part of the name comes from the images being Single-Band-Reference. More details in section 3.
  1. sub-001: A folder containing the data from a single subject that you are going to work with.
  2. sub-example: A folder containing an example 'pre-baked' registration i.e. where the registration has been already run for you. We will use this a bit later to interrogate the output files. Note, this is the same subject and data as in sub-001.
  3. sub-multiband: A folder containing data for the optional section (multiband registration).

Get inside one of the directories (each of them represents a subject according to BIDS structure) and take a look:

cd sub-001/

You can see the following directories:

  1. anat: Anatomical (structural) data.
  2. func: Functional data.
  3. fmap: Fieldmaps data.

If you play around with cd and ls, you will see the following files:

In BIDS, metadata (information about the images) is stored in JSON files with a predefined structure that is easily readable by both humans and computers.
  1. anat/sub-001_T1w.nii.gz: A structural (T1-weighted) scan.
  2. func/sub-001_task-dummy_bold.nii.gz: A functional scan.
  3. fmap/sub-001_magnitude1.nii.gz: Raw fieldmap: magnitude image.
  4. fmap/sub-001_phasediff.nii.gz: Raw fieldmap: phase-difference image.
  5. fmap/FMAPS.txt: A text file containing the fieldmap information.
  6. fmap/sub-001_phasediff.json: A text file containing the fieldmap information in JSON format.
Open question 1: Use the fslinfo command to look at the details of the STRUCTURAL (sub-001_T1w.nii.gz) and the FUNCTIONAL (sub-001_task-dummy_bold.nii.gz) images. Which details indicate that sub-001_T1w.nii.gz is a 3D image and sub-001_task-dummy_bold.nii.gz is a 4D image?

The objective of this practical is to become familiar with how to perform and evaluate the results of registration in the FEAT GUI (the main functional analysis GUI). This involves fieldmap-based unwarping and multi-stage registration, and requires the images to be suitably prepared. Registration in other FSL GUIs (e.g. for resting-state functional or diffusion analysis) works very similarly.

Preparing the structural image

Get inside the anat directory:

cd anat/

We need to perform brain extraction on the structural image prior to using it for registration (as explained in the lecture). To do this run BET on the image sub-001_T1w.nii.gz, and save the result in the same directory (anat) as sub-001_T1w_brain.nii.gz. Check the results with FSLeyes. You can run BET either using the BET GUI (open by typing Bet & or Bet_gui & for Macs) or via the terminal (type bet in the terminal to see options).

G 1 Input image (sub-001_T1w.nii.gz) 3 BET 1->3 2 Options (e.g. -m) 2->3 4 Brain Extracted Image (sub-001_T1w_brain.nii.gz) 3->4 5 Brain Mask (-m) (sub-001_T1w_brain_mask.nii.gz) 3->5 6 ... 3->6

Open question 2: Why do we always run BET before running registration?

Open question 3: Discuss with your fellow students or a tutor: what is the best way to inspect the accuracy of the brain extraction in FSLeyes?

Fieldmap images

Get inside the fieldmap directory:

cd ../fmap

There are two images that Siemens scanners saved from a fieldmap sequence. These are:


where the first image represents the ordinary magnitude image from the fieldmap acquisition, and the second image represents a phase difference (between two different echo times, calculated internally as part of the fieldmap acquisition). The values in the phase difference image are directly proportional to the local distortions. Have a quick look at these with FSLeyes. We will need to use both the magnitude and the phase image.

Open question 4: Briefly explain what a fieldmap is and what it is used for?

Processing the fieldmap magnitude image

Typically the magnitude image will have 2 volumes and will need to be reduced to 1 volume before using BET. You can use fslroi to do this.

We will start by brain extracting the magnitude fieldmap image. Run brain extraction on the magnitude image and save the result as sub-001_magnitude1_brain.nii.gz. In the phase difference image the voxels around the edge of the brain are typically noisy due to partial voluming. To exclude these from subsequent processing steps, we will erode the brain-extracted magnitude image (shaving off one voxel from all edges). You will see the noisy voxels below, but in practice you are advised to look at the phase difference image first before deciding to erode. To do the erosion we run:

fslmaths sub-001_magnitude1_brain -ero sub-001_magnitude1_brain_ero

This performs an erosion operation (stripping one voxel from the edge) with the general tool fslmaths which acts a command-line image calculator, taking input images and performing operations on them and then saving them as a new image (the last name specified). Check what the results look like in FSLeyes:

fsleyes sub-001_magnitude1 -cm greyscale \
  sub-001_magnitude1_brain -cm red-yellow \
  sub-001_magnitude1_brain_ero -cm blue-lightblue &

Compare the sub-001_magnitude1_brain and sub-001_magnitude1_brain_ero to see the effect of the erosion.

Add the phase (sub-001_phasediff.nii.gz) to the viewer to see why we needed to erode the brain in order to avoid the noisy voxels at the edge. Note that the "lost" voxels will have fieldmap values filled in by extrapolating from the nearest voxel inside the mask, which is quite accurate for fieldmaps as the field variations are quite smooth (you cannot see this in these images as it happens in the later processing).

Processing the fieldmap phase difference image

Here we need to take this raw scanner output, which is scaled in a vendor-specific way (0 to 360 degrees are mapped to 0 to 4096 for Siemens), and convert it into a physically meaningful image with values expressed in radians per second (this is equivalent to an image in Hz multiplied by 2*pi). For this we need the phase difference image, the brain extracted (and eroded) magnitude image and the difference in the echo times of the fieldmap acquisitions. This latter value is 2.46 ms and can be found in the text file FMAPS.txt, which is conveniently given here but will not exist normally. Therefore it is important to record this echo time difference when you scan (your scanner operator will be able to give you the value. Although it can usually be determined later on, it is much easier to record it at the time when the scanner operator is present). In addition to FMAPS.txt, you may find the same piece of information in the sub-001_phasediff.json file, but note that there it is given in seconds, not milliseconds to comply with BIDS.

G 1 Fieldmap phase image(sub-001_phasediff.nii.gz)> 4 Fsl_prepare_fieldmap  (GUI or command line) 1->4 2 Fieldmap magnitude image  (sub-001_magnitude1_brain_ero.nii.gz) 2->4 3 Difference in echo times 3->4 5 Output Fieldmap (in radians/sec)  (sub-001_fieldmap.nii.gz) 4->5

Armed with this information, all we need to do is run the GUI called Fsl_prepare_fieldmap. Open the GUI by typing Fsl_prepare_fieldmap & or Fsl_prepare_fieldmap_gui & on Macs in the terminal, and set up all the information required. Note that these images come from a Siemens scanner. Set up all the information required in the GUI, including the Difference of Echo Times, (phase image is sub-001_phasediff.nii.gz and the brain extracted magnitude image is sub-001_magnitude1_brain_ero.nii.gz) calling the output sub-001_fieldmap, and press Go. View the output with FSLeyes (fsleyes sub-001_fieldmap & and check that most of the brain has small values (less than 200 rad/s) while in the inferior frontal and temporal areas the values are larger (either large and positive or large and negative).

Using the FEAT GUI

With the fieldmap processed and the structural image brain extracted we are now ready to use the FEAT GUI for registration. Note that the "unwarping" of images using fieldmaps is done in the Pre-stats tab of the FEAT GUI.

The FEAT GUI is used for running functional analyses at the single-subject and the group level, which we will explore in future sessions. Today, we will use the FEAT GUI for running only pre-processing and registration.

Start the FEAT GUI by typing Feat & or Feat_gui & on Mac) in the terminal. From the drop-down list in the top right corner select Preprocessing. We now need to set up the GUI to run our registration with unwarping.

G 1 Functional image (sub-001_task-dummy_bold.nii.gz) 8 Distortion Correction and Registration  (BBR) 1->8 2 Structural image (sub-001_T1w.nii.gz) 2->8 3 Fieldmap image (sub-001_fieldmap.nii.gz) 3->8 4 Parameters (of FMRI acquisition) 4->8 9 Undistorted and registered functional image (example_func2highres.nii.gz) 8->9 10 Nonlinear spatial transformation: Distorted FMRI to structural (example_func2highres_warp.nii.gz) 8->10 11 Linear spatial transformation: Undistorted FMRI to structural (example_func2highres.mat) 8->11
G 12 Structural image (structural.nii.gz) 14 Linear Registration (FLIRT) 12->14 16 Nonlinear Registration (FNIRT) 12->16 13 Standard Template: e.g. MNI (standard.nii.gz) 13->14 13->16 15 Linear transformation (highres2standard.mat) 14->15 15->16 17 Registered Image (highres2standard.nii.gz) 16->17 18 Nonlinear transformation (highres2standard_warp.nii.gz) 16->18

We will start with the main Data tab. To begin with click on the Select 4D data button and select the image sub-001_task-dummy_bold.nii.gz. Once this is done, click on the file browser for the Output directory and make sure the directory is set to the func directory of subject sub-001. Then, in the Selection box at the bottom type "test_reg" and press OK. (If you leave it empty, it would normally default to something like ~/fsl_course_data/registration/sub-001_task-dummy_bold.feat). We will cover High Pass Filter Cutoff(s) in a future session.

Now go to the Pre-stats tab and click the B0 unwarping button. Note that all other parts of this tab (e.g. motion correction) are set to their default values and we will leave them with these settings. Again they will be covered in future sessions. Now go through and populate the relevant parts:

Multiband data: here is where you use the additional single-band-reference high-contrast image (sub-multiband_task-dummy_sbref.nii.gz) as Expanded functional image. More details in section 3.

Go to the Registration tab and click on the Main structural image button. Open the file browser and select sub-001_T1w_brain. Make sure the options underneath are set to Normal search and BBR. In the Standard space box, make sure the image MNI152_T1_2mm_brain is selected in the correct directory. (This reference image is part of FSL. In general, to find out where FSL is installed, type echo $FSLDIR into a terminal. The standard space reference images are in data/standard/ inside that directory.) We will not select the Nonlinear button in the Standard space section for this part of the practical in order to save time, but you normally would use this setting.

OK, that's everything we need to register the functional image to standard space. So double-check that the Pre-stats and Registration tabs look correct and when you are happy, press the Go button at the bottom. This should start up a web browser showing the progress of FEAT - although it may take a minute for this to appear.

Open question 5: Why would we usually use non-linear registration between structural and standard space?

Now go back to the FEAT GUI, and we are going to run a comparison registration without fieldmap unwarping. So go to the Pre-stats tab and de-select the B0 unwarping button. In the Data tab, re-name the output to something like test_reg_no_fmap. Everything else stays the same, and once you are happy with all the setting press the Go button again.

While you wait

The FEAT jobs will take about 15-30 minutes to finish. In the meantime we can have a look at the registrations provided in the sub-example subject directory. Change to this directory, and open the webpage report for the registration:

cd ~/fsl_course_data/registration/sub-example/func/example_reg.feat
firefox report_reg.html &

If you are using a Mac, open the webpage report as follows:

open report_reg.html &

Look carefully at the results of the registrations in the web page report and in the Unwarping page for the cases where fieldmap-based correction was run. Do these registrations seem accurate to you? Note that you should not trust borders with signal loss areas as these are not true anatomical boundaries but artificial borders.

It is also highly recommended to use FSLeyes to look in more detail. We can look at each of the two registration steps separately (functional to structural, and structural to standard), but remember when these two steps are combined to produce a functional to standard transformation, the functional image is only resampled ONCE into standard space. Let's first look at the initial registration step (functional to structural) in FSLeyes. Load the structural image into FSLeyes using the following command:

cd reg
fsleyes highres.nii.gz &

This highres.nii.gz image is created in the reg folder by FEAT from the T1 structural image we specified.

Using the FSLeyes GUI, add the example_func2highres.nii.gz image (example_func is a distortion-corrected example volume from the EPI/functional data, and example_func2highres is the example_func image transformed into structural space), and the example_func2highres_fast_wmedge.nii.gz (this image shows the location of the white matter edges, as defined by the highres image). Change the colour map of this wmedge image, by selecting in the image list at the bottom left, and then selecting Red in the colour map drop down list at the top of the FSLeyes window.

Click around the image to see where the registration is particularly good (as the red edges derived from the structural should align with the changes the in greyscale intensities of the functional image). Toggle the visibility of the example_func2highres image on and off (the button), or adjust its transparency (the Opacity slider in the display toolbar at the top of the FSLeyes GUI) to judge its alignment to the highres image.

Feel free to look at other images in this reg subdirectory or in the unwarp subdirectory inside this. For example, the uncorrected registration result is in the file unwarp/example_func_distorted2highres.nii.gz and can be viewed separately or added to the FSLeyes session above.

Now open another FSLeyes session (without closing the old one) from the terminal to view the second registration step (structural to standard):

fsleyes standard.nii.gz &

Add the highres2standard.nii.gz image, which is the structural image transformed into standard space. In this case non-linear registration (FNIRT) was used after affine linear transformation (FLIRT) for maximum accuracy. Use the same FSLeyes tools to check the registration of the structural image to the standard image.

Leave both of these FSLeyes sessions open for the moment, as we are now going to compare the registrations you just ran to these given examples.

Once the FEAT job is finished

Firstly, look at your webpage reports for the registrations you ran. It is also good practice to check the 'Logs' part of the report to check for obvious errors. Can you spot any noticable differences compared to the example registration webpage report? We will now compare these registrations carefully using FSLeyes.

Go back to the FSLeyes window where you were looking at the first registration step (functional to structural). Now add the example_func2highres.nii.gz image from the registration you ran with fieldmap correction (sub-001/func/test_reg.feat/reg/example_func2highres.nii.gz). How does this registration compare to the original? It should be identical, or at least very, very similar.

Now add the registration you ran WITHOUT fieldmaps (sub-001/func/test_reg_no_fmap.feat/reg/example_func2highres.nii.gz). You may wish to rename this image within FSLeyes to something like example_func2highres_no_fmap.nii.gz to avoid confusion (as FSLeyes will initially give both images the same name). Use the FSLeyes tools you practised earlier to compare the registrations with and without fieldmaps

Open question 6: What differences can you see between the registrations with and without fieldmaps?

Which areas likely benefit the most from fieldmap distortion correction?
Incorrect. The visual cortex doesn't usually suffer from as much distortion as other areas of the brain as it is further away from unusual bone/air interfaces, such as the sinuses.
Correct! The prefrontal cortex often suffers from large distortions (and drop-out, which cannot be corrected for using fieldmaps) due to its proximity to sinuses etc.
Incorrect. The thalamus is very central within the brain, and is not particularly susceptible to distortions in EPI imaging.

Now go to the FSLeyes window where you were looking at the second registration step (structural to standard). Add the highres2standard.nii.gz image from the registration you ran (sub-001/func/test_reg.feat/reg/highres2standard.nii.gz). This registration step was done linearly (using FLIRT) rather than nonlinearly (using FNIRT). Compare the linear and linear+non-linear versions of this step. The linear+non-linear version can be found at ~/fsl_course_data/registration/sub-example/func/example_reg.feat/reg/highres2standard.nii.gz.

Open question 7: What differences can you see between the linear and linear+non-linear registrations of the structural to standard brain? Name some anatomical structures that are better aligned with the non-linear registration.

Now add (to FSLeyes) the second brain example we have provided, using both linear and non-linear registration to the standard space:

Which brain (original or brain2) registered more successfully to the standard brain using linear only registration? Can you think why this might have been the case?
Correct! This brain registered pretty well using linear only registration, although it was slightly improved with non-linear registration. This brain was from a young adult, whose brain was a much closer match to the MNI template it was registered to.
Incorrect. This brain was very badly registered to the standard using linear only registration. This brain was from an older adult with much larger ventricles and local brain differences to the MNI template, hence linear registration performed very poorly.

Finally, de-select (or remove) the highres2standard images within the FSLeyes session. Add the combined registration images from the supplied example using both fieldmaps and non-linear registration (~/fsl_course_data/registration/sub-example/func/example_reg.feat/reg/example_func2standard.nii.gz) and the registration you ran without fieldmaps or non-linear registration (~/fsl_course_data/registration/sub-001/func/test_reg_no_fmaps.feat/reg/example_func2standard.nii.gz). You may need to rename these within FSLeyes to avoid confusion. The registration without fieldmap correction or non-linear registration will be markedly worse than the original registration, as both sub-optimal registration steps have now been concatenated into one step.

How many times do we resample the image when we register from functional to standard space, and why?
Incorrect. While the registration steps are performed separately, the transformation files are concatenated so that we only have to resample once into standard space. Accuracy of registration steps is maintained, while resampling degrades the image quality and should be minimized.
Incorrect. Whilst some analysis is conducted in native space, many require us to resample our image into a different space, such as a template space when we want to compare individual brains in a group analysis.
Correct! The individual registration steps are concatenated to move from functional to structural to standard space all in one go, with resampling only happening at the very end into the standard space.

Open question 8: Why do we not register the functional image directly to the standard space?

Applying and Inverting Transformations

The objective of this section of the practical is to become familiar with applying transformations, as well as their inverses, to move masks (or images) between different spaces. This is very useful as although FEAT, Featquery and FDT do a lot of this "behind the scenes" for you, there will be many cases when you want to do something beyond the standard options and then you'll need to be able to do this for yourself.

We will be working with the files from the FEAT analysis in the previous part of the practical, however what we are doing is not restricted to functional analysis. FDT outputs similar files when analysing diffusion datasets, and the same files (affine transformation matrices and warp fields) are output by the fundamental tools, FLIRT and FNIRT, when doing any structural analyses.

Transformation files

If you look in the example registration directory you will see many different files:

cd ~/fsl_course_data/registration/sub-example/func/example_reg.feat/reg/

The crucial ones for registration purposes are the transformation files that come in two different varieties: affine matrices (ending with .mat - generated by FLIRT) and warp fields (ending with _warp.nii.gz - generated by FNIRT). For now we will not look at the contents of these files (see the exercises below for more about this) but instead we will explain what each of them means.

The naming convention is always from the input space to the reference space (or source to destination if you prefer). For example, the file highres2standard.mat is an affine transformation going from the highres (structural) space to the standard (MNI) space. There is also the file highres2standard_warp.nii.gz that represents a non-linear warp from highres space to standard space. We have both of these because it is necessary to initialise all non-linear registrations with an affine registration (that gets the head in roughly the right position and scaling to allow the non-linear registration to work well). When you want to use a transformation between these spaces, you would generally go for the warp field (when it exists) and ignore the initial affine registration. Note that the warp fields include the affine transformation as part of them, so you don't need to use both.

There are three main spaces in a FEAT analysis: functional (represented by example_func); structural (represented by highres); and MNI (represented by standard). Various combinations of transformations exist in this directory (e.g. example_func2highres, example_func2standard, highres2standard) but not all (e.g. standard2highres). Note that in a diffusion analysis, run via FDT, the three spaces are called diff, str and standard, and all combinations of transformations are provided.

One thing that might confuse you is why there exists example_func2highres_warp.nii.gz when BBR (which performs linear registration) was run to do the registration of functional to structural images. This is because of the fieldmap-based distortion correction, which is not just a linear (affine) registration and so must be represented as a warp field.

Creating an example mask

Now let's make a mask in the standard (MNI) space so that we can transform it into the other spaces and use it to calculate some ROI quantities. We will do this using FSLeyes - type in fsleyes -std & to get started.

Once FSLeyes is open, select the Settings > Ortho View 1 > Atlas panel menu option. This will open up a new panel along the bottom of the FSLeyes GUI that allows you to look at anatomical information from the atlases included with FSL. We can use these atlases to create a mask image (we will choose the left hippocampus from the Harvard-Oxford subcortical atlas, but there are lots of possibilities).

Click the Atlas search tab. Type hip into the search box at the top of the right section - note that as you type, all atlases, in the atlas list to the left, which contain a structure that matches the search term, are highlighted. Click the checkbox next to the Harvard-Oxford Subcortical Structural Atlas to add it as an overlay. Then, in the structure list on the right, click the "+" button by the Left Hippocampus entry, to move the cursor location to this structure.

Now we are going to select the voxels in the left hippocampus. An alternative method to create a mask will be discussed in the first FEAT practical.

  1. Turn on edit mode (Tools > Edit mode ). Two new toolbars will be added to the FSLeyes window.
  2. On the toolbar along the top:
    • Click the selection mode button ()
    • Click the select-by-intensity button ().
    • Enable 3D selection ().
    Now we are able to select regions of voxels according to their intensity.
  3. Click anywhere in the left hippocampus structure to select all of the voxels within it.
  4. On the toolbar running down the left hand side, click the Create mask button (), to copy this selection to a new mask image.
This mask can also be created directly at the command line using fslroi and fslmaths with the images in $FSLDIR/data/atlases and finding the appropriate values from the xml files (but be warned that the numbers in the xml files differ by one from the numbers needed in fslroi - see the FSL wiki for more details).

A new image will be added to FSLeyes, with ones in the left hippocampus, and zeros everywhere else. Exit edit mode (Tools > Edit mode), and toggle the visibility of the Harvard Oxford subcortical atlas (the button in the overlay list) so you can see your new mask image better.

We will now save this mask image out to a file in the directory ~/fsl_course_data/registration/sub-example/func/example_reg.feat/reg. Click on the save button () alongside the mask image in the overlay list, and choose an appropriate name (e.g. LeftHippMask). To make life a lot easier later on make sure you remove all spaces from the filename. This is a general rule to stick with, as spaces within filenames will almost always cause problems and are easily avoided.

Inverting a transform

We want to transform the mask we just made into the functional space in order to calculate an ROI value (e.g. of a statistical image, or an average timecourse, etc.). To go from the standard space to the functional space we would need to have the transformation standard2example_func_warp.nii.gz (or something named like this). In FEAT this does not exist (in FDT the equivalent is generated automatically, and called standard2diff_warp.nii.gz).

As feat does not create the required warp field, we need to create it ourselves from the transformations that it does provide. In this case we do not want to undo the distortion correction (i.e. we want a mask in distortion-corrected functional space). For the structural-to-functional transform we therefore only need highres2example_func.mat which was already created by FEAT. We do need to calculate the nonlinear standard-to-structural transform, which can easily be done using the invwarp command, as follows.

invwarp -w highres2standard_warp -o standard2highres_warp -r highres

where the final part (the reference) controls the size (FOV) and resolution of the warp and should generally be the destination space of the new transform. As this warp transforms from standard space to structural (we will stick on the final transformation to functional space below), we specify highres. (This may take as long as 25 minutes to complete so we have already run it for you and you will find the output standard2highres_warp.nii.gz in the folder.)

G 1 Nonlinear transformation (highres2standard_warp.nii.gz) 3 invwarp 1->3 2 Input image (highres) 2->3 4 Inverted nonlinear transformation (standard2highres_warp.nii.gz) 3->4

Applying a transformation

Now that we have the transformation that we need, we can apply it using the applywarp command, by specifying a warp (-w). The command you need is (with your own filenames):

applywarp -i LeftHippMask -r example_func -o LeftHippMaskFunc \
  -w standard2highres_warp --postmat=highres2example_func.mat

which goes from the standard space via the highres space to the example_func space (the last part only needing a rigid-body transformation matrix, as we want to end up in the distortion-corrected functional space, rather than the original distorted one).

G 1 Image to transform  e.g. mask in standard space  (LeftHippMask.nii.gz) 4 applywarp 1->4 2 First transformation  e.g. nonlinear from standard to structural (standard2highres_warp.nii.gz) 2->4 3 Second transformation  e.g. linear from structural to functional (highres2example_func.mat) 3->4 5 Transformed/Resampled image  e.g. mask in example_func space (LeftHippMaskFunc.nii.gz) 4->5

Visual Check

Use the command:

fsleyes example_func LeftHippMaskFunc &

to see the mask on the functional image. Note that the values at the edge of the mask lie between 0 and 1.

Thresholding the Mask

In order to obtain a binary mask (where each voxel has a value of either 0 or 1) we need to threshold and binarise the transformed mask. This is easily done with fslmaths but the threshold used is arbitrary. If a high threshold is chosen (e.g. 0.9) then most edge voxels will be excluded and the mask will be tighter and less likely to include neighbouring structures. This is often desirable when trying to make sure that only the structure of interest is included, but it might end up with the mask being quite small. So sometimes a threshold near 0.5 is preferable, to make a mask of similar size/volume. Or sometimes a mask is needed that does not leave out any of the structure, in which case a low threshold (e.g. 0.1) can be better. We also binarise the mask with the -bin command in fslmaths, to make all voxels within the mask have a value of 1. In this case we will choose a high threshold in order to get a mask where we are very confident that each voxel in the mask is within the hippocampus. This can be done with:

fslmaths LeftHippMaskFunc -thr 0.9 -bin LeftHippMaskFuncBin

Load the resulting image into FSLeyes and compare it to the original, pre-thresholded version in the functional space.

Using the Mask

There are many possible ways in which a mask can be used (e.g. getting average statistical values) but as an example will we calculate the average timecourse of the fMRI within this mask. This is done with the command:

fslmeants -i ../filtered_func_data -m LeftHippMaskFuncBin

which will output a column of numbers, representing the timecourse of the average signal intensity (of the pre-processed fMRI data) within this mask. We won't do anything with this for now, but such calculations can be very useful in all sorts of situations.

The main point of this exercise was to see how to transform your own masks (or images, as the only difference is skipping the thresholding and binarising steps) between spaces. For functional studies you can often do similar things with the tool Featquery but it is not as flexible and generally useful as being able to process things yourself.

If we were interested in the functional signal in (for example) the amygdala within the fMRI data in a particular subject, which space would we transform a standard mask of the amygdala into for further processing?
Incorrect. We perform most of our fMRI analysis in distortion-corrected functional space. The accuracy does not improve in structural space, as the data was acquired in functional space.
Incorrect. We perform most of our fMRI analysis in distortion-corrected functional space.

Open question 9: How would you change the above command to get the output as a text file (e.g. LeftHippMeanTS.txt) rather than printed in the terminal? HINT: type fslmeants into the terminal to see the usage of the command.

Plotting time series with FSL-Python (optional)

FSL-Python is a virtual environment that FSL uses to run those of its components that were written in the programming language Python. Throughout your research you might want to familiarise yourself with this powerful programming environment. Similarly to bash scripting, it can help you assemble various FSL utilities into a coherent post-processing pipeline and also perform intermediate processing of your neuroimaging data according to your needs.

As an example, if you are interested to see the mean signal of the left hippocampus throughout the experiment, you can use fslpython to plot the data from the file that you have just created. For this, start fslpython (fslpythonw on a Mac) in your terminal window:


You will see that the prompt has changed to >>>. This indicates that you are in the interactive shell of FSL-Python and you can type python commands to perform the plotting:

import numpy as np
import matplotlib.pyplot as plt
time_series = np.loadtxt("LeftHippMeanTS.txt")

To exit the interactive shell, close the figure and type quit().

Multiband data registration (Optional)

A new functional imaging technique that is becoming more popular is 'multiband imaging'. Multiband imaging allows people to acquire functional images more quickly, allowing more volumes in the functional 4D file for more statistical power, or shortening functional scanning times. Many of you might be using multiband data for your own imaging projects, so here we have an optional section to demonstrate how we can optimise registration of multiband scans.

Because multiband images are acquired very quickly, they can have low contrast between grey and white matter. Therefore, to aid registration we can add an additional high-contrast image to our registration between functional and standard spaces. This high-contrast image, which is acquired without using multiple bands, is usually one of the first few scans ('pre-saturation' scans) acquired in a multiband sequence, which are usually discarded before functional analysis. In every other way it matched the functional scans used in the analysis, so it is a perfect match to the functional image (sub-001_task-dummy_bold.nii.gz) image, just with greater contrast between tissues in the brain. Note that registration of multiband data does not require this step to run, but it is recommended to use this intermediate contrast image for improved registration of multiband images.

Move into the sub-multiband directory:

cd ~/fsl_course_data/registration/sub-multiband/

This directory (as in the first example) contains the following directories:

  1. anat: Anatomical (structural) data.
  2. func: Functional data.
  3. fmap: Fieldmaps data.

If you play around with cd and ls, you will see the following files:

  1. anat/sub-multiband_T1w.nii.gz: A structural (T1-weighted) scan.
  2. anat/sub-multiband_T1w_brain.nii.gz: A brain extracted version of the previous structural (T1 weighted) scan.
  3. func/sub-multiband_task-dummy_bold.nii.gz: A multiband functional scan.
  4. func/sub-multiband_task-dummy_sbref.nii.gz: A high-contrast volume (single-band-reference) to help aid registration.
  5. fmap/sub-multiband_magnitude1.nii.gz: A magnitude fieldmap image.
  6. fmap/sub-multiband_magnitude1_brain.nii.gz: A brain extracted version of the previous magnitude fieldmap image.
  7. fmap/sub-multiband_phasediff.nii.gz: A phase-difference fieldmap image.
  8. fmap/sub-multiband_fieldmap.nii.gz: A processed fieldmap image we have created for you.
  9. fmap/FMAPS.txt: A text file containing the fieldmap information.
  10. func/example_multiband_reg.feat: An example registration using FEAT.

If you are short on time you can open the example registration web report to have a look at this registration, and note how the intermediate step helps the functional to structural registration:

firefox func/example_multiband_reg.feat/report_reg.html &

Note that the registration from example_func to highres is now split into two parts. The first transforms from example_func to the high-contrast volume (referred to as initial_highres). The second transforms from the high-constrast volume to highres.

If you want to try running this registration yourself, open a new FEAT GUI by typing Feat & in the terminal. Change the drop-down list to Preprocessing and enter the sub-multiband_task-dummy_bold.nii.gz image in the Select 4D data input. Now go to the Pre-stats tab and click the B0 unwarping button. Fill in the information as follows (note that not all scan information is the same as before so follow the instructions carefully):

All other parts of this tab can be left with their default settings. In the Registration tab, now click on the Expanded functional image button. Open the file browser and select sub-multiband_task-dummy_sbref.nii.gz. Note that registration does not require this step to run, but it is recommended to use this intermediate contrast image for registration of multiband data. Select sub-multiband_T1w_brain.nii.gz as your Main structural image. Make sure you turn the nonlinear option OFF so that you save some time here. Go back to the Data tab, and rename your output (in the Output directory section) to something like "test_reg_multiband". Check all your options and press the Go button at the bottom again. This should start up a new web browser tab with the progress of your new FEAT run. Note how the extra registration step is now included in the report. Feel free to load any of the registration steps into FSLeyes to explore these in more detail.

The End.