Preprocess Debug — Preprocessing Failure Diagnosis

When to Use

• "Why did preprocessing fail for patient X?"
• "The registration output looks wrong"
• "Skull stripping removed too much / too little"
• "Intensity normalization produced weird values"
• "Which step is causing the problem?"
• Any preprocessing quality issue or crash investigation

Diagnostic Workflow

Step 1: Identify the failing step

Check the visualization directory for which step produced the last PNG:

ls -la {viz_root}/MenGrowth-XXXX/MenGrowth-XXXX-YYY/
# step1_data_harmonization_t1c.png  ← exists
# step2_bias_field_correction_t1c.png  ← exists
# step3_resampling_t1c.png  ← MISSING → Step 3 failed

Check logs for error messages (look for ERROR or RuntimeError).

Step 2: Check step artifacts

Each step may produce artifacts in {artifacts}/MenGrowth-XXXX/MenGrowth-XXXX-YYY/:

Step 3: Examine visualization PNGs

Each step's PNG shows before/after comparison. Look for:

Step 4: Check specific failure patterns

Registration failures

• "No reference modality found": Check that reference_modality_priority matches available modalities
• Poor alignment: Try engine: "antspyx" instead of "nipype" (or vice versa)
• Divergence: Check if use_center_of_mass_init: true is set
• ANTs crash: Look for ITK ERROR in logs; check if input volumes have valid affine matrices
• Quality warning: If correlation dissimilarity > quality_warning_threshold, registration may have failed

Skull stripping failures

• Over-stripping (tumor removed): HD-BET is more robust to pathology than SynthStrip; try method: "hdbet" with hdbet_mode: "accurate"
• Under-stripping (skull remaining): Increase SynthStrip border parameter or switch methods
• GPU OOM: Set hdbet_device: "cpu" or synthstrip_device: "cpu"

Intensity normalization failures

• All zeros output: Check that brain mask exists and covers tissue
• Extreme values: Use clip_range: [-5.0, 5.0] for z-score
• NaN values: Input may contain NaN — check with nib.load(path).get_fdata() for NaN/Inf
• Wrong mask source: Check logs for "Using brain mask from:" vs "using nonzero voxels as fallback"

Data harmonization failures

• Wrong orientation: Check reorient_to matches expected convention (RAS vs LPS)
• Background not removed: Try method: "otsu_foreground" instead of default
• NRRD parse error: Check if input file is valid NRRD with nrrd.read(path)

Resampling failures

• ECLARE environment not found: Verify conda_environment_eclare matches installed env
• GPU OOM with ECLARE: Reduce batch_size or switch to method: "bspline"
• Extreme anisotropy: Use method: "composite" for volumes with > 5mm slice thickness

Step 5: Check the temp-file mechanism

If a step crashes mid-write, a .tmp.nii.gz file may be left behind:

find {output_root} -name "*.tmp*"

These should be deleted before re-running.

Key Debugging Code Locations

Quick Config Fixes