Neurodesk Tools Demo

Shell We Begin?¶

Welcome to this Neurodesk demonstration notebook - a guide to the rich ecosystem of tools, workflows, and visualization strategies available on the Neurodesk platform. From command-line tools and pipelines to modular Python interfaces, this notebook provides an overview of setting up pipelines, running individual processing steps, and inspecting outputs, from shell and cell.

Use this notebook to:

Explore a selection of popular neuroimaging tools (e.g., FSL, AFNI, FreeSurfer, MRIQC)
Learn how to run CLI-based commands, set up workflows, and execute Pythonic processing steps interactively
Visualize outputs and quality control reports directly in the notebook
Navigate to detailed, tool-specific notebooks for deeper exploration

Author: Monika Doerig

Date: 13 June 2025

License:

MIT License

Note: If this notebook uses neuroimaging tools from Neurocontainers, those tools retain their original licenses. Please see Neurodesk citation guidelines for details.

Citation: For clarity and conciseness, references and citations supporting each tool or workflow are included in the linked notebooks themselves.

1. Load software tools and import Python libraries¶

%%capture
!pip install fury==0.11.0 dipy==1.11.0 vtk==9.5.2 pybids==0.19.0 antspyx==0.6.3 nilearn==0.13.1

import os
import nibabel as nib
from scipy import ndimage
import numpy as np
import matplotlib.pyplot as plt
from matplotlib import transforms
import ants
from bids.layout import BIDSLayout, BIDSValidator
from ipyniivue import NiiVue
from IPython.display import Image, display
from IPython.core.display import SVG
from nipype.interfaces import fsl
from nipype.interfaces import afni
from dipy.core.gradients import gradient_table
from dipy.io import read_bvals_bvecs
from dipy.io.image import load_nifti
import dipy.reconst.dti as dti
from dipy.segment.mask import median_otsu
from dipy.data import get_sphere
from dipy.viz import actor, window
from nilearn.image.image import mean_img
from nilearn.plotting import plot_epi, plot_anat, plot_img, plot_roi, view_img

# We can use module to load the different software tools in a specific version
import module
await module.purge()
await module.load('afni/21.2.00')
await module.load('mriqc/24.0.2')
await module.load('ants/2.6.5')
await module.load('bidscoin/4.6.2')
await module.load('freesurfer/8.1.0')
await module.load('mrtrix3/3.0.4')
await module.load('fsl/6.0.7.16')
await module.list()

['afni/21.2.00',
 'mriqc/24.0.2',
 'ants/2.6.5',
 'bidscoin/4.6.2',
 'freesurfer/8.1.0',
 'mrtrix3/3.0.4',
 'fsl/6.0.7.16']

2. Data¶

Access Open Data on OSF Using DataLad¶

Note :This workflow requires the dataset to be available as a DataLad dataset on OSF (i.e. with DataLad metadata and annexed file storage).

# Download one subject of the Brain Tumor Connectomics Data in BIDS Format
PATTERN = "sub-CON02"
! datalad install https://github.com/OpenNeuroDatasets/ds001226.git

! cd ds001226 && datalad get $PATTERN

3. Bits about BIDS¶

BIDS conversion with BIDScoin¶

For more information on BIDS conversion using different software tools, dcm2niix, HeuDiConv, and BIDScoin, see this BIDS conversion example.

BIDScoin workflow: BIDScoin requires that the source data repository follows a subject/[session]/data structure. The data folder can be organized in various DICOM layouts: DICOM series, DICOMDIR, or flat DICOMs.

To perform a BIDS conversion using BIDScoin:

Run bidsmapper with the --automated flag to generate the bidsmap non-interactively (this skips the manual editing step with bidseditor).
Run bidscoiner to convert the data using the generated bidsmap.

#! bidscoin --download .  # Download the tutorial data (use a "." for the current folder or a pathname of choice to save it elsewhere)
# Install phantom dataset generated by the University of Arizona on their Siemens Skyra 3T with Syngo MR VE11c software on 2018_02_08.
! datalad install https://datasets.datalad.org/repronim/heudiconv-reproin-example

# Download only the series needed (anat, fieldmaps, func, localizer - skip DWI)
! cd heudiconv-reproin-example/REPROIN/dicom/001 && datalad get -J 4 \
    "Patterson_Coben - 1/anatT1w_acqMPRAGE_6" \
    "Patterson_Coben - 1/fmap_acq4mm_7" \
    "Patterson_Coben - 1/fmap_acq4mm_8" \
    "Patterson_Coben - 1/func_taskrest_16"

action summary:
  get (notneeded: 4)

! bidsmapper -h

usage: bidsmapper [-h] [-b NAME] [-t NAME] [-p NAME [NAME ...]] [-n PREFIX]
                  [-m PREFIX] [-u PATTERN] [-s] [-a] [-f] [--no-update]
                  sourcefolder bidsfolder

The bidsmapper scans your source data repository to identify different data types by matching
them against the run-items in the template bidsmap. Once a match is found, a mapping to BIDS
output data types is made and the run-item is added to the study bidsmap. You can check and
edit these generated bids-mappings to your needs with the (automatically launched) bidseditor.
Re-run the bidsmapper whenever something was changed in your data acquisition protocol and
edit the new data type to your needs (your existing bidsmap will be reused).

The bidsmapper uses plugins, as stored in the 'Options' section of the bidsmap, to perform
its task and deal with different data modalities and formats.

positional arguments:
  sourcefolder          The study root folder containing the raw source data
                        folders
  bidsfolder            The destination folder with the (future) bids data and
                        the bidsfolder/code/bidscoin/bidsmap.yaml output file

options:
  -h, --help            show this help message and exit
  -b, --bidsmap NAME    The study bidsmap file with the mapping heuristics. If
                        the bidsmap filename is just the base name (i.e. no
                        '/' in the name) then it is assumed to be located in
                        the current directory or in bidsfolder/code/bidscoin.
                        Default: bidsmap.yaml
  -t, --template NAME   The bidsmap template file with the default heuristics
                        (this could be provided by your institute). If the
                        bidsmap filename is just the base name (i.e. no '/' in
                        the name) then it is assumed to be located in the
                        bidscoin config folder. Default: bidsmap_dccn
  -p, --plugins NAME [NAME ...]
                        List of plugins to be used. Default: the plugin list
                        of the study/template bidsmap
  -n, --subprefix PREFIX
                        The prefix common for all the source subject-folders
                        (e.g. 'Pt' is the subprefix if subject folders are
                        named 'Pt018', 'Pt019', ...). Use '*' when your
                        subject folders do not have a prefix. Default: the
                        value of the study/template bidsmap, e.g. 'sub-'
  -m, --sesprefix PREFIX
                        The prefix common for all the source session-folders
                        (e.g. 'M_' is the subprefix if session folders are
                        named 'M_pre', 'M_post', ..). Use '*' when your
                        session folders do not have a prefix. Default: the
                        value of the study/template bidsmap, e.g. 'ses-'
  -u, --unzip PATTERN   Wildcard pattern to unpack tarball/zip-files in the
                        sub/ses sourcefolder that need to be unzipped (in a
                        tempdir) to make the data readable. Default: the value
                        of the study/template bidsmap
  -s, --store           Store newly discovered data samples in the
                        bidsfolder/code/provenance folder (useful for editing
                        e.g. zipped or DICOMDIR datasets)
  -a, --automated       Save the automatically generated bidsmap to disk and
                        without interactively tweaking it with the bidseditor
  -f, --force           Discard the previously saved bidsmap and log file,
                        instead of reusing them (use this option for a fresh
                        start)
  --no-update           Do not update any sub-/ses-prefixes in or prepend the
                        sourcefolder name to the <<filepath:regex>> expression
                        that extracts the subject/session labels. This is
                        normally done to make the extraction more robust, but
                        could cause problems for certain use cases

examples:
  bidsmapper myproject/raw myproject/bids
  bidsmapper myproject/raw myproject/bids -t bidsmap_custom  # Uses a template bidsmap of choice
  bidsmapper myproject/raw myproject/bids -p nibabel2bids    # Uses a plugin of choice
  bidsmapper myproject/raw myproject/bids -n patient- -m '*' # Handles DICOMDIR datasets
  bidsmapper myproject/raw myproject/bids -u '*.tar.gz'      # Unzip tarball source files

! mkdir -p ./bidscoin_bids
! bidsmapper ./heudiconv-reproin-example/REPROIN/dicom ./bidscoin_bids \
  --subprefix '0' --sesprefix 'Patterson_Coben' --automated
! bidscoiner ./heudiconv-reproin-example/REPROIN/dicom ./bidscoin_bids

INFO                                                                            
INFO     -------------- START BIDSmapper ------------                           
INFO     >>> bidsmapper                                                         
         sourcefolder=/home/jovyan/workspace/books/examples/workflows/heudiconv-
         reproin-example/REPROIN/dicom                                          
         bidsfolder=/home/jovyan/workspace/books/examples/workflows/bidscoin_bid
         s bidsmap=bidsmap.yaml                                                 
         template=/home/jovyan/.bidscoin/4.6.2/templates/bidsmap_dccn.yaml      
         plugins=[] subprefix=0 sesprefix=Patterson_Coben store=False           
         force=False                                                            
INFO     Reading:                                                               
         /home/jovyan/workspace/books/examples/workflows/bidscoin_bids/code/bids
         coin/bidsmap.yaml                                                      
INFO     Checking the bidsmap run-items:                                        
SUCCESS  All run-items in the bidsmap are valid                                 
INFO     Reading: /home/jovyan/.bidscoin/4.6.2/templates/bidsmap_dccn.yaml      
INFO     Checking the bidsmap run-items:                                        
SUCCESS  All datatypes and options in the template bidsmap are valid            
INFO     Mapping:                                                               
         /home/jovyan/workspace/books/examples/workflows/heudiconv-reproin-examp
         le/REPROIN/dicom/001/Patterson_Coben - 1 (subject 1/1)                 
Subjects ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
INFO     Checking the bidsmap run-items:                                        
SUCCESS  All run-items in the bidsmap are valid                                 
INFO     Saving bidsmap in:                                                     
         /home/jovyan/workspace/books/examples/workflows/bidscoin_bids/code/bids
         coin/bidsmap.yaml                                                      
INFO     -------------- FINISHED! -------------------                           
INFO                                                                            
SUCCESS  No BIDScoin errors or warnings were reported                           
INFO                                                                            
INFO     For the complete detailed log see:                                     
         /home/jovyan/workspace/books/examples/workflows/bidscoin_bids/code/bids
         coin/bidsmapper.log                                                    
         NB: That folder may contain privacy sensitive information, e.g.        
         pathnames in logfiles and provenance data samples                      
INFO                                                                            
INFO     -------------- START BIDScoiner 4.6.2: BIDS 1.10.0 ------------        
INFO     >>> bidscoiner                                                         
         sourcefolder=/home/jovyan/workspace/books/examples/workflows/heudiconv-
         reproin-example/REPROIN/dicom                                          
         bidsfolder=/home/jovyan/workspace/books/examples/workflows/bidscoin_bid
         s participant=None force=False bidsmap=bidsmap.yaml                    
INFO     Reading:                                                               
         /home/jovyan/workspace/books/examples/workflows/bidscoin_bids/code/bids
         coin/bidsmap.yaml                                                      
INFO     Checking the bidsmap run-items:                                        
SUCCESS  All run-items in the bidsmap are valid                                 
INFO     ------------------- Subject 1/1 -------------------                    
INFO     >>> Skipping dcm2niix2bids processing:                                 
         /home/jovyan/workspace/books/examples/workflows/bidscoin_bids/sub-01/se
         s-1 already contains {'func', 'fmap', 'anat'} data. Use the -f option  
         to force processing if needed.                                         
INFO     >>> No events2bids datasources found in                                
         '/home/jovyan/workspace/books/examples/workflows/heudiconv-reproin-exam
         ple/REPROIN/dicom/001/Patterson_Coben - 1'                             
WARNING  Empty IntendedFor/B0FieldSource/B0FieldIdentifier values in            
         fmap/sub-01_ses-1_acq-fmapacq4mm_magnitude1.json (i.e. the field map   
         may not be used)                                                       
WARNING  Empty IntendedFor/B0FieldSource/B0FieldIdentifier values in            
         fmap/sub-01_ses-1_acq-fmapacq4mm_magnitude2.json (i.e. the field map   
         may not be used)                                                       
WARNING  Empty IntendedFor/B0FieldSource/B0FieldIdentifier values in            
         fmap/sub-01_ses-1_acq-fmapacq4mm_phasediff.json (i.e. the field map may
         not be used)                                                           
Subjects ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
INFO     -------------- FINISHED! ------------                                  
INFO                                                                            
INFO     The following BIDScoin errors and warnings were reported:              
                                                                                
         >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>                               
         2026-07-08 09:52:55 - WARNING | Empty                                  
         IntendedFor/B0FieldSource/B0FieldIdentifier values in                  
         fmap/sub-01_ses-1_acq-fmapacq4mm_magnitude1.json (i.e. the field map   
         may not be used)                                                       
         2026-07-08 09:52:55 - WARNING | Empty                                  
         IntendedFor/B0FieldSource/B0FieldIdentifier values in                  
         fmap/sub-01_ses-1_acq-fmapacq4mm_magnitude2.json (i.e. the field map   
         may not be used)                                                       
         2026-07-08 09:52:55 - WARNING | Empty                                  
         IntendedFor/B0FieldSource/B0FieldIdentifier values in                  
         fmap/sub-01_ses-1_acq-fmapacq4mm_phasediff.json (i.e. the field map may
         not be used)                                                           
         <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<                               
                                                                                
INFO     For the complete detailed log see:                                     
         /home/jovyan/workspace/books/examples/workflows/bidscoin_bids/code/bids
         coin/bidscoiner.log                                                    
         NB: That folder may contain privacy sensitive information, e.g.        
         pathnames in logfiles and provenance data samples

! tree -L 3 ./bidscoin_bids

./bidscoin_bids
├── README
├── code
│   └── bidscoin
│       ├── bidscoiner.errors
│       ├── bidscoiner.log
│       ├── bidscoiner.tsv
│       ├── bidsmap.yaml
│       ├── bidsmapper.errors
│       └── bidsmapper.log
├── dataset_description.json
├── participants.json
├── participants.tsv
└── sub-01
    └── ses-1
        ├── anat
        ├── fmap
        ├── func
        └── sub-01_ses-1_scans.tsv

8 directories, 11 files

pyBIDS¶

PyBIDS is a Python package that makes it easier to query, summarize, and manage BIDS-formatted datasets. It integrates smoothly with neuroimaging tools like Nipype and Nilearn, which support the BIDS standard natively. Here, you’ll finda more comprehensive example.

BIDSLayout¶

layout = BIDSLayout("./bidscoin_bids")

all_files = layout.get()
print("There are {} files in the layout.".format(len(all_files)))
print("\nThe first 3 files are:")
all_files[:5]

There are 15 files in the layout.

The first 3 files are:

[<BIDSJSONFile filename='/home/jovyan/workspace/books/examples/workflows/bidscoin_bids/dataset_description.json'>,
 <BIDSJSONFile filename='/home/jovyan/workspace/books/examples/workflows/bidscoin_bids/participants.json'>,
 <BIDSDataFile filename='/home/jovyan/workspace/books/examples/workflows/bidscoin_bids/participants.tsv'>,
 <BIDSFile filename='/home/jovyan/workspace/books/examples/workflows/bidscoin_bids/README'>,
 <BIDSJSONFile filename='/home/jovyan/workspace/books/examples/workflows/bidscoin_bids/sub-01/ses-1/anat/sub-01_ses-1_acq-anatT1wacqMPRAGE_T1w.json'>]

# Retrieve filenames of all BOLD runs for subject 01
bold_run = layout.get(subject='01', suffix='bold', extension='nii.gz', return_type='filename')
bold_run

['/home/jovyan/workspace/books/examples/workflows/bidscoin_bids/sub-01/ses-1/func/sub-01_ses-1_task-functaskrest_dir-AP_bold.nii.gz']

layout.get_task()

['functaskrest']

The BIDSFile¶

# Pick the 11th file in the dataset
bf = layout.get()[11]

# Print it
bf

<BIDSImageFile filename='/home/jovyan/workspace/books/examples/workflows/bidscoin_bids/sub-01/ses-1/fmap/sub-01_ses-1_acq-fmapacq4mm_phasediff.nii.gz'>

bf.get_entities()

{'acquisition': 'fmapacq4mm',
 'datatype': 'fmap',
 'extension': '.nii.gz',
 'fmap': 'phasediff',
 'session': '1',
 'subject': '01',
 'suffix': 'phasediff'}

# Print all metadata of this file
bf.get_metadata()

{'AcquisitionMatrixPE': 64,
 'AcquisitionNumber': 1,
 'AcquisitionTime': '14:36:16.837500',
 'BaseResolution': 64,
 'BidsGuess': ['fmap', '_acq-fm2_phasediff'],
 'BodyPart': 'BRAIN',
 'CoilCombinationMethod': 'Sum of Squares',
 'ConsistencyInfo': 'N4_VE11C_LATEST_20160120',
 'ConversionSoftware': 'dcm2niix',
 'ConversionSoftwareVersion': 'v1.0.20250505',
 'DeviceSerialNumber': '45424',
 'DwellTime': 2.6e-05,
 'EchoNumber': 2,
 'EchoTime': 0.00738,
 'EchoTime1': 0.00492,
 'EchoTime2': 0.00738,
 'FlipAngle': 90,
 'ImageOrientationPatientDICOM': [0.993872,
  -0.109373,
  -0.0159882,
  0.108671,
  0.940376,
  0.322311],
 'ImageOrientationText': 'Tra>Cor(18.8)>Sag(1.2)',
 'ImageType': ['ORIGINAL', 'PRIMARY', 'P', 'ND', 'PHASE'],
 'ImagingFrequency': 123.238285,
 'InPlanePhaseEncodingDirectionDICOM': 'COL',
 'InstitutionName': 'University of Arizona',
 'InstitutionalDepartmentName': 'Department',
 'MRAcquisitionType': '2D',
 'MagneticFieldStrength': 3,
 'Manufacturer': 'Siemens',
 'ManufacturersModelName': 'Skyra',
 'MatrixCoilMode': 'SENSE',
 'Modality': 'MR',
 'MultibandAccelerationFactor': 2,
 'NonlinearGradientCorrection': False,
 'PartialFourier': 1,
 'PatientPosition': 'HFS',
 'PercentPhaseFOV': 100,
 'PercentSampling': 100,
 'PhaseEncodingDirection': 'j-',
 'PhaseEncodingSteps': 64,
 'PhaseResolution': 1,
 'PixelBandwidth': 300,
 'ProcedureStepDescription': 'Patterson^Coben',
 'ProtocolName': 'fmap_acq-4mm',
 'PulseSequenceDetails': '%SiemensSeq%\\gre_field_mapping',
 'ReceiveCoilActiveElements': 'HEA;HEP',
 'ReceiveCoilName': 'Head_32',
 'ReconMatrixPE': 64,
 'RepetitionTime': 0.625,
 'SAR': 0.102569,
 'ScanningSequence': 'GR',
 'SequenceName': '*fm2d2r',
 'SequenceVariant': 'SP',
 'SeriesDescription': 'fmap_acq-4mm',
 'SeriesNumber': 8,
 'ShimSetting': [7588, -13970, 14323, -207, 396, -603, -378, -103],
 'SliceThickness': 4,
 'SliceTiming': [0,
  0,
  0.01562,
  0.03125,
  0.04688,
  0.0625,
  0.07812,
  0.09375,
  0.10938,
  0.125,
  0.14062,
  0.15625,
  0.15625,
  0.17188,
  0.1875,
  0.20312,
  0.21875,
  0.23438,
  0.25,
  0.26562,
  0.28125,
  0.29688,
  0.3125,
  0.3125,
  0.32812,
  0.34375,
  0.35938,
  0.375,
  0.39062,
  0.40625,
  0.42188,
  0.4375,
  0.45312,
  0.46875,
  0.46875,
  0.48438,
  0.5,
  0.51562,
  0.53125,
  0.54688,
  0.5625,
  0.57812,
  0.59375,
  0.60938],
 'SoftwareVersions': 'syngo MR E11',
 'SpacingBetweenSlices': 4,
 'StationName': 'AWP45424',
 'StudyDescription': 'Patterson^Coben',
 'TablePosition': [0, 0, -36],
 'TxRefAmp': 219.681}

The BIDSValidator¶

# When using the bids validator, the filepath MUST be relative to the top level bids directory
validator = BIDSValidator()
validator.is_bids('/sub-01/ses-1/anat/sub-01_ses-1_acq-anatT1wacqMPRAGE_T1w.nii.gz')

True

4. Toolbox Tour¶

4.1. Workflows¶

Several neuroimaging tools provide streamlined, reproducible pipelines that build on widely used software packages such as FSL, AFNI, ANTs, and SPM. Some notable examples, like fMRIPrep and MRIQC, are high-level, preconfigured pipelines built on Nipype, a flexible Python workflow engine designed for creating custom neuroimaging processing chains.

fMRIPrep: A Preprocessing Pipeline for fMRI Data¶

fMRIPrep offers a robust BIDS-compatible pipeline for preprocessing fMRI data with minimal manual intervention, as demonstrated in the fMRIPrep example notebook.

MRIQC: Quality control¶

MRIQC provides automated quality assessment metrics for structural and functional MRI data, generating comprehensive reports to identify potential issues before analysis. For a complete walkthrough and more detailed example, see the full MRIQC example.

!mriqc --help

usage: mriqc [-h] [--version] [-v] [--species {human,rat}]
             [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
             [--bids-filter-file PATH] [--session-id [SESSION_ID ...]]
             [--run-id [RUN_ID ...]] [--task-id [TASK_ID ...]]
             [-m [{T1w,T2w,bold,dwi} ...]] [--dsname DSNAME]
             [--bids-database-dir PATH] [--bids-database-wipe]
             [--no-datalad-get] [--nprocs NPROCS]
             [--omp-nthreads OMP_NTHREADS] [--mem MEMORY_GB] [--testing] [-f]
             [--pdb] [-w WORK_DIR] [--verbose-reports] [--reports-only]
             [--write-graph] [--dry-run] [--resource-monitor]
             [--use-plugin USE_PLUGIN] [--crashfile-format {txt,pklz}]
             [--no-sub] [--email EMAIL] [--webapi-url WEBAPI_URL]
             [--webapi-port WEBAPI_PORT] [--upload-strict] [--notrack]
             [--ants-float] [--ants-settings ANTS_SETTINGS]
             [--min-dwi-length MIN_LEN_DWI] [--min-bold-length MIN_LEN_BOLD]
             [--fft-spikes-detector] [--fd_thres FD_THRES] [--deoblique]
             [--despike] [--start-idx START_IDX] [--stop-idx STOP_IDX]
             bids_dir output_dir {participant,group} [{participant,group} ...]

MRIQC 24.1.0.dev0+gd5b13cb5.d20240826 Automated Quality Control and visual
reports for Quality Assessment of structural (T1w, T2w) and functional MRI of
the brain. IMPORTANT: Anonymized quality metrics (IQMs) will be submitted to
MRIQC's metrics repository. Submission of IQMs can be disabled using the
``--no-sub`` argument. Please visit
https://mriqc.readthedocs.io/en/latest/dsa.html to revise MRIQC's Data Sharing
Agreement.

positional arguments:
  bids_dir              The root folder of a BIDS valid dataset (sub-XXXXX
                        folders should be found at the top level in this
                        folder).
  output_dir            The directory where the output files should be stored.
                        If you are running group level analysis this folder
                        should be prepopulated with the results of the
                        participant level analysis.
  {participant,group}   Level of the analysis that will be performed. Multiple
                        participant level analyses can be run independently
                        (in parallel) using the same output_dir.

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -v, --verbose         Increases log verbosity for each occurrence, debug
                        level is -vvv. (default: 0)
  --species {human,rat}
                        Use appropriate template for population (default:
                        human)

Options for filtering BIDS queries:
  --participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], --participant-labels PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], --participant_labels PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
                        A space delimited list of participant identifiers or a
                        single identifier (the sub- prefix can be removed).
                        (default: None)
  --bids-filter-file PATH
                        a JSON file describing custom BIDS input filter using
                        pybids {<suffix>:{<entity>:<filter>,...},...}
                        (https://github.com/bids-standard/pybids/blob/master/b
                        ids/layout/config/bids.json) (default: None)
  --session-id [SESSION_ID ...]
                        Filter input dataset by session ID. (default: None)
  --run-id [RUN_ID ...]
                        DEPRECATED - This argument will be disabled. Use
                        ``--bids-filter-file`` instead. (default: None)
  --task-id [TASK_ID ...]
                        Filter input dataset by task ID. (default: None)
  -m [{T1w,T2w,bold,dwi} ...], --modalities [{T1w,T2w,bold,dwi} ...]
                        Filter input dataset by MRI type. (default: ('T1w',
                        'T2w', 'bold', 'dwi'))
  --dsname DSNAME       A dataset name. (default: None)
  --bids-database-dir PATH
                        Path to an existing PyBIDS database folder, for faster
                        indexing (especially useful for large datasets).
                        (default: None)
  --bids-database-wipe  Wipe out previously existing BIDS indexing caches,
                        forcing re-indexing. (default: False)
  --no-datalad-get      Disable attempting to get remote files in DataLad
                        datasets. (default: True)

Options to handle performance:
  --nprocs NPROCS, --n_procs NPROCS, --n_cpus NPROCS, -n-cpus NPROCS
                        Maximum number of simultaneously running parallel
                        processes executed by *MRIQC* (e.g., several instances
                        of ANTs' registration). However, when ``--nprocs`` is
                        greater or equal to the ``--omp-nthreads`` option, it
                        also sets the maximum number of threads that
                        simultaneously running processes may aggregate
                        (meaning, with ``--nprocs 16 --omp-nthreads 8`` a
                        maximum of two 8-CPU-threaded processes will be
                        running at a given time). Under this mode of
                        operation, ``--nprocs`` sets the maximum number of
                        processors that can be assigned work within an *MRIQC*
                        job, which includes all the processors used by
                        currently running single- and multi-threaded
                        processes. If ``None``, the number of CPUs available
                        will be automatically assigned (which may not be what
                        you want in, e.g., shared systems like a HPC cluster.
                        (default: None)
  --omp-nthreads OMP_NTHREADS, --ants-nthreads OMP_NTHREADS
                        Maximum number of threads that multi-threaded
                        processes executed by *MRIQC* (e.g., ANTs'
                        registration) can use. If ``None``, the number of CPUs
                        available will be automatically assigned (which may
                        not be what you want in, e.g., shared systems like a
                        HPC cluster. (default: None)
  --mem MEMORY_GB, --mem_gb MEMORY_GB, --mem-gb MEMORY_GB
                        Upper bound memory limit for MRIQC processes.
                        (default: None)
  --testing             Use testing settings for a minimal footprint.
                        (default: False)
  -f, --float32         Cast the input data to float32 if it's represented in
                        higher precision (saves space and improves
                        performance). (default: True)
  --pdb                 Open Python debugger (pdb) on exceptions. (default:
                        False)

Instrumental options:
  -w WORK_DIR, --work-dir WORK_DIR
                        Path where intermediate results should be stored.
                        (default:
                        /home/jovyan/workspace/books/examples/workflows/work)
  --verbose-reports
  --reports-only
  --write-graph         Write workflow graph. (default: False)
  --dry-run             Do not run the workflow. (default: False)
  --resource-monitor, --profile
                        Hook up the resource profiler callback to nipype.
                        (default: False)
  --use-plugin USE_PLUGIN
                        Nipype plugin configuration file. (default: None)
  --crashfile-format {txt,pklz}
                        Nipype crashfile format (default: txt)
  --no-sub              Turn off submission of anonymized quality metrics to
                        MRIQC's metrics repository. (default: False)
  --email EMAIL         Email address to include with quality metric
                        submission. (default: )
  --webapi-url WEBAPI_URL
                        IP address where the MRIQC WebAPI is listening.
                        (default: None)
  --webapi-port WEBAPI_PORT
                        Port where the MRIQC WebAPI is listening. (default:
                        None)
  --upload-strict       Upload will fail if upload is strict. (default: False)
  --notrack             Opt-out of sending tracking information of this run to
                        the NiPreps developers. This information helps to
                        improve MRIQC and provides an indicator of real world
                        usage crucial for obtaining funding. (default: False)

Specific settings for ANTs:
  --ants-float          Use float number precision on ANTs computations.
                        (default: False)
  --ants-settings ANTS_SETTINGS
                        Path to JSON file with settings for ANTs. (default:
                        None)

Diffusion MRI workflow configuration:
  --min-dwi-length MIN_LEN_DWI
                        Drop DWI runs with fewer orientations than this
                        threshold. (default: 7)

Functional MRI workflow configuration:
  --min-bold-length MIN_LEN_BOLD
                        Drop BOLD runs with fewer time points than this
                        threshold. (default: 5)
  --fft-spikes-detector
                        Turn on FFT based spike detector (slow). (default:
                        False)
  --fd_thres FD_THRES   Threshold on framewise displacement estimates to
                        detect outliers. (default: 0.2)
  --deoblique           Deoblique the functional scans during head motion
                        correction preprocessing. (default: False)
  --despike             Despike the functional scans during head motion
                        correction preprocessing. (default: False)
  --start-idx START_IDX
                        DEPRECATED Initial volume in functional timeseries
                        that should be considered for preprocessing. (default:
                        None)
  --stop-idx STOP_IDX   DEPRECATED Final volume in functional timeseries that
                        should be considered for preprocessing. (default:
                        None)

%%bash
# Set the number of threads for ITK (Image Processing Toolkit) to use
export ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=6
# Set the directory for matplotlib configuration to avoid conflicts
export MPLCONFIGDIR=~/matplotlib-mpldir

# Run MRIQC
mriqc ds001226 \
        MRIQC \
        participant \
        --participant-label sub-CON02 \
        --no-sub \
        --work-dir MRIQC_workdir \
        --nprocs 10 \
        --mem-gb 10 \
        --verbose-reports \
        -v

Fetching long content....

The carpet plot offers a compact way to visualize voxel-wise fMRI signal changes over time, allowing quick identification of artifacts, motion spikes, or other irregularities in the data. Each row corresponds to a voxel (or a group of voxels), and each column represents a time point, effectively summarizing the entire 4D dataset in a single image.

Here’s an example of a carpet plot generated by MRIQC for subject sub-CON02 during the resting-state session:

SVG(filename='./MRIQC/sub-CON02/figures/sub-CON02_ses-preop_task-rest_desc-carpet_bold.svg')

4.2 Core Neuroimaging Tools (Command-Line Interfaces)¶

The following tools are widely used in neuroimaging research and are typically run from the command line. They support key tasks in structural, functional, and diffusion imaging workflows. Many are integrated into higher-level toolkits like Nipype or fMRIPrep.

# create an output directory
!mkdir -p output

FreeSurfer’s SynthStrip: Brain extraction of the anatomical image¶

Another interactive example can be found here: recon-all

# SynthStrip
! mri_synthstrip -i ./ds001226/sub-CON02/ses-preop/anat/sub-CON02_ses-preop_T1w.nii.gz -o ./output/synth_stripped.nii.gz -m ./output/synth_mask.nii.gz

Configuring model on the CPU
Running SynthStrip model version 1
Input image read from: ./ds001226/sub-CON02/ses-preop/anat/sub-CON02_ses-preop_T1w.nii.gz
Processing frame (of 1): 1 done
Masked image saved to: ./output/synth_stripped.nii.gz
Binary brain mask saved to: ./output/synth_mask.nii.gz

If you use SynthStrip in your analysis, please cite:
----------------------------------------------------
SynthStrip: Skull-Stripping for Any Brain Image
A Hoopes, JS Mora, AV Dalca, B Fischl, M Hoffmann
NeuroImage 206 (2022), 119474
https://doi.org/10.1016/j.neuroimage.2022.119474

Website: https://synthstrip.io

AFNI’s 3dvolreg: Motion Correction of functional data¶

For a complete example about preprocessing and glm, have a look at this AFNI Preprocessing and GLM notebook.

# 3dvolreg
! 3dvolreg -verbose -zpad 1 -cubic -base 0 -prefix ./output/epi_volreg.nii.gz  -1Dfile ./output/motion.1D ./ds001226/sub-CON02/ses-preop/func/sub-CON02_ses-preop_task-rest_bold.nii.gz

++ 3dvolreg: AFNI version=AFNI_21.2.00 (Jul  8 2021) [64-bit]
++ Authored by: RW Cox
*+ WARNING:   If you are performing spatial transformations on an oblique dset,
  such as ./ds001226/sub-CON02/ses-preop/func/sub-CON02_ses-preop_task-rest_bold.nii.gz,
  or viewing/combining it with volumes of differing obliquity,
  you should consider running: 
     3dWarp -deoblique 
  on this and  other oblique datasets in the same session.
 See 3dWarp -help for details.
++ Oblique dataset:./ds001226/sub-CON02/ses-preop/func/sub-CON02_ses-preop_task-rest_bold.nii.gz is 8.917687 degrees from plumb.
++ Reading input dataset ./ds001226/sub-CON02/ses-preop/func/sub-CON02_ses-preop_task-rest_bold.nii.gz
++ Edging: x=3 y=3 z=2
++ Creating mask for -maxdisp
 + Automask has 50248 voxels
 + 6670 voxels left in -maxdisp mask after erosion
++ Initializing alignment base
++ Starting final pass on 180 sub-bricks: 0..1..2..3..4..5..6..7..8..9..10..11..12..13..14..15..16..17..18..19..20..21..22..23..24..25..26..27..28..29..30..31..32..33..34..35..36..37..38..39..40..41..42..43..44..45..46..47..48..49..50..51..52..53..54..55..56..57..58..59..60..61..62..63..64..65..66..67..68..69..70..71..72..73..74..75..76..77..78..79..80..81..82..83..84..85..86..87..88..89..90..91..92..93..94..95..96..97..98..99..100..101..102..103..104..105..106..107..108..109..110..111..112..113..114..115..116..117..118..119..120..121..122..123..124..125..126..127..128..129..130..131..132..133..134..135..136..137..138..139..140..141..142..143..144..145..146..147..148..149..150..151..152..153..154..155..156..157..158..159..160..161..162..163..164..165..166..167..168..169..170..171..172..173..174..175..176..177..178..179..
++ CPU time for realignment=0 s  [=0 s/sub-brick]
++ Min : roll=-0.392  pitch=-0.667  yaw=-0.087  dS=-1.333  dL=-0.196  dP=-0.715
++ Mean: roll=-0.183  pitch=-0.191  yaw=+0.040  dS=-0.527  dL=-0.064  dP=-0.354
++ Max : roll=+0.016  pitch=+0.160  yaw=+0.166  dS=+0.086  dL=+0.149  dP=+0.183
++ Max displacements (mm) for each sub-brick:
 0.00(0.00) 0.44(0.44) 0.27(0.39) 0.12(0.23) 0.44(0.37) 0.47(0.19) 0.21(0.45) 0.42(0.42) 0.48(0.15) 0.26(0.40) 0.38(0.50) 0.52(0.15) 0.28(0.49) 0.28(0.29) 0.55(0.34) 0.28(0.45) 0.28(0.19) 0.48(0.36) 0.56(0.13) 0.35(0.38) 0.34(0.27) 0.53(0.29) 0.45(0.38) 0.38(0.20) 0.52(0.35) 0.57(0.16) 0.58(0.11) 0.60(0.27) 0.44(0.33) 0.54(0.36) 0.58(0.30) 0.42(0.39) 0.50(0.31) 0.64(0.15) 0.42(0.42) 0.45(0.35) 0.69(0.30) 0.56(0.47) 0.68(0.48) 0.75(0.26) 0.48(0.55) 0.60(0.42) 0.81(0.37) 0.59(0.53) 0.68(0.37) 0.55(0.39) 0.67(0.29) 0.82(0.39) 0.61(0.41) 0.75(0.29) 0.58(0.37) 0.60(0.22) 0.60(0.25) 0.49(0.47) 0.46(0.32) 0.57(0.26) 0.52(0.40) 0.57(0.35) 0.55(0.35) 0.57(0.32) 0.64(0.29) 0.53(0.41) 0.69(0.55) 0.59(0.41) 0.60(0.25) 0.91(0.64) 0.71(0.59) 0.68(0.28) 0.69(0.34) 0.71(0.31) 0.73(0.26) 0.88(0.51) 0.71(0.45) 1.09(0.64) 1.04(0.35) 1.13(0.14) 0.93(0.46) 0.95(0.28) 0.75(0.29) 0.92(0.27) 0.91(0.42) 0.74(0.41) 1.03(0.43) 0.82(0.26) 1.17(0.41) 0.91(0.32) 1.12(0.36) 1.06(0.36) 1.01(0.43) 1.67(0.96) 1.10(0.76) 1.72(0.76) 1.45(0.33) 1.22(0.59) 1.28(0.32) 1.08(0.41) 1.28(0.36) 1.06(0.31) 1.60(0.67) 1.38(0.46) 1.48(0.54) 1.69(0.48) 1.77(0.55) 1.99(0.49) 1.53(0.56) 1.59(0.23) 1.51(0.45) 1.46(0.57) 1.57(0.37) 1.36(0.36) 1.60(0.30) 1.37(0.26) 1.73(0.42) 1.36(0.47) 2.12(0.90) 1.64(0.59) 2.12(0.57) 1.58(0.68) 2.11(0.69) 1.79(0.42) 1.69(0.38) 1.64(0.34) 1.49(0.21) 1.56(0.38) 1.61(0.22) 1.55(0.28) 1.49(0.38) 1.66(0.30) 1.45(0.24) 1.50(0.37) 1.50(0.19) 1.42(0.12) 1.38(0.26) 1.48(0.16) 1.32(0.22) 1.26(0.28) 1.37(0.13) 1.27(0.32) 1.17(0.20) 1.32(0.32) 1.29(0.25) 1.18(0.14) 1.29(0.33) 1.34(0.24) 1.26(0.16) 1.22(0.30) 1.33(0.19) 1.31(0.24) 1.21(0.32) 1.55(0.45) 1.45(0.43) 1.52(0.55) 2.03(0.70) 1.66(0.52) 1.47(0.30) 1.48(0.36) 1.50(0.34) 1.33(0.30) 1.64(0.38) 1.43(0.28) 1.64(0.26) 1.35(0.38) 1.61(0.30) 1.48(0.29) 1.55(0.44) 1.47(0.46) 1.46(0.46) 1.57(0.35) 1.46(0.26) 2.09(0.82) 1.69(0.57) 1.94(0.43) 1.79(0.43) 1.66(0.24) 2.27(0.88) 1.94(0.59) 2.26(0.98) 2.14(0.93) 1.75(0.51) 1.78(0.31)
++ Max displacement in automask = 2.27 (mm) at sub-brick 174
++ Max delta displ  in automask = 0.98 (mm) at sub-brick 176
** ERROR: output dataset name 'epi_volreg.nii.gz' conflicts with existing file
** ERROR: dataset NOT written to disk!
++ Wrote dataset to disk in ./output/epi_volreg_AA1.nii.gz
** Warning: overwriting file ./output/motion.1D

FSL: Registration of the anatomical image to MNI¶

A detailed example notebook about FSL Preprocessing and GLM is also available.

fsl_path = !which fsl
fsl_version = fsl_path[0].split('_')[1]

MNI_BRAIN = os.path.join(
    '/opt',
    f'fsl-{fsl_version}',
    'data',
    'standard',
    'MNI152_T1_2mm_brain.nii.gz'
)

print(MNI_BRAIN)

/opt/fsl-6.0.7.16/data/standard/MNI152_T1_2mm_brain.nii.gz

# Register the T1w image to the MNI template (default: dof 12, normal search)
!flirt -in ./output/synth_stripped.nii.gz -ref "{MNI_BRAIN}" -out ./output/synth_stripped_flirt_T1MNI.nii.gz -omat ./output/synth_stripped_flirt_T1MNI.mat

MRTrix: Denoising diffusion data¶

There is a series of 3 notebooks about MRTrix: Part 1 - Preprocessing can be found here.

# converts diffusion data to a format that MRtrix understands
! mrconvert ./ds001226/sub-CON02/ses-preop/dwi/sub-CON02_ses-preop_acq-AP_dwi.nii.gz ./output/sub-02_dwi.mif -fslgrad ./ds001226/sub-CON02/ses-preop/dwi/sub-CON02_ses-preop_acq-AP_dwi.bvec ./ds001226/sub-CON02/ses-preop/dwi/sub-CON02_ses-preop_acq-AP_dwi.bval -force

mrconvert: [WARNING] existing output files will be overwritten
mrconvert: [100%] uncompressing image "./ds001226/sub-CON02/ses-preop/dwi/sub-CON02_ses-preop_acq-AP_dwi.nii.gz"
mrconvert: [100%] copying from "./ds001226...ses-preop_acq-AP_dwi.nii.gz" to "./output/sub-02_dwi.mif"

# denoising
! dwidenoise ./output/sub-02_dwi.mif ./output/sub-02_den.mif -noise ./output/noise.mif -force

dwidenoise: [WARNING] existing output files will be overwritten
dwidenoise: [100%] preloading data for "./output/sub-02_dwi.mif"
dwidenoise: [100%] running MP-PCA denoising

4.3 Pythonic Interfaces and Python Toolkits for Neuroimaging¶

Nipype¶

Nipype is a flexible Python-based workflow engine that enables users to build reproducible, modular pipelines by integrating diverse neuroimaging tools under a consistent interface. We will explore how it wraps individual tools such as fsl.BET() and afni.Edge3() directly from Python code.

An overview of Nipype and how to build pipelines can be found in Nipype on Neurodesk.

# this makes it so FSL knows how we want our output files
os.environ["FSLOUTPUTTYPE"]="NIFTI_GZ"

btr = fsl.BET()
btr.inputs.in_file = './ds001226/sub-CON02/ses-preop/anat/sub-CON02_ses-preop_T1w.nii.gz'
btr.inputs.frac = 0.4
btr.inputs.out_file = './output/nipype_bet.nii.gz'
res = btr.run()

edge3 = afni.Edge3()
edge3.inputs.in_file = './ds001226/sub-CON02/ses-preop/anat/sub-CON02_ses-preop_T1w.nii.gz'
edge3.inputs.out_file = './output/nipype_afni_edges.nii.gz'
edge3.inputs.datum = 'byte'
res = edge3.run()

260708-09:55:47,503 nipype.interface INFO:
	 stderr 2026-07-08T09:55:47.503627:++ 3dedge3: AFNI version=AFNI_21.2.00 (Jul  8 2021) [64-bit]
260708-09:55:47,505 nipype.interface INFO:
	 stderr 2026-07-08T09:55:47.505177:*+ WARNING:   If you are performing spatial transformations on an oblique dset,
260708-09:55:47,505 nipype.interface INFO:
	 stderr 2026-07-08T09:55:47.505177:  such as ds001226/sub-CON02/ses-preop/anat/sub-CON02_ses-preop_T1w.nii.gz,
260708-09:55:47,506 nipype.interface INFO:
	 stderr 2026-07-08T09:55:47.505177:  or viewing/combining it with volumes of differing obliquity,
260708-09:55:47,506 nipype.interface INFO:
	 stderr 2026-07-08T09:55:47.505177:  you should consider running: 
260708-09:55:47,507 nipype.interface INFO:
	 stderr 2026-07-08T09:55:47.505177:     3dWarp -deoblique 
260708-09:55:47,507 nipype.interface INFO:
	 stderr 2026-07-08T09:55:47.505177:  on this and  other oblique datasets in the same session.
260708-09:55:47,508 nipype.interface INFO:
	 stderr 2026-07-08T09:55:47.505177: See 3dWarp -help for details.
260708-09:55:47,508 nipype.interface INFO:
	 stderr 2026-07-08T09:55:47.505177:++ Oblique dataset:ds001226/sub-CON02/ses-preop/anat/sub-CON02_ses-preop_T1w.nii.gz is 3.067714 degrees from plumb.
260708-09:55:49,780 nipype.interface INFO:
	 stderr 2026-07-08T09:55:49.779993:** ERROR: output dataset name 'nipype_afni_edges.nii.gz' conflicts with existing file
260708-09:55:49,781 nipype.interface INFO:
	 stderr 2026-07-08T09:55:49.779993:** ERROR: dataset NOT written to disk!

ANTsPy¶

ANTsPy is a Python wrapper for the widely-used ANTs (Advanced Normalization Tools) C++ biomedical image processing library. It offers fast reading and writing of medical images, advanced algorithms for image registration, segmentation, and statistical learning, as well as tools for generating publication-quality visualizations.

Segmentation¶

The segmentation module provides methods such as Atropos segmentation, Joint Label Fusion, cortical thickness estimation, and prior-based segmentation.

Atropos segmentation:

img = ants.image_read(ants.get_ants_data('r16'))
img = ants.resample_image(img, (64,64), 1, 0)
mask = ants.get_mask(img)
img_seg = ants.atropos(a=img, m='[0.2,1x1]', c='[2,0]', 
                       i='kmeans[3]', x=mask)
print(img_seg.keys())
ants.plot(img_seg['segmentation'])

dict_keys(['segmentation', 'probabilityimages'])

Cortical thickness

img = ants.image_read(ants.get_ants_data('r16'),2)
mask = ants.get_mask(img).threshold_image(1, 2)
segs = ants.atropos(a=img, m='[0.2,1x1]', c='[2,0]', i='kmeans[3]', x= mask)
thickimg = ants.kelly_kapowski(s=segs['segmentation'], g=segs['probabilityimages'][1],
                            w=segs['probabilityimages'][2], its=45, 
                            r=0.5, m=1)
print(thickimg)
img.plot(overlay=thickimg, overlay_cmap='jet')

ANTsImage
	 Pixel Type : float (float32)
	 Components : 1
	 Dimensions : (256, 256)
	 Spacing    : (1.0, 1.0)
	 Origin     : (0.0, 0.0)
	 Direction  : [1. 0. 0. 1.]

Registration¶

The registration module features the core ANTs registration interface, enabling access to all registration algorithms. It also includes utilities for evaluating registration quality, resampling and reorienting images, and applying specific transformations.

Symmetric Normalization (SyN)

fixed = ants.image_read(ants.get_ants_data('r16')).resample_image((64,64),1,0)
moving = ants.image_read(ants.get_ants_data('r64')).resample_image((64,64),1,0)
fixed.plot(overlay=moving, title='Before Registration')
mytx = ants.registration(fixed=fixed , moving=moving, type_of_transform='SyN' )
print(mytx)
warped_moving = mytx['warpedmovout']
fixed.plot(overlay=warped_moving,title='After Registration')

{'warpedmovout': ANTsImage
	 Pixel Type : float (float32)
	 Components : 1
	 Dimensions : (64, 64)
	 Spacing    : (4.0476, 4.0476)
	 Origin     : (0.0, 0.0)
	 Direction  : [1. 0. 0. 1.]
, 'warpedfixout': ANTsImage
	 Pixel Type : float (float32)
	 Components : 1
	 Dimensions : (64, 64)
	 Spacing    : (4.0476, 4.0476)
	 Origin     : (0.0, 0.0)
	 Direction  : [1. 0. 0. 1.]
, 'fwdtransforms': ['/tmp/tmp_rj2w1tp1Warp.nii.gz', '/tmp/tmp_rj2w1tp0GenericAffine.mat'], 'invtransforms': ['/tmp/tmp_rj2w1tp0GenericAffine.mat', '/tmp/tmp_rj2w1tp1InverseWarp.nii.gz']}

DIPY - Reconstruction of the diffusion signal with DTI (single tensor) model¶

DIPY (Diffusion Imaging in Python) is a comprehensive library for processing and analyzing 3D and 4D medical imaging data. As part of the NiPy ecosystem, it provides robust tools for spatial normalization, denoising, tractography, and advanced diffusion modeling. In this section, we focus on reconstructing the diffusion signal using the classic Diffusion Tensor Imaging (DTI) model — a foundational approach for estimating white matter structure.

# Get data
fdwi = './ds001226/sub-CON02/ses-preop/dwi/sub-CON02_ses-preop_acq-AP_dwi.nii.gz'
fbval = './ds001226/sub-CON02/ses-preop/dwi/sub-CON02_ses-preop_acq-AP_dwi.bval'
fbvec =  './ds001226/sub-CON02/ses-preop/dwi/sub-CON02_ses-preop_acq-AP_dwi.bvec'

data, affine, img = load_nifti(fdwi, return_img=True)
print(data.shape)
print(img.header.get_zooms()[:3])

(96, 96, 60, 102)
(np.float32(2.5), np.float32(2.5), np.float32(2.5))

# Load the b-values and b-vectors
bvals, bvecs = read_bvals_bvecs(fbval, fbvec)
gtab = gradient_table(bvals, bvecs=bvecs)
print(gtab.info)

B-values shape (102,)
         min 0.000000
         max 2800.000000
B-vectors shape (102, 3)
          min -0.998927
          max 0.997386

None

# Mask and crop the data
maskdata, mask = median_otsu(
    data, vol_idx=range(10, 50), median_radius=3, numpass=1, autocrop=True, dilate=2
)
print(f"maskdata.shape {maskdata.shape}")

maskdata.shape (59, 73, 55, 102)

# Instantiate the Tensor model and fit the masked data
tenmodel = dti.TensorModel(gtab)
tenfit = tenmodel.fit(maskdata)

# Initialize a NIfTI header and set its intent to 'vector' to indicate multi-component data (e.g., DEC map)
hdr = nib.Nifti1Header()
hdr.set_intent('vector') 
hdr['intent_name'] = b'RGB'

# Compute the color FA map (also known as the DEC map) from the diffusion tensor model,
# and save it as a NIfTI image with the appropriate vector metadata
img = nib.Nifti1Image(tenfit.color_fa, affine, header=hdr)
nib.save(img, './output/colorfa.nii.gz')

# Fit the tensor Orientation Distribution Functions on a subset of the data
sphere = get_sphere(name="repulsion724")
tensor_odfs = tenmodel.fit(data[25:60, 30:70, 29:30]).odf(sphere) 

scene = window.Scene()
odf_actor = actor.odf_slicer(tensor_odfs, sphere=sphere, scale=0.5, colormap=None)

scene.add(odf_actor)
# Save a snapshot of the rendered scene as a PNG image to display it in a later step or to share it outside the notebook
window.record(scene=scene, n_frames=1, out_path="./output/tensor_odfs.png", size=(600, 600))

5. Visualization: The Art of Brain Mapping¶

DIPY¶

Visualizing Tensor Orientation Distributions with DIPY and IPython¶

display(Image(filename='./output/tensor_odfs.png'))

Creating a mosaic plot¶

t1_nipype = './output/nipype_bet.nii.gz'
data, affine = load_nifti(t1_nipype)

#Render slices from T1 with a specific value range
mean, std = data[data > 0].mean(), data[data > 0].std()
value_range = (mean - 0.5 * std, mean + 1.5 * std)

slice_actor = actor.slicer(data, affine=affine, value_range=value_range)
scene = window.Scene()
scene.clear()
scene.projection(proj_type="parallel")
cnt = 0

X, Y, Z = slice_actor.shape[:3]

rows, cols, border = 20, 15, 5

for j in range(rows):
    for i in range(cols):
        slice_mosaic = slice_actor.copy()
        slice_mosaic.display(z=cnt)
        slice_mosaic.SetPosition(
            (X + border) * i, 0.5 * cols * (Y + border) - (Y + border) * j, 0
        )
        slice_mosaic.SetInterpolate(False)
        scene.add(slice_mosaic)
        cnt += 1
        if cnt > Z:
            break
    if cnt > Z:
        break

scene.reset_camera()
scene.zoom(3.5) #zoom in

window.record(scene=scene, out_path="./output/mosaic.png", size=(800, 800), reset_camera=False)
display(Image(filename='./output/mosaic.png'))

Matplotlib¶

Brain slices¶

# View 3D data
def view_slices_3d(image_3d, slice_nbr, vmin, vmax, title=''):
  fig = plt.figure(figsize=(15, 4))
  plt.suptitle(title, fontsize=14)

  plt.subplot(131)
  plt.imshow(np.take(image_3d, slice_nbr, 2), vmin=vmin, vmax=vmax, cmap='gray')
  plt.title('Axial', fontsize=10);

  plt.subplot(132)
  image_rot = ndimage.rotate(np.take(image_3d, slice_nbr, 1),90)
  plt.imshow(image_rot, vmin=vmin, vmax=vmax, cmap='gray')
  plt.title('Coronal', fontsize=10);

  plt.subplot(133)
  image_rot = ndimage.rotate(np.take(image_3d, slice_nbr, 0),90)
  plt.imshow(image_rot, vmin=vmin, vmax=vmax, cmap='gray')
  plt.title('Sagittal', fontsize=10);
  cbar=plt.colorbar()

# load data
brain_full = nib.load('./ds001226/sub-CON02/ses-preop/anat/sub-CON02_ses-preop_T1w.nii.gz').get_fdata()
brain_edges = nib.load('./output/nipype_afni_edges.nii.gz').get_fdata()

view_slices_3d(brain_full, slice_nbr=135, vmin=0, vmax=500, title='Brain and Skull')
view_slices_3d(brain_edges, slice_nbr=135, vmin=0, vmax=500, title='Brain Edges')

Motion parameters¶

# Load AFNI motion parameters (roll, pitch, yaw, dS, dL, dP)
motion_params = np.loadtxt('./output/motion.1D')
timepoints = np.arange(motion_params.shape[0])

# Plotting
fig, axs = plt.subplots(2, 1, figsize=(12, 6), sharex=True)

# Rotations in degrees
axs[0].plot(timepoints, motion_params[:, 0], label='Roll (I-S)')
axs[0].plot(timepoints, motion_params[:, 1], label='Pitch (R-L)')
axs[0].plot(timepoints, motion_params[:, 2], label='Yaw (A-P)')
axs[0].set_ylabel('Rotation (degrees)')
axs[0].legend()
axs[0].set_title('AFNI Motion Parameters')

# Translations in mm
axs[1].plot(timepoints, motion_params[:, 3], label='dS (Superior)')
axs[1].plot(timepoints, motion_params[:, 4], label='dL (Left)')
axs[1].plot(timepoints, motion_params[:, 5], label='dP (Posterior)')
axs[1].set_ylabel('Translation (mm)')
axs[1].set_xlabel('Timepoint (volume)')
axs[1].legend()

plt.tight_layout()
plt.show()

Nilearn¶

plot_epi¶

Plot cuts of an EPI image

mean_epi = mean_img('./output/synth_stripped_flirt_T1MNI.nii.gz', copy_header=True)
plot_epi(mean_epi, colorbar=True, cbar_tick_format="%i", title="mean_epi")

<nilearn.plotting.displays._slicers.OrthoSlicer at 0x7205f5e27230>

plot_anat and `add_edges` to see the overlay between two images¶

# Check registration by overlaying anatomical image as edges (red) on top of mni template
t1_mni = './output/synth_stripped_flirt_T1MNI.nii.gz'
disp_edges = plot_anat(title="add_edges") #default=MNI152TEMPLATE
disp_edges.add_edges(t1_mni, color="r")

plot_roi¶

Plot cuts of an ROI/mask image

plot_roi('./output/synth_mask.nii.gz', bg_img=t1_nipype, 
         title='Brain mask on skull-stripped brain')

<nilearn.plotting.displays._slicers.OrthoSlicer at 0x7205a07d4a50>

view_img¶

Interactive html viewer

import warnings
warnings.filterwarnings("ignore", message="Warning: 'partition' will ignore the 'mask'")

view_img(t1_nipype, bg_img='./ds001226/sub-CON02/ses-preop/anat/sub-CON02_ses-preop_T1w.nii.gz', 
         symmetric_cmap=False)

ipyniivue¶

Visualize the skull-stripped brain¶

from ipyniivue import NiiVue
nv = NiiVue()
nv.load_volumes([{"url": "https://huggingface.co/datasets/neurodeskorg/neurodeskedu/resolve/main/data/examples/workflows/AA_Neurodesk_demo_tour/synth_stripped_505129570395.nii.gz"}])
nv

Visualize the FA image (DEC map)¶

nv = NiiVue()
nv.load_volumes([{"url": "https://huggingface.co/datasets/neurodeskorg/neurodeskedu/resolve/main/data/examples/workflows/AA_Neurodesk_demo_tour/colorfa_d4813ca9a8c3.nii.gz"}])
nv

Dependencies in Jupyter/Python¶

Using the package watermark to document system environment and software versions used in this notebook, alongside the Neurodesktop version extracted from the JUPYTER_IMAGE or NEURODESKTOP_VERSION environment variables.

import os

%load_ext watermark

%watermark
%watermark --iversions

neurodesktop_version = (
    os.environ.get('JUPYTER_IMAGE', '').split(':')[-1] or
    os.environ.get('NEURODESKTOP_VERSION', 'unknown')
)

print(f"Neurodesktop version: {neurodesktop_version}")

Last updated: 2026-07-08T09:56:34.564438+00:00

Python implementation: CPython
Python version       : 3.13.13
IPython version      : 9.12.0

Compiler    : GCC 14.3.0
OS          : Linux
Release     : 6.8.0-111-generic
Machine     : x86_64
Processor   : x86_64
CPU cores   : 16
Architecture: 64bit

IPython       : 9.12.0
ants          : 0.6.3
bids          : 0.19.0
bids_validator: 1.14.7.post0
dipy          : 1.11.0
fury          : 0.11.0
ipyniivue     : 2.4.4
matplotlib    : 3.10.9
nibabel       : 5.4.2
nilearn       : 0.13.1
nipype        : 1.11.0
numpy         : 2.3.5
scipy         : 1.15.3

Neurodesktop version: 2026-06-04

Neurodesk Tools Demo

Shell We Begin?¶

1. Load software tools and import Python libraries¶

2. Data¶

Access Open Data on OSF Using DataLad¶

3. Bits about BIDS¶

BIDS conversion with BIDScoin¶

pyBIDS¶

BIDSLayout¶

The BIDSFile¶

The BIDSValidator¶

4. Toolbox Tour¶

4.1. Workflows¶

fMRIPrep: A Preprocessing Pipeline for fMRI Data¶

MRIQC: Quality control¶

4.2 Core Neuroimaging Tools (Command-Line Interfaces)¶

FreeSurfer’s SynthStrip: Brain extraction of the anatomical image¶

AFNI’s 3dvolreg: Motion Correction of functional data¶

FSL: Registration of the anatomical image to MNI¶

MRTrix: Denoising diffusion data¶

4.3 Pythonic Interfaces and Python Toolkits for Neuroimaging¶

Nipype¶

ANTsPy¶

Segmentation¶

Registration¶

DIPY - Reconstruction of the diffusion signal with DTI (single tensor) model¶

5. Visualization: The Art of Brain Mapping¶

DIPY¶

Visualizing Tensor Orientation Distributions with DIPY and IPython¶

Creating a mosaic plot¶

Matplotlib¶

Brain slices¶

Motion parameters¶

Nilearn¶

plot_epi¶

plot_anat and add_edges to see the overlay between two images¶

plot_roi¶

view_img¶

ipyniivue¶

Visualize the skull-stripped brain¶

Visualize the FA image (DEC map)¶

Dependencies in Jupyter/Python¶

plot_anat and `add_edges` to see the overlay between two images¶