Getting Started

Install HINEC, prepare your data, and run your first tractography pipeline in minutes.

Prerequisites

MATLAB

HINEC requires MATLAB R2020b or later with two toolboxes:

Image Processing Toolbox
Statistics and Machine Learning Toolbox

matlab

ver('images')  % Image Processing Toolbox
ver('stats')   % Statistics and Machine Learning Toolbox

Verify required toolboxes are installed.

FSL (FMRIB Software Library)

Required for preprocessing raw diffusion data. Not needed if you provide already-preprocessed files.

bash

# Add to your shell profile (~/.bashrc or ~/.zshrc)
export FSLDIR=/usr/local/fsl
source $FSLDIR/etc/fslconf/fsl.sh
export PATH=$FSLDIR/bin:$PATH
 
# Verify installation
flirt -version

SPM12

Included in the repository at lib/spm12/. No separate installation is needed — main.m automatically adds it to the MATLAB path.

Python (Optional)

Required only for the fast distributed slice viewer:

Python 3.7+
pip install Pillow numpy
tkinter (usually included with Python)

Installation

bash

# Clone the repository
git clone https://github.com/uicneuro/hinec
cd hinec
 
# Verify sample data exists
ls data/original_sample/
ls data/parcellation_sample/

No build step is required. MATLAB source files are used directly.

Quick Start

# Process sample data with default configuration
./bin/run_hinec.sh data/parcellation_sample/sample sample.mat

# Export visualization figures
./bin/run_visualization.sh hinec_runs/run_*_hinec_default/ figures/sample

The simplest way to run HINEC end-to-end — preprocessing, DTI, and tractography in one command.

Data prefix convention

The first argument is a data prefix — the shared path and name common to all input files, without any suffix or extension. For example, given files sample_raw.nii.gz, sample.bval, and sample.bvec, the prefix is data/parcellation_sample/sample.

Tip

If your files end in _raw.nii.gz, HINEC runs FSL preprocessing automatically. Files ending in just .nii.gz (no _raw) are assumed to be already preprocessed.

Input Data Requirements

HINEC uses a prefix-based file discovery system. All input files share a common prefix.

Required and optional input files

Parameter	Type	Required	Default	Description
{prefix}_raw.nii.gz	NIfTI	Yes	—	Raw diffusion-weighted MRI data (triggers preprocessing)
{prefix}.bval	text	Yes	—	B-values for each diffusion-weighted volume
{prefix}.bvec	text	Yes	—	B-vectors (gradient directions) for each volume
{prefix}_M.nii.gz	NIfTI	No	—	Pre-computed brain mask (skips mask extraction)
{prefix}_T1.nii.gz	NIfTI	No	—	T1-weighted structural image for enhanced registration
{prefix}_fmap_Hz.nii.gz	NIfTI	No	—	B0 field map in Hz for distortion correction
{prefix}_acqp.txt	text	No	—	Acquisition parameters for FSL eddy
{prefix}_index.txt	text	No	—	Volume index file for FSL eddy

text|Example directory structure

data/parcellation_sample/
├── sample_raw.nii.gz    # Raw diffusion data
├── sample.bval          # B-values
├── sample.bvec          # B-vectors
├── sample_T1.nii.gz     # T1 anatomical (optional)
└── sample_acqp.txt      # Acquisition parameters (optional)

Expected Output

After main() completes, the output .mat file contains a nim struct with:

Parameter	Type	Required	Default	Description
.img	4D array	Yes	—	Original image data [X, Y, Z, N]
.DT	4D array	Yes	—	Diffusion tensors (6 components per voxel)
.evec	5D array	Yes	—	Eigenvectors — fiber directions
.eval	4D array	Yes	—	Eigenvalues — diffusion magnitudes
.FA	3D array	Yes	—	Fractional anisotropy map
.parcellation_mask	3D array	Yes	—	Brain region labels
.labels	Map	Yes	—	Region names from atlas

After runTractography(), a tracks file appears in tractography_results/ containing:

tracks — Cell array of fiber pathways (each track is an Nx3 matrix)
options — Parameters used during tracking
elapsed_time — Computation time
algorithm — Algorithm name

Configuration Presets

HINEC ships with four configuration presets that balance speed and quality for different use cases.

Preset	Purpose	Speed	Quality
hinec_default.yml	Balanced performance	Medium	Good
high_precision.yml	Publication quality	Slow	Excellent
fast_exploration.yml	Quick testing	Fast	Moderate
irontract.yml	IronTract challenge	Medium	High

Overview

Pipeline