Home DocumentationTroubleshooting

Troubleshooting

Common issues, diagnostic commands, and solutions for HINEC pipeline problems.

FSL Not Found

Symptom

Error: 'fsl command not found' or 'flirt: command not found' during preprocessing.

Likely Cause

FSL is not installed or not initialized in the current MATLAB session's environment.

Diagnostic

matlab

system('which flirt')
system('echo $FSLDIR')

Solution

matlab

# Add to ~/.bashrc before launching MATLAB
export FSLDIR=/usr/local/fsl
source $FSLDIR/etc/fslconf/fsl.sh
export PATH=$FSLDIR/bin:$PATH
 
# Or set within MATLAB:
setenv('FSLDIR', '/usr/local/fsl');
setenv('PATH', [getenv('FSLDIR') '/bin:' getenv('PATH')]);

Prevention:Add FSL initialization to your shell profile so it's available in every session.

Out of Memory

Symptom

MATLAB crashes or throws 'Out of memory' error during tensor estimation or tractography.

Likely Cause

Large datasets exceed available RAM. Typical datasets require 2-4 GB; very large volumes may need more.

Diagnostic

matlab

memory  % Check MATLAB memory usage
whos nim  % Check nim structure size

Solution

matlab

% Reduce memory usage:
% 1. Close other applications
% 2. Use single precision where possible
% 3. Reduce seed_density in YAML config
% 4. Process in smaller chunks if possible
 
% Check available memory before processing:
[~, sys] = memory;
fprintf('Available: %.1f GB\n', sys.PhysicalMemory.Available/1e9);

Prevention:Monitor memory usage before starting large jobs. Use fast_exploration.yml preset for initial testing.

String vs Char Array Errors

Symptom

Error involving string indexing or 'Conversion to char from string is not possible'.

Likely Cause

MATLAB's string type (double quotes) and char array type (single quotes) behave differently. HINEC expects char arrays for file paths.

Diagnostic

matlab

class(my_path)  % Should return 'char', not 'string'

Solution

matlab

% Use single quotes for all file paths:
main('data/sample', 'output.mat');  % Correct
main("data/sample", "output.mat");  % May cause issues
 
% Convert string to char if needed:
my_path = char(my_string);

Prevention:Always use single quotes for string arguments in HINEC function calls.

No Tracks Generated

Symptom

runTractography completes but produces zero or very few tracks.

Likely Cause

Seed mask is empty, FA values are too low, or termination criteria are too strict.

Diagnostic

matlab

% Check seed mask
load('output.mat');
sum(nim.FA(:) > 0.15)  % Count voxels above FA threshold
sum(nim.mask(:) > 0)   % Count brain mask voxels

Solution

matlab

% Adjust parameters in YAML config:
tractography:
  termination_fa: 0.10    # Lower from default 0.15
  angle_thresh: 45        # More permissive curvature
  min_length: 20          # Accept shorter tracks
  seed_density: 8         # More seed points

Prevention:Always verify data quality with nim_plot before running tractography. Check FA histogram for reasonable values.

Preprocessing Fails

Symptom

nim_preprocessing produces errors or incomplete output.

Likely Cause

Missing input files, incorrect file naming convention, or FSL tool failures.

Diagnostic

matlab

% Check all required files exist:
ls data/prefix_raw.nii.gz
ls data/prefix.bval
ls data/prefix.bvec

Solution

matlab

% Verify file naming convention:
% Required: {prefix}_raw.nii.gz, {prefix}.bval, {prefix}.bvec
% Optional: {prefix}_T1.nii.gz, {prefix}_acqp.txt
 
% If FSL tools fail individually:
system('bet input.nii.gz output -f 0.3 -v');
% Check for specific error messages

Prevention:Validate input files before running the pipeline. Use the data prefix convention consistently.

Poor Registration Quality

Symptom

Atlas regions appear misaligned with brain structures. Parcellation labels don't match anatomy.

Likely Cause

Registration failed or used suboptimal fallback method. T1 data was not available for T1-guided registration.

Diagnostic

matlab

% Visual check:
nim_plot(nim, 'mode', 'parcels');
% Look for regions that appear shifted or misaligned

Solution

matlab

% Provide T1 data for enhanced registration:
main('data/prefix_raw', 'output.mat', 't1_file', 'data/prefix_T1.nii.gz');
 
% Or in YAML:
preprocessing:
  t1_available: true
  use_t1_registration: true

Prevention:Always provide T1 structural data when available. The T1-guided MNI→T1→DWI registration chain produces 40-60% better alignment.

Validation