NBLtools

Diffusion MRI Preprocessing Pipeline

NBL Logo

Overview

NBLtools is a comprehensive preprocessing pipeline for diffusion MRI data. It provides automated tools for data quality control and correction, ensuring your diffusion data is optimally prepared for analysis.

Installation Options

There are two ways to install and use NBLtools:

  1. Native Installation: Install NBLtools and its dependencies directly on your Linux/Windows Subsystem for Linux (WSL)/macOS system. This provides the best performance and integration with your system.
  2. Docker Container: Use our pre-configured Docker image with all dependencies already installed. This is the easiest option for quick setup and ensures compatibility.

Detailed installation instructions for both methods are available below on this page.

Key Features

Usage

Data Organization

Before running NBLtools, organize your data with the following structure:

subject01/
└── dwi/
    ├── dwi.nii.gz          # Diffusion weighted images
    ├── dwi.bval            # B-values file
    ├── dwi.bvec            # B-vectors file
    ├── dwi_rev.nii.gz      # Reverse phase encode data (optional)
    ├── dwi_rev.bval        # B-values for reverse phase
    ├── dwi_rev.bvec        # B-vectors for reverse phase
    └── acqparams.txt       # Acquisition parameters
Note: You can add multiple diffusion files (e.g., dwi_01.nii.gz, dwi_02.nii.gz, etc.) with their corresponding .bval and .bvec files. NBLtools will automatically concatenate all files during processing. Remember to adjust the acqparams.txt file accordingly with one row per volume.

The acqparams.txt file should contain the phase encoding directions and total readout time:

0 1 0 0.086
0 -1 0 0.086

Each row corresponds to a volume: phase encoding direction (x y z) and total readout time in seconds.

Running NBLtools

Once your data is organized, process it with a single command:

run_all_tu ./subject01 -f -p -b 1 -i -t -m -e -c 0 -q

Each parameter controls a specific preprocessing step:

NBLtools command line parameters

The screenshot above shows all available parameters and their descriptions directly from the command line help.

Direct Installation

For users who want to install NBLtools directly on their Linux, Windows Subsystem for Linux (WSL), or macOS system.

Download from GitHub

GitHub Repository

Access the source code, documentation, and latest releases

View on GitHub

System Requirements

NBLtools requires the following software dependencies to be installed:

ANTs

Advanced Normalization Tools for image registration and segmentation

FSL

FMRIB Software Library for brain imaging analysis

TORTOISE 4.0

Tolerably Obsessive Registration and Tensor Optimization Indolent Software Ensemble

Memory (RAM)

Minimum: 8GB
Recommended: 16GB+ for large datasets

Setting Up Your Environment

After installing the dependencies, you need to add them to your PATH. Edit your ~/.bashrc file (Linux/WSL) or ~/.bash_profile (macOS) and add these lines:

# Add NBLtools to PATH (including all subdirectories)
NBLTOOLS_DIR=/path/to/your/nbltools  # Change to your installation path
if [ -d "$NBLTOOLS_DIR" ]; then
  NBLTOOLS_PATHS=$(find $NBLTOOLS_DIR -type d ! -path "*.git/*" | tr '\n' ':')
  export PATH="$PATH:$NBLTOOLS_PATHS"
fi

# Example for ANTs (simple path addition)
export PATH="/path/to/ANTs/bin:$PATH"

# For FSL and TORTOISE, follow their specific installation instructions

Note:
• Change NBLTOOLS_DIR to where you cloned/installed NBLtools
• For ANTs, replace /path/to/ANTs/bin with your actual ANTs installation path
• FSL and TORTOISE have specific setup scripts - follow their official installation guides

After saving the file, reload it by running: source ~/.bashrc

Docker Installation

For Windows, Linux, and macOS (Intel) users, we provide a Docker container with all dependencies pre-installed. This is the easiest way to get started with NBLtools.

Installing Docker Desktop

  1. Download and install Docker Desktop from docker.com
  2. Start Docker Desktop and ensure it's running
  3. Pull the NBLtools Docker image (see command below)

Running NBLtools with Docker

Interactive Docker Command

Run NBLtools interactively with all dependencies included:

docker run -it -v /path/to/your/data:/data rstones/dwi-preproc bash

Replace /path/to/your/data with the actual path to your diffusion MRI data directory. Your data will be accessible inside the container at /data

Note: macOS Apple Silicon (M-series) users may experience compatibility issues with the Docker container. We recommend using the native installation with the required dependencies.

Support

For questions, bug reports, or feature requests: