JupyterLab with FSL and FreeSurfer

  • Updated

This article provides some practical examples of how to access and use JupyterLab with FSL and FreeSurfer to perform brain imaging analysis, complete with details of how to visualise images. The workflows below combine both the use of Python and Bash.

It's important to note that JupyterLab does not support GUI access. As a result, graphical user interfaces (GUIs) of FSL and FreeSurfer, and commands like FSLeyes won't launch an image viewer. Instead, you’ll be working with command-line tools, which are equally effective. For visualisation, this article will use Python libraries such as matplotlib and NiBabel. 

Find JupyterLab with Image Processing 

  1. Navigate to the Tools Library in UKB-RAP.

  2. In the dropdown menu, locate JupyterLab with Python, R, Stata, ML, Image Processing.

  3. Click on the tool and press Run. Select a default output folder. Click next.

  4. A configuration screen will be displayed where the instance type can be customised. 
    Select IMAGE_PREPROCESSING under the feature tab. 
    Other useful settings:
  • Duration: Set how long the JupyterLab session should run. The instance will automatically terminate after this time.
  • Priority: Selecting high priority will prevent an instance being reclaimed while you are using it. It will incurs additional cost, but is good for jobs on popular instances that will take more than 15 minutes. See here for more information.
  • Instance Type: 
    • Different instance types offer varying levels of memory, compute power, and storage. 
    • The mem1_hdd1_v2_x16 instance type is assigned by default, but may take some time to boot. Load times on ssd may be faster than seemingly equivalent hdd disc types.
    • CPU only instances will be sufficient for running most FSL and FreeSurfer commands. However, if your analysis involves intensive processing, e.g., fsl bedpostx, you may wish to consider utilising a GPU instance for these sections.
  1. Once configured, click Launch Analysis.
  2. You’ll be redirected to the Monitor tab, where you can track the status of your job:
  • Waiting: indicates resources are being allocated, and your instance is not yet ready:
  • Running: Your instance is active. You’ll see an Open button next to the worker URL.

If you encounter a 502 Bad Gateway error, don’t worry—it usually means the instance is still loading. Wait 10–15 minutes and try again.

  1. Once opens, the JupyterLab interface will be presented ready for your analysis. Open up a new bash notebook to begin typing your commands.

Set up your JupyterLab session and download your data 

Install an unzipping package:

apt-get update
apt-get install unzip

Before starting, use FreeSurfer on the DNAnexus platform, you’ll need a valid license. You can register for one on the FreeSurfer registration page. Make sure to upload your license file to your project, and then run the following command to download the license file to the FREESURFER_HOME directory. You need to make sure that you are providing the path to the where the files are stored in your UKB-RAP project.

dx download license.txt -o $FREESURFER_HOME

Then use dx download to collect the data you wish to analyse. This example uses the Example T1 structural brain image in NIFT format, which is freely available on the Showcase website. 

dx download 20252_2_0.zip

Then, unzip your data within your instance. Use the -d flag to assign a directory to unzip the files into.

unzip 20252_2_0.zip -d sub001/

After unzipping, one can display an axial slice of the example T1 scan using NiBabel and matplotlib. Open a JupyterLab Python Notebook from the JupyterLab homepage and run the following:

import nibabel as nib 
import matplotlib.pyplot as plt

sub1_t1 = nib.load("sub-001/T1/T1.nii.gz")
t1_data = sub1_t1.get_fdata()
slice_index = t1_data.shape[2] // 2
axial_slice = t1_data[:, :, slice_index].T 
plt.imshow(axial_slice, cmap="gray", origin="lower")
plt.title(f"T1 Axial Slice {slice_index}")
plt.axis("off")
plt.show()


 

FSL Examples 

Brain Extraction

The FSL Brain Extraction Tool (BET) is used to isolate brain tissue from the rest of the head in MRI scans. In other words, it removes non-brain tissue—such as the skull and scalp—which is not relevant for neuroimaging analysis.

Using a bash terminal, run the following command on the example data. This uses BET on the T1.nii.gz scan, and saves the output in our sub-001 folder, inside a subfolder "bet", under the name 'bet_t1.nii.gz'. 

mkdir -p sub-001/bet
bet "sub-001/T1/T1.nii.gz" "sub-001/bet/bet_t1.nii.gz"

Once this has run, visualise the results on the JupyterLab Python Notebook to see what the tool has done:

import nibabel as nib
import matplotlib.pyplot as plt

img = nib.load("sub-001/bet/bet_t1.nii.gz")
bet_t1 = img.get_fdata()
slice_index = bet_t1.shape[2] // 2
axial_slice = bet_t1[:, :, slice_index].T  
plt.imshow(axial_slice, cmap="gray", origin="lower")
plt.title(f"T1 Axial Slice {slice_index} after brain extraction")
plt.axis("off")
plt.show()

 

Image Registration

Next, use FMRIB’s Linear Image Registration Tool (FLIRT) to provide an initial global alignment between the brain-extracted T1 volume and a standard MNI152_T1_1mm_brain template. This template can be downloaded from the FSL software library.

flirt -in sub-001/bet/bet_t1.nii.gz -ref $FSLDIR/data/standard/MNI152_T1_1mm_brain -omat T1_to_temp.mat

This produces a 4x4 affine transformation matrix (named above as T1_to_temp.mat). 

Following this, use FMRIB's Non-linear Image Registration Tool (FNIRT) to perform non-linear registration. This step incorporates the transformation matrix generated by the FLIRT command, enabling FNIRT to apply more detailed warping that accounts for anatomical variability within the image.

fnirt --in=sub-001/bet/bet_t1.nii.gz --ref=$FSLDIR/data/standard/MNI152_T1_1mm_brain --aff=T1_to_temp.mat

This will produce a coefficient file for the nonlinear warp (the name should be something like bet_t1_warpcoef.nii.gz).

Segmentation

FMRIB's Automated Segmentation Tool (FAST) can be used to segment an image of the brain into different tissue types, including grey matter, white matter and cerebral spinal fluid. 

The commands below make the output directory sub-001/T1/T1_tissue/, and runs FSL FAST with the output file prefix T1_fast. The T1_brain.nii.gz has been provided as an input image.

mkdir sub-001/T1/T1_tissue
fast -o sub-001/T1/T1_tissue/T1_fast sub-001/T1/T1_brain.nii.gz

FMRIB's Integrated Registration and Segmentation Tool (FIRST) can also be used for segmentation. FIRST enables segmentation of subcortical structures including regions such as the amygdala, thalamus and hippocampus.

The commands below has make the directory sub-001/T1/T1_seg, and use the input file T1_unbiased_brain.nii.gz

mkdir sub-001/T1/T1_seg
run_first_all -i sub-001/T1/T1_unbiased_brain.nii.gz -o sub-001/T1/T1_seg/T1_seg

Some of the output files for these segmentation commands may look familiar. This is because UK Biobank already provides researchers with many of the intermediary files from the UKB brain imaging pipeline. Some files within your T1_fast and T1_first folders should look similar to what you have now generated within your T1_seg and T1_tissue folders. 

Example outputs can be visualised from the FAST command using:
 

import nibabel as nib
import matplotlib.pyplot as plt

seg_img = nib.load("sub-001/T1/T1_tissue/T1_fast_seg.nii.gz")
seg_data = seg_img.get_fdata()
slice_index = seg_data.shape[2] // 2
seg_slice = seg_data[:, :, slice_index].T
plt.figure(figsize=(4, 4))
plt.imshow(seg_slice, cmap="jet", origin="lower")
plt.title(f"T1 Axial Slice {slice_index} FAST output")
plt.axis("off")



 

FreeSurfer Example

FreeSurfer can also be used within JupyterLab. The recon-all command can be used with the -autorecon1 flag, which initiates stages 1 through 5 of FreeSurfer’s pre-processing pipeline — including motion correction, intensity normalization, and skull stripping. This step typically takes around 10–15 minutes to complete.

To begin, specify subject ID as "sub-001" and create a recon1 subject directory to store the output.

Next, run the recon-all command, specifying the subject, the directory, and the path to the input T1-weighted image.

subj="sub-001"
subject_dir="recon1"

mkdir -p "$subject_dir"

recon-all -autorecon1 -sd "$subject_dir" -subject "$subj" -i "$subj/T1/T1.nii.gz"

The -autorecon1 flag can be omitted to run the full FreeSurfer cortical reconstruction pipeline, which includes all processing stages. This may take several hours to finish.

subj="sub-001"
subject_dir="recon1"

mkdir -p "$subject_dir"

recon-all -sd "$subject_dir" -subject "$subj" -i "$subj/T1/T1.nii.gz"

Once the recon-all step has finished, results can be visualised to see the outputs. For example, here is a visualisation of the brainmask.mgz file (using python):

import nibabel as nib
import matplotlib.pyplot as plt

img = nib.load("recon1/sub-001/mri/brainmask.auto.mgz")
img_canonical = nib.as_closest_canonical(img) 
recon = img_canonical.get_fdata()
slice_index = recon.shape[2] // 2
axial_slice = recon[:, :, slice_index].T 
plt.imshow(axial_slice, cmap="gray", origin="lower")
plt.title(f"T1 Axial Slice {slice_index} skull stripped")
plt.axis("off")
plt.show()
 


After analyses in JupyterLab have finished, remember to use dx upload to transfer your results back into your project space. Files created within your instance aren’t automatically saved to your UKB-RAP project, so without uploading them, they’ll be lost when the instance times out. For example, if you wanted to upload the entire sub-001 directory to your project, you could specify a folder and use the -r flag:

dx upload sub-001 -r

However, if you want to upload individual files you can specify a specific file name:

dx upload sub-001/bet/bet_t1.nii.gz

 

Was this article helpful?

2 out of 2 found this helpful

Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.