User guide

Note

You can download the user guide and examples for offline viewing.

This user guide is especially directed towards grad students with a background in computer science, machine learning, computational biology or neuroscience. However, less or more advanced readers can also find interesting pieces of information throughout the guide.

Table of contents

• 1. Introduction
  • 1.1. What is nilearn?
  • 1.2. Using nilearn for the first time
    • 1.2.1. First steps with nilearn
    • 1.2.2. Learning with the API references
    • 1.2.3. Learning with examples
    • 1.2.4. Finding help
  • 1.3. Machine learning applications to Neuroimaging
• 2. Decoding and MVPA: predicting from brain images
  • 2.1. An introduction to decoding
    • 2.1.1. Loading and preparing the data
      • 2.1.1.1. The Haxby 2001 experiment
      • 2.1.1.2. Loading the data into nilearn
    • 2.1.2. Performing a simple decoding analysis
      • 2.1.2.1. A few definitions
      • 2.1.2.2. A first estimator
      • 2.1.2.3. Decoding made easy
      • 2.1.2.4. Measuring prediction performance
        • 2.1.2.4.1. Cross-validation
        • 2.1.2.4.2. Choosing a good cross-validation strategy
        • 2.1.2.4.3. Choice of the prediction accuracy measure
        • 2.1.2.4.4. Prediction accuracy at chance using simple strategies
      • 2.1.2.5. Visualizing the decoder’s weights
    • 2.1.3. Decoding without a mask: Anova-SVM
      • 2.1.3.1. Dimension reduction with feature selection
      • 2.1.3.2. Visualizing the results
  • 2.2. Choosing the right predictive model for neuroimaging
    • 2.2.1. Predictions: regression, classification and multi-class
      • 2.2.1.1. Regression
      • 2.2.1.2. Classification: two classes or multi-class
    • 2.2.2. Different linear models
    • 2.2.3. Setting estimator parameters
    • 2.2.4. Bagging several models
    • 2.2.5. References
  • 2.3. FREM: fast ensembling of regularized models for robust decoding
    • 2.3.1. FREM pipeline
    • 2.3.2. Empirical comparisons
      • 2.3.2.1. Decoding performance increase on Haxby dataset
      • 2.3.2.2. Spatial regularization of decoding maps on mixed gambles study
    • 2.3.3. References
  • 2.4. SpaceNet: decoding with spatial structure for better maps
    • 2.4.1. The SpaceNet decoder
    • 2.4.2. Related example
    • 2.4.3. References
  • 2.5. Searchlight : finding voxels containing information
    • 2.5.1. Principle of the Searchlight
    • 2.5.2. Preparing the data
      • 2.5.2.1. Masking
    • 2.5.3. Setting up the searchlight
      • 2.5.3.1. Classifier
      • 2.5.3.2. Score function
      • 2.5.3.3. Cross validation
      • 2.5.3.4. Sphere radius
    • 2.5.4. Visualization
      • 2.5.4.1. Searchlight
      • 2.5.4.2. Comparing to massively univariate analysis: F_score or SPM
    • 2.5.5. References
  • 2.6. Running scikit-learn functions for more control on the analysis
    • 2.6.1. Performing decoding with scikit-learn
      • 2.6.1.1. Using scikit-learn estimators
      • 2.6.1.2. Cross-validation with scikit-learn
      • 2.6.1.3. Measuring the chance level
    • 2.6.2. Going further with scikit-learn
      • 2.6.2.1. Decoding without a mask: Anova-SVM using scikit-learn
      • 2.6.2.2. Using any other model in the pipeline
    • 2.6.3. Setting estimator parameters
• 3. Functional connectivity and resting state
  • 3.1. Extracting times series to build a functional connectome
    • 3.1.1. Time-series from a brain parcellation or “MaxProb” atlas
      • 3.1.1.1. Brain parcellations
      • 3.1.1.2. Extracting signals on a parcellation
    • 3.1.2. Time-series from a probabilistic atlas
      • 3.1.2.1. Probabilistic atlases
      • 3.1.2.2. Extracting signals from a probabilistic atlas
    • 3.1.3. A functional connectome: a graph of interactions
    • 3.1.4. A functional connectome: extracting coordinates of regions
  • 3.2. Connectome extraction: inverse covariance for direct connections
    • 3.2.1. Sparse inverse covariance for functional connectomes
    • 3.2.2. Sparse inverse covariance on multiple subjects
    • 3.2.3. Comparing the different approaches on simulated data
    • 3.2.4. Linking total and direct interactions at the group level
  • 3.3. Extracting functional brain networks: ICA and related
    • 3.3.1. Multi-subject ICA: CanICA
      • 3.3.1.1. Objective
      • 3.3.1.2. Fitting CanICA model with nilearn
      • 3.3.1.3. Visualizing results
      • 3.3.1.4. Interpreting such components
    • 3.3.2. An alternative to ICA: Dictionary learning
  • 3.4. Region Extraction for better brain parcellations
    • 3.4.1. Fetching movie-watching based functional datasets
    • 3.4.2. Brain maps using Dictionary learning
    • 3.4.3. Visualization of Dictionary learning maps
    • 3.4.4. Region Extraction with Dictionary learning maps
    • 3.4.5. Visualization of Region Extraction results
    • 3.4.6. Computing functional connectivity matrices
    • 3.4.7. Visualization of functional connectivity matrices
    • 3.4.8. Validating results
  • 3.5. Clustering to parcellate the brain in regions
    • 3.5.1. Data loading: movie-watching data
    • 3.5.2. Applying clustering
    • 3.5.3. Using and visualizing the resulting parcellation
      • 3.5.3.1. Visualizing the parcellation
      • 3.5.3.2. Compressed representation
• 4. Plotting brain images
  • 4.1. Different plotting functions
  • 4.2. Different display modes
  • 4.3. Available Colormaps
  • 4.4. Adding overlays, edges, contours, contour fillings, markers, scale bar
  • 4.5. Displaying or saving to an image file
  • 4.6. Surface plotting
  • 4.7. Interactive plots
    • 4.7.1. 3D Plots of statistical maps or atlases on the cortical surface
      • 4.7.1.1. view_img_on_surf: Surface plot using a 3D statistical map
      • 4.7.1.2. view_surf: Surface plot using a surface map and a cortical mesh
      • 4.7.1.3. plot_surf_stat_map: Surface plot using a surface map and a cortical mesh
    • 4.7.2. 3D Plots of connectomes
    • 4.7.3. 3D Plots of markers
    • 4.7.4. Interactive visualization of statistical map slices
• 5. Analyzing fMRI using GLMs
  • 5.1. An introduction to GLMs in fMRI statistical analysis
    • 5.1.1. A primer on BOLD-fMRI data analysis
      • 5.1.1.1. What is fMRI ?
      • 5.1.1.2. fMRI data modelling
      • 5.1.1.3. fMRI statistical analysis
      • 5.1.1.4. Multiple Comparisons
  • 5.2. First level models
    • 5.2.1. HRF models
    • 5.2.2. Design matrix: event-based and time series-based
      • 5.2.2.1. Event-based
      • 5.2.2.2. Time series-based
    • 5.2.3. Fitting a first level model
      • 5.2.3.1. Computing contrasts
    • 5.2.4. Extracting predicted time series and residuals
    • 5.2.5. Surface-based analysis
  • 5.3. Second level models
    • 5.3.1. Fitting a second level model
    • 5.3.2. Thresholding statistical maps
    • 5.3.3. Multiple comparisons correction
    • 5.3.4. Voxel based morphometry
• 6. Manipulation brain volumes with nilearn
  • 6.1. Input and output: neuroimaging data representation
    • 6.1.1. Inputing data: file names or image objects
      • 6.1.1.1. File names and objects, 3D and 4D images
      • 6.1.1.2. File name matching: “globbing” and user path expansion
    • 6.1.2. Fetching open datasets from Internet
    • 6.1.3. Understanding neuroimaging data
      • 6.1.3.1. Nifti and Analyze data
      • 6.1.3.2. Niimg-like objects
      • 6.1.3.3. Text files: phenotype or behavior
  • 6.2. Manipulating images: resampling, smoothing, masking, ROIs…
    • 6.2.1. Functions for data preparation and image transformation
    • 6.2.2. Resampling images
      • 6.2.2.1. Resampling one image to match another one
      • 6.2.2.2. Resampling to a specific target affine, shape, or resolution
    • 6.2.3. Accessing individual volumes in 4D images
    • 6.2.4. Computing and applying spatial masks
      • 6.2.4.1. Extracting a brain mask
      • 6.2.4.2. Masking data: from 4D Nifti images to 2D data arrays
    • 6.2.5. Image operations: creating a ROI mask manually
  • 6.3. From neuroimaging volumes to data matrices: the masker objects
    • 6.3.1. The concept of “masker” objects
    • 6.3.2. NiftiMasker: applying a mask to load time-series
      • 6.3.2.1. Custom data loading: loading only the first 100 time points
      • 6.3.2.2. Controlling how the mask is computed from the data
        • 6.3.2.2.1. Visualizing the computed mask
        • 6.3.2.2.2. Different masking strategies
        • 6.3.2.2.3. Extra mask parameters: opening, cutoff…
      • 6.3.2.3. Common data preparation steps: smoothing, filtering, resampling
        • 6.3.2.3.1. Smoothing
        • 6.3.2.3.2. Temporal Filtering and confound removal
        • 6.3.2.3.3. Resampling: resizing and changing resolutions of images
      • 6.3.2.4. Inverse transform: unmasking data
    • 6.3.3. Extraction of signals from regions: NiftiLabelsMasker, NiftiMapsMasker
      • 6.3.3.1. Regions definition
      • 6.3.3.2. NiftiLabelsMasker Usage
      • 6.3.3.3. NiftiMapsMasker Usage
    • 6.3.4. Extraction of signals from regions for multiple subjects: MultiNiftiMasker, MultiNiftiLabelsMasker, MultiNiftiMapsMasker
      • 6.3.4.1. MultiNiftiMasker Usage
      • 6.3.4.2. MultiNiftiLabelsMasker Usage
      • 6.3.4.3. MultiNiftiMapsMasker Usage
    • 6.3.5. Extraction of signals from seeds: NiftiSpheresMasker
• 7. Advanced usage: manual pipelines and scaling up
  • 7.1. Building your own neuroimaging machine-learning pipeline
    • 7.1.1. Data loading and preprocessing
      • 7.1.1.1. Downloading the data
      • 7.1.1.2. Loading non image data: experiment description
      • 7.1.1.3. Masking the data: from 4D image to 2D array
        • 7.1.1.3.1. Applying a mask
        • 7.1.1.3.2. Automatically computing a mask
    • 7.1.2. Applying a scikit-learn machine learning method
    • 7.1.3. Unmasking (inverse_transform)
    • 7.1.4. Visualizing results
    • 7.1.5. Going further
  • 7.2. Downloading statistical maps from the Neurovault repository
    • 7.2.1. Specific images or collections
    • 7.2.2. Selection filters
    • 7.2.3. Output
    • 7.2.4. Neurosynth annotations
    • 7.2.5. Examples using Neurovault
    • 7.2.6. References