FSLeyes (pronounced fossilise) is the new FSL image viewer for 3D and 4D data (replacing FSLView). It does not perform any processing or analysis of images - that is done by separate tools. FSLeyes has lots of features to visualise data and results in a variety of useful ways, and some of these are shown in this introductory practical. You will also be using FSLeyes throughout the course, so it is useful to get a feel for it, but many more useful features will be included in the course.
This practical provides a quick introduction to some FSLeyes features that you will be likely to use quite often. For a full overview of what FSLeyes can do, take a look at the FSLeyes user guide.
Assuming you have downloaded the data and it is in the correct directory, please open a command terminal and type:
cd ~/fsl_course_data/intro ls
ls command gives you a list of the files in this
directory. Note that if you are not very familiar with using Unix it will be
useful to go through the preparatory material on UNIX.
Start FSLeyes by typing:
& means that the program you asked for
fsleyes) runs in the background in the terminal (or shell), and
you can keep typing and running other commands while fsleyes continues to
run. If you had not made
fsleyes run in the background (i.e., if
you had just typed
fsleyes without the
& at the
end) then you would not be able to get anything to run in that terminal until
fsleyes (although you could still type things, but
they would not run).
Other useful Unix info:
fgif it is the last job that was started.
bg. Note that
control-zon its own will give you the terminal prompt back but the job will be sleeping, not running in the background, until you do
FSLeyes by defaults opens in the ortho view mode. If you add
image filenames on the command line (after typing
will load them all automatically, and you can also add many options from the
command line. FSLeyes assumes that all of the images which you load share a
single coordinate system, but images do not have to have the same field of
view, number of voxels, or timepoints.
fsleyes -hto get an overview on how to use FSLeyes from the command line.
In FSLeyes, load in the image
example_func.nii.gz, by pressing
File > Add overlay from file and selecting the image.
Hold the mouse button down in one of the ortho canvases and move it around - see how various things update as you do so:
You can interact with an orthographic view in a number of ways. Spend a couple of minutes trying each of these.
The display toolbar allows you to adjust the display properties of the currently selected image. Play around with the controls and note how the image display changes (but leave the "overlay type" as "3D/4D volume").
If FSLeyes does not have enough room to display a toolbar in full, it will display left and right arrows (, ) on each side of the toolbar - you can click on these arrows to navigate back and forth through the toolbar.
The ortho toolbar allows you to adjust and control the ortho view. Play with the controls, and try to figure out what each of them do.
Open a lightbox view using View > Lightbox View. If you drag the mouse around in the viewer you can see that the cursor position is linked in the two views of the data (the ortho and the lightbox views). This is particularly useful when you have several images loaded in at the same time (you can view each in a separate view window and move around all of them simultaneously).
The lightbox view has a slightly different toolbar to the ortho toolbar.
You can "unlink" the cursor position between the two views (it is linked by default). Go into one of the views, e.g., the lightbox view, and press the spanner button (). This will open the lightbox view settings panel. Turn off the Link Location option, and close the view settings panel.. You will now find that this view (the lightbox view) is no longer linked to the "global" cursor position, and you can move the cursor independently (in this view) from where it is in the other views.
Close the lightbox view for now (click on the small red circle or X at the very top of the view).
Now load in a second image (
File > Add overlay from file. This image
thresh_zstat1) is a thresholded FMRI activation image. In the
bottom-left panel is a list of loaded images - the overlay list.
The overlay list shows the images which are currently loaded into FSLeyes. When you select an image in this list, it becomes the currently selected image - in FSLeyes, you can only select one image at a time.
You can use the controls on the display toolbar to adjust the display
properties of the currently selected image.Select the image you just loaded
thresh_zstat1), and use the display toolbar to change its colour
map to Red-yellow.
The overlay list allows you to do the following:
In the bottom right corner of the FSLeyes window you will find the location panel, which contains information about the current cursor location, and image data values at that location.
The controls on the left show the cursor location in "world" coordinates (millimetres). This coordinate system will change depending upon whether your image is in native subject coordinates, standard template coordinates (e.g. MNI152), or some other coordinate space.
The controls in the middle show the cursor location in voxel coordinates, relative to the currently selected image. If the currently selected image is 4D (e.g. a time series image), the bottom control displays the currently selected volume (e.g. time point).
The area on the right displays the intensity value and voxel location at the current cursor location for all loaded images. Note that if you have images with different resolutions loaded, the voxel location will be different for each of them.
Now remove all of the images you have loaded (you can
remove all images via the Overlay > Remove all menu
option), and load in
filtered_func_data, a 4D FMRI time
series. Watch this as a movie by pressing the movie button
() on the ortho toolbar. The data
changes very subtly over time, so you may wish to adjust the brightness and
contrast in order to see the data changing. Note that, when movie mode is
running, the volume index in the location panel scrolls through the different
time-point values. Note also that whilst the movie is running you can still
change the cursor position. Stop the movie by pressing the movie button
thresh_zstat1 stats overlay image back in. Make
filtered_func_data image is selected in the overlay
list, and open a time series plot view via View > Time
series. Note that the FMRI time series data for the current voxel
filtered_func_data is plotted in the time series view.
The time series toolbar allows you to control a few aspects of how time series are plotted.
thresh_zstat1image until you find a "highly activated" voxel. Press the add button () on the time series toolbar to add that voxel's time series to the plot. You can add more time series by moving to new voxels and clicking the add button again.
If you have added several time series to the display, they may all have quite different mean values, making comparison difficult - change the Plotting mode drop down menu to Demeaned to demean all displayed time series. You can also also choose to scale the time series to Percent changed. (i.e. in this case you're now seeing the BOLD % signal change values).
When you are finished exploring the time series, close the time series view.
Image histograms give you an overview of all of the intensities within an image. A histogram plots the distribution of intensities in the image; image intensity is on the x axis and the number of voxels with that intensity is on the y axis. Histograms are used as part of structural segmentation methods and can be useful for QC purposes.
Close all overlays (Overlay > Remove all). Open
structural and select View > Histogram to view a
The histogram toolbar is very similar to the time series toolbar, with a few extra options:
When you are ready, close the histogram view and continue to the next section.
Finally, we'll look at some more advanced FMRI analysis features in FSLeyes. Kill FSLeyes, then switch back to your terminal and type:
cd ~/fsl_course_data/fmri/ptt/at/at_left.feat fsleyes -ad filtered_func_data stats/zstat1 stats/zstat2
-adflag is short for
--autoDisplay, which tells FSLeyes to automatically adjust the display properties for certain types of images. In this case, the
zstat2images are thresholded and given bright colour maps.
You are now in an example FMRI analysis FEAT output directory. The image
names on the
fsleyes command line tell FSLeyes to load in each
of these images, to save you having to load them in by hand in the GUI.
Because we are viewing a FEAT analysis, it makes sense to change into FEAT mode: View > Perspectives > FEAT mode. Then, on the time series toolbar, change the Plotting mode to Normalised.
One of the nice features when in FSLeyes "FEAT mode" is that you can see a plot of the fitted timeseries model versus the data. You can also plot various other aspects of the FEAT model fitting process - click on the spanner button () on the time series toolbar, expand the FEAT settings for selected overlay section, and experiment with the settings. If none of the settings mean anything to you, don't worry - they will make more sense after the first FEAT lecture!
This FEAT output directory already contains versions of some of the images upsampled to "standard space" - the common image space that multisubject analyses are carried out in, which allows us to interact with the FSL atlases. Close FSLeyes and run:
fsleyes -ad reg_standard/reg/highres.nii.gz reg_standard/stats/cope1
-adflag configured the
cope1image so that positive COPE values are shown in red-yellow, and negative COPE values are shown in blue.
You might like to change the minimum display range value to 50, in the display toolbar, so that only strong activations (high COPE values) are shown. It is also possible to enable interpolation for the COPE image, to make the blobs look nicer - you can turn on interpolation in the display panel ().
Because these images are in standard space, we can turn on the atlas tools with Settings > Ortho View 1 > Atlas Panel. Now as you click around in the image you can see reporting of the probability of being in different brain structures. You might want to resize the different FSLeyes panels to increase the size of the Atlas information space (in general you do this by dragging around the edges of the different FSLeyes panels).
The atlas panel is organised into three main sections - Atlas information, Atlas search, and Atlas management. These sections are accessed by clicking on the tabs at the top of the panel. We will only cover the first two sections in this introductory practical.
The Atlas information tab displays information about the current display location, relative to one or more atlases:
The list on the left allows you to select the atlases that you wish to query - click the check boxes to the left of an atlas to toggle information on and off for that atlas. The Harvard-Oxford cortical and sub-cortical structural atlases are both selected by default. These are formed by averaging careful hand segmentations of structural images of many separate individuals.
The panel on the right displays information about the current display location from each selected atlas. For probabilistic atlases, the region(s) corresponding to the display location are listed, along with their probabilities. For discrete atlases, the region at the current location is listed.
You may click on the Show/Hide links alongside each atlas and region name to toggle corresponding atlas images on and off.
The Atlas search tab allows you to browse through the atlases, and search for specific regions.
The list on the left displays all available atlases - the checkbox to the left of each atlas toggles an image for that atlas on and off.
When you select an atlas in this list, all of the regions in that atlas are listed in the area to the right. Again, the checkbox to the left of each region name toggles an image for that region on and off. The + button next to each region moves the display location to the (approximate) centre of that region.
The search field at the top of the region list allows you to filter the regions that are displayed.
When you type some characters into the search field, the region list will be filtered, so that only those regions with a name that contains the characters you entered are displayed. The atlas list on the left will also be updated so that any atlases which contain regions matching the search term are highlighted in bold.
Use the atlas search feature to locate the thalamus (left or right); you should be able to see that there is activation here.
Spend some time with the atlas panel. Look at the information for some other atlases (click the checkbox next to some of the atlas names). In particular, the Juelich atlas is very complementary to the Harvard-Oxford atlases (being derived from post-mortem histological segmentations), as are the JHU atlases (being derived from diffusion MRI data).
Quit FSLeyes when you have finished looking at the atlases.