Run Bash Command (FSL) in Jupyter Notebook

💡

Note: This tutorial will assume you have some very fundamental knowledge of Python and Unix shell and installed fsl correctly on your current machine.

Run FSL in Jupyter

Why bother?

JupyterLab and Jupyter Notebook are the most popular tools among data scientists. Jupyter provides a great way to keep your code and results recorded and organised.

Check here for more information about project Jupyter

In short, the benefits of using fsl in jupyter are as follows:

Break down your analysis to a step-by-step style

The outputs and results are recorded

Use Python to boost your analysis

I will show you an example at the end of this blog. If you don't have jupyter on your machine, you can open the live notebook here right now. As it will take a few minutes to build.

How to do it?

There are a few ways that you can use FSL in a jupyter notebook.

The first way is the easiest and handiest way which is running command-line tools in jupyter notebooks via multiple IPython magic commands since most of the FSL utilities can be accessed from the command line.

The simplest IPython magic function for this purpose is the exclamation mark! We will use this as the main method in this blog but will also cover a few other magic functions.

Except for this way, there are other ways to do this like: Install different kernels in Jupyter, and then using bash or Matlab to run your analysis. Or use FSL official Python packages fslpy and fsleyes.

If you prefer to work with MATLAB, I will recommend you to use the IOctave kernel, it also provides magic functions that are similar to what I will talk about later.

Other ways are way more complicated than the first way, I won't get into any details here, if you are interested, you can check my other blogs.

Use Command-line Tool in Notebook

This part mainly relies on IPython magic functions. Use %magic to check all magic functions. Click here to learn more.

💡

The magic function starts with % only works for one line, starts with %% works for the whole cell

Exclamation mark

Use ! in front of the code to execute it in shell and capture the output

💡

All the characters behind! will be interpreted in the shell, But in front of the! , the code still interpreted in Python

Define an alias for a shell command.

%alias allows you to turn a shell command into a Python magic function


ex_img_dir = 'example_data/sub-101/ses-1/anat/sub-101_ses-1_T1w.nii.gz'

# basic usage:
# %alias alias_name system_command
%alias feyes fsleyes
%feyes $ex_img_dir -cm "greyscale"

# You can also include parameters in the alias
# %alias alias_name system_command %s -params 
%alias feyes fsleyes %s -cm "red-yellow"
%feyes $ex_img_dir

Run the whole cell in shell

The first way is not actually running the whole cell like other methods. You can use; and\ to extend one line of code infinitely.

💡

The advantage of this method is you can still access the variables from the python kernel

There are multiple other ways you can run a cell in shell, they are hardly different. Just type %%! %%system %%script bash at the first line of the cell

💡

It is not possible to access the variable in the python kernel if you are using these methods

Run a cell via a shell command

%%script is a very versatile magic command, the most helpful way to use this command is to access other kernels through it for example, Matlab, Rscript, SQL, Ruby, Perl etc.

💡

Unfortunately, in this method, you can't use the expanded variables from the Python kernel.

Variable Expansion in IPython

As you can see above, if you want to pass a Python Variable to your shell command via magic command, you can use $ in front of the Python variable, or enclose variables using {}.

💡

If you are using a variable defined in shell, you will need $$ in front of the variable.

Other Magic Functions

By now, I have covered most of the useful magic functions in Jupyter that can help you use FSL in your notebook. But there are still many helpful functions that can make your work a lot easier.

If you want to know more, please check my blog here.

An example

The data I used here is from T1-weighted structural MRI study of cannabis users at baseline and 3 years follow up. I selected four subjects from the original dataset, two health controls and two cannabis users.

You can open a live notebook here, or you can download the data and the notebook from my GitHub page and run it on your machine.

A-Jupyter-template-for-mri-analysis/fsl_in_jupyter.ipynb at main · Wetiqe/A-Jupyter-template-for-mri-analysis

Contribute to Wetiqe/A-Jupyter-template-for-mri-analysis development by creating an account on GitHub.

https://github.com/Wetiqe/A-Jupyter-template-for-mri-analysis/blob/main/fsl_in_jupyter.ipynb

Here we will perform a simplified VBM analysis on the T1 image from the first session.

Setup

Import the libraries and define the functions that will be used in the analysis

Preprocessing

Gather T1 Files

Take advantage of python and bash, making things easier.

Bias Field Correction

Create Glm model

Call the Glm GUI and save the design

Run VBM

Run FSL VBM and collapse the long output. And time the process.