1. Introduction: nilearn in a nutshell

1.1. What is nilearn: MVPA, decoding, predictive models, functional connectivity

Why use nilearn?

Nilearn makes it easy to use many advanced machine learning, pattern recognition and multivariate statistical techniques on neuroimaging data for applications such as MVPA (Mutli-Voxel Pattern Analysis), decoding, predictive modelling, functional connectivity, brain parcellations, connectomes.

Nilearn can readily be used on task fMRI, resting-state, or VBM data.

For a machine-learning expert, the value of nilearn can be seen as domain-specific feature engineering construction, that is, shaping neuroimaging data into a feature matrix well suited to statistical learning, or vice versa.

1.1.1. Why is machine learning relevant to NeuroImaging? A few examples!

Diagnosis and prognosis

Predicting a clinical score or even treatment response from brain imaging with supervised learning e.g. [Mourao-Miranda 2012]

Measuring generalization scores

  • Information mapping: using the prediction accuracy of a classifier to characterize relationships between brain images and stimuli. (e.g. searchlight) [Kriegeskorte 2005]

  • Transfer learning: measuring how much an estimator trained on one specific psychological process/task can predict the neural activity underlying another specific psychological process/task (e.g. discriminating left from right eye movements also discriminates additions from subtractions [Knops 2009])

High-dimensional multivariate statistics

From a statistical point of view, machine learning implements statistical estimation of models with a large number of parameters. Tricks pulled in machine learning (e.g. regularization) can make this estimation possible despite the usually small number of observations in the neuroimaging domain [Varoquaux 2012]. This usage of machine learning requires some understanding of the models.

Data mining / exploration

Data-driven exploration of brain images. This includes the extraction of the major brain networks from resting-state data (“resting-state networks”) or movie-watching data as well as the discovery of connectionally coherent functional modules (“connectivity-based parcellation”). For example, Extracting functional brain networks: ICA and related or Clustering to parcellate the brain in regions with clustering.

1.2. Installing nilearn

  • Windows
  • Mac
  • Linux
  • Get source

  • First: download and install 64 bit Anaconda

    We recommend that you install a complete 64 bit scientific Python distribution like Anaconda . Since it meets all the requirements of nilearn, it will save you time and trouble. You could also check PythonXY as an alternative.

    Nilearn requires a Python installation and the following dependencies: ipython, scipy, scikit-learn, joblib, matplotlib, nibabel and pandas.

    Second: open a Command Prompt

    (Press "Win-R", type "cmd" and press "Enter". This will open the program cmd.exe, which is the command prompt)
    Then type the following line and press "Enter"

    pip install -U --user nilearn

    Third: open IPython

    (You can open it by writing "ipython" in the command prompt and pressing "Enter")
    Then type in the following line and press "Enter":

    In [1]: import nilearn

    If no error occurs, you have installed nilearn correctly.

  • First: download and install 64 bit Anaconda

    We recommend that you install a complete 64 bit scientific Python distribution like Anaconda. Since it meets all the requirements of nilearn, it will save you time and trouble.

    Nilearn requires a Python installation and the following dependencies: ipython, scipy, scikit-learn, joblib, matplotlib, nibabel and pandas.

    Second: open a Terminal

    (Navigate to /Applications/Utilities and double-click on Terminal)
    Then type the following line and press "Enter"

    pip install -U --user nilearn

    Third: open IPython

    (You can open it by writing "ipython" in the terminal and pressing "Enter")
    Then type in the following line and press "Enter":

    In [1]: import nilearn

    If no error occurs, you have installed nilearn correctly.

  • If you are using Ubuntu or Debian and you have access to Neurodebian, then simply install the python-nilearn package through Neurodebian.

    First: Install dependencies

    Install or ask your system administrator to install the following packages using the distribution package manager: ipython , scipy, scikit-learn (sometimes called sklearn, or python-sklearn), joblib, matplotlib (sometimes called python-matplotlib), nibabel (sometimes called python-nibabel) and pandas (sometimes called python-pandas).

    If you do not have access to the package manager we recommend that you install a complete 64 bit scientific Python distribution like Anaconda. Since it meets all the requirements of nilearn, it will save you time and trouble.

    Second: open a Terminal

    (Press ctrl+alt+t and a Terminal console will pop up)
    Then type the following line and press "Enter"

    pip install -U --user nilearn

    Third: open IPython

    (You can open it by writing "ipython" in the terminal and pressing "Enter")
    Then type in the following line and press "Enter":

    In [1]: import nilearn

    If no error occurs, you have installed nilearn correctly.

  • To Install the development version:

    Use git as an alternative to using pip, to get the latest nilearn version

    Simply run the following command (as a shell command, not a Python command):

    git clone https://github.com/nilearn/nilearn.git

    In the future, you can readily update your copy of nilearn by executing “git pull” in the nilearn root directory (as a shell command).

    If you really do not want to use git, you may still download the latest development snapshot from the following link (unziping required): https://github.com/nilearn/nilearn/archive/master.zip

    Install in the nilearn directory created by the previous steps, run (again, as a shell command):

    python setup.py develop --user

    Now to test everything is set up correctly, open IPython and type in the following line:

    In [1]: import nilearn

    If no error occurs, you have installed nilearn correctly.

1.3. Python for NeuroImaging, a quick start

If you don’t know Python, Don’t panic. Python is easy. It is important to realize that most things you will do in nilearn require only a few or a few dozen lines of Python code. Here, we give the basics to help you get started. For a very quick start into the programming language, you can learn it online. For a full-blown introduction to using Python for science, see the scipy lecture notes.

We will be using Jupyter for notebooks, or IPython, which provides an interactive scientific environment that facilitates many everyday data-manipulation steps (e.g. interactive debugging, easy visualization). You can choose notebooks or terminal:

Notebooks

Start the Jupter notebook either with the application menu, or by typing:

jupyter notebook
Terminal

Start ipython by typing:

ipython --matplotlib

Note

The --matplotlib flag, which configures matplotlib for interactive use inside IPython.

These will give you a prompt in which you can execute commands:

In [1]: 1 + 2 * 3
Out[1]: 7

>>> Prompt

Below we’ll be using >>> to indicate input lines. If you wish to copy and paste these input lines directly, click on the >>> located at the top right of the code block to toggle these prompt signs

1.3.1. Your first steps with nilearn

First things first, nilearn does not have a graphical user interface. But you will soon realize that you don’t really need one. It is typically used interactively in IPython or in an automated way by Python code. Most importantly, nilearn functions that process neuroimaging data accept either a filename (i.e., a string variable) or a NiftiImage object. We call the latter “niimg-like”.

Suppose for instance that you have a Tmap image saved in the Nifti file “t_map000.nii” in the directory “/home/user”. To visualize that image, you will first have to import the plotting functionality by:

>>> from nilearn import plotting

Then you can call the function that creates a “glass brain” by giving it the file name:

>>> plotting.plot_glass_brain("/home/user/t_map000.nii")

File name matchings

The filename could be given as “~/t_map000.nii’ as nilearn expands “~” to the home directory. See more on file name matchings.

_images/sphx_glr_plot_demo_glass_brain_001.png

Note

There are many other plotting functions. Take your time to have a look at the different options.


For simple functions/operations on images, many functions exist, such as in the nilearn.image module for image manipulation, e.g. image.smooth_img for smoothing:

>>> from nilearn import image
>>> smoothed_img = image.smooth_img("/home/user/t_map000.nii", fwhm=5)

The returned value smoothed_img is a NiftiImage object. It can either be passed to other nilearn functions operating on niimgs (neuroimaging images) or saved to disk with:

>>> smoothed_img.to_filename("/home/user/t_map000_smoothed.nii")

Finally, nilearn deals with Nifti images that come in two flavors: 3D images, which represent a brain volume, and 4D images, which represent a series of brain volumes. To extract the n-th 3D image from a 4D image, you can use the image.index_img function (keep in mind that array indexing always starts at 0 in the Python language):

>>> first_volume = image.index_img("/home/user/fmri_volumes.nii", 0)

To loop over each individual volume of a 4D image, use image.iter_img:

>>> for volume in image.iter_img("/home/user/fmri_volumes.nii"):   
...     smoothed_img = image.smooth_img(volume, fwhm=5)

Exercise: varying the amount of smoothing

Want to sharpen your skills with nilearn? Compute the mean EPI for first subject of the brain development dataset downloaded with nilearn.datasets.fetch_development_fmri and smooth it with an FWHM varying from 0mm to 20mm in increments of 5mm

Hints:

  • Inspect the ‘.keys()’ of the object returned by nilearn.datasets.fetch_development_fmri

  • Look at the “reference” section of the documentation: there is a function to compute the mean of a 4D image

  • To perform a for loop in Python, you can use the “range” function

  • The solution can be found here


Tutorials to learn the basics

The two following tutorials may be useful to get familiar with data representation in nilearn:

More tutorials can be found here

Now, if you want out-of-the-box methods to process neuroimaging data, jump directly to the section you need:


1.3.2. Scientific computing with Python

In case you plan to become a casual nilearn user, note that you will not need to deal with number and array manipulation directly in Python. However, if you plan to go beyond that, here are a few pointers.

1.3.2.1. Basic numerics

Numerical arrays

The numerical data (e.g. matrices) are stored in numpy arrays:

>>> import numpy as np
>>> t = np.linspace(1, 10, 2000)  # 2000 points between 1 and 10
>>> t
array([  1.        ,   1.00450225,   1.0090045 , ...,   9.9909955 ,
         9.99549775,  10.        ])
>>> t / 2
array([ 0.5       ,  0.50225113,  0.50450225, ...,  4.99549775,
        4.99774887,  5.        ])
>>> np.cos(t) # Operations on arrays are defined in the numpy module
array([ 0.54030231,  0.53650833,  0.53270348, ..., -0.84393609,
       -0.84151234, -0.83907153])
>>> t[:3] # In Python indexing is done with [] and starts at zero
array([ 1.        ,  1.00450225,  1.0090045 ])

More documentation …

Plotting and figures
_images/sphx_glr_plot_python_101_001.png 
>>> import matplotlib.pyplot as plt
>>> plt.plot(t, np.cos(t))       
[<matplotlib.lines.Line2D object at ...>]

More documentation …

Image processing
>>> from scipy import ndimage
>>> t_smooth = ndimage.gaussian_filter(t, sigma=2)

More documentation …

Signal processing
>>> from scipy import signal
>>> t_detrended = signal.detrend(t)

More documentation …

Much more

  • Simple statistics:

    >>> from scipy import stats

  • Linear algebra:

    >>> from scipy import linalg

More documentation…

1.3.2.2. Scikit-learn: machine learning in Python

What is scikit-learn?

Scikit-learn is a Python library for machine learning. Its strong points are:

  • Easy to use and well documented

  • Computationally efficient

  • Provides a wide variety of standard machine learning methods for non-experts

The core concept in scikit-learn is the estimator object, for instance an SVC (support vector classifier). It is first created with the relevant parameters:

>>> import sklearn; sklearn.set_config(print_changed_only=False)
>>> from sklearn.svm import SVC
>>> svc = SVC(kernel='linear', C=1.)

These parameters are detailed in the documentation of the object: in IPython or Jupter you can do:

In [3]: SVC?
...
Parameters
----------
C : float or None, optional (default=None)
    Penalty parameter C of the error term. If None then C is set
    to n_samples.

kernel : string, optional (default='rbf')
    Specifies the kernel type to be used in the algorithm.
    It must be one of 'linear', 'poly', 'rbf', 'sigmoid', 'precomputed'.
    If none is given, 'rbf' will be used.
...

Once the object is created, you can fit it on data. For instance, here we use a hand-written digits dataset, which comes with scikit-learn:

>>> from sklearn import datasets
>>> digits = datasets.load_digits()
>>> data = digits.data
>>> labels = digits.target

Let’s use all but the last 10 samples to train the SVC:

>>> svc.fit(data[:-10], labels[:-10])   
SVC(C=1.0, ...)

and try predicting the labels on the left-out data:

>>> svc.predict(data[-10:])     
array([5, 4, 8, 8, 4, 9, 0, 8, 9, 8])
>>> labels[-10:]    # The actual labels
array([5, 4, 8, 8, 4, 9, 0, 8, 9, 8])

To find out more, try the scikit-learn tutorials.

1.3.3. Finding help

Reference material

  • A quick and gentle introduction to scientific computing with Python can be found in the scipy lecture notes.

  • The documentation of scikit-learn explains each method with tips on practical use and examples: http://scikit-learn.org/. While not specific to neuroimaging, it is often a recommended read. Be careful to consult the documentation of the scikit-learn version that you are using.

Mailing lists and forums