Normalize ========= normalize_intensity - Percentile-based Intensity Normalization for MRI Data Part of the micaflow processing pipeline for neuroimaging data. This module performs intensity normalization on MRI data using percentile-based clamping and rescaling. Intensity normalization is crucial for improving consistency across different scans, scanners, and acquisition protocols, making downstream analysis more robust and enabling valid comparisons between subjects and timepoints. Why Intensity Normalization? ---------------------------- MRI signal intensities are arbitrary and vary significantly due to: - Scanner hardware differences (field strength, coils, gradient systems) - Acquisition parameters (TR, TE, flip angle, bandwidth) - Reconstruction algorithms and vendor-specific processing - Subject-specific factors (head size, tissue properties) Without normalization: - Visual comparison across scans is difficult - Quantitative analyses become unreliable - Machine learning models perform poorly - Atlas-based methods may fail - Group statistics are confounded by intensity variations Percentile-based Normalization: ------------------------------ This method normalizes intensities by: 1. Computing percentiles on non-zero (brain) voxels only 2. Clamping extreme values at specified percentiles (default: 1st and 99th) 3. Rescaling clamped values to a standardized range (default: 0-100) Advantages: - Robust to outliers (extreme bright/dark spots) - Preserves relative intensity relationships within normal range - No assumptions about tissue distributions Limitations: - Does not account for spatial intensity variations (bias fields) - May not be appropriate for quantitative sequences (T1/T2 mapping) - Assumes background is zero (requires brain extraction for best results) - Cannot correct for different tissue contrasts across modalities Features: -------- - Percentile-based clamping to reduce outlier effects - Customizable percentile thresholds (default: 1st and 99th) - Customizable output range (default: 0-100) - Operates only on non-zero voxels (preserves background) - Preserves original image geometry and header information - Handles edge cases (no non-zero voxels, uniform intensity) - Fast processing suitable for large datasets Command-Line Usage: ------------------ # Basic normalization with default parameters (1st-99th percentiles, 0-100 range) micaflow normalize_intensity \ --input \ --output # Custom percentiles (more aggressive outlier removal) micaflow normalize_intensity \ --input \ --output \ --lower-percentile 2.0 \ --upper-percentile 98.0 # Normalize to [0, 1] range (useful for machine learning) micaflow normalize_intensity \ --input \ --output \ --min-value 0 \ --max-value 1 # Conservative normalization (less outlier removal) micaflow normalize_intensity \ --input \ --output \ --lower-percentile 0.5 \ --upper-percentile 99.5 Python API Usage: ---------------- >>> from micaflow.scripts.normalize_intensity import normalize_intensity >>> >>> # Basic normalization >>> normalize_intensity( ... input_file="t1w.nii.gz", ... output_file="t1w_normalized.nii.gz" ... ) >>> >>> # Custom percentiles and range >>> normalize_intensity( ... input_file="t1w.nii.gz", ... output_file="t1w_normalized.nii.gz", ... lower_percentile=2, ... upper_percentile=98, ... min_val=0, ... max_val=1 ... ) >>> >>> # Silent mode (no progress messages) >>> normalize_intensity( ... input_file="t1w.nii.gz", ... output_file="t1w_normalized.nii.gz", ... verbose=False ... ) Pipeline Integration: -------------------- Intensity normalization is typically applied AFTER bias field correction: Structural MRI Pipeline: 1. Denoising (optional) 2. Brain extraction (bet) 3. Bias field correction (bias_correction) 4. Intensity normalization (normalize_intensity) ← You are here 5. Registration to standard space (coregister) 6. Tissue segmentation Diffusion MRI Pipeline: Note: For DWI, normalization is less common. If needed, apply to b0 only: 1. Denoising (denoise) 2. Motion/eddy correction (motion_correction) 3. Distortion correction (apply_SDC) 4. Bias field correction (bias_correction) 5. B0 intensity normalization (optional) Exit Codes: ---------- 0 : Success - normalization completed 1 : Error - invalid inputs, file not found, or processing failure Technical Notes: --------------- - Default percentiles: 1st and 99th (clips ~2% of voxels) - Default output range: 0-100 - Percentile calculation: Only on non-zero voxels (excludes background) - Zero voxels (background) remain zero after normalization - Formula: norm = ((clipped - p_low) / (p_high - p_low)) × (max - min) + min - Processing time: < 1 minute for typical 3D volumes - Memory efficient: Operates on masked data only - Data type: Preserved from input (float32/float64) - NIfTI header: Preserved including orientation and spacing - Edge case handling: Returns copy if no non-zero voxels found See Also: -------- - bias_correction : Remove intensity inhomogeneities before normalization - bet : Brain extraction for better percentile estimation - coregister : Register normalized images to standard space Command Line Usage ----------------- .. code-block:: bash micaflow normalize [options] Source Code ----------- View the source code: `GitHub Repository `_ Description ----------- This script normalizes MRI intensity values using percentile-based clamping and rescaling to improve consistency across scans and scanners. Full Help --------- .. code-block:: text ╔════════════════════════════════════════════════════════════════╗ ║ INTENSITY NORMALIZATION ║ ╚════════════════════════════════════════════════════════════════╝ This script normalizes MRI intensity values using percentile-based clamping and rescaling to improve consistency across scans and scanners. ────────────────────────── USAGE ────────────────────────── micaflow normalize_intensity [options] ─────────────────── REQUIRED ARGUMENTS ─────────────────── --input, -i : Path to the input image file (.nii.gz) --output, -o : Path for the normalized output image (.nii.gz) ─────────────────── OPTIONAL ARGUMENTS ─────────────────── --lower-percentile: Lower percentile for clamping (default: 1.0) Range: 0-100, must be < upper percentile --upper-percentile: Upper percentile for clamping (default: 99.0) Range: 0-100, must be > lower percentile --min-value : Minimum value in output range (default: 0) --max-value : Maximum value in output range (default: 100) ──────────────────── EXAMPLE USAGE ─────────────────────── # Example 1: Basic normalization (1st-99th percentiles, 0-100) micaflow normalize_intensity \ --input t1w.nii.gz \ --output t1w_normalized.nii.gz # Example 2: Aggressive outlier removal (2nd-98th percentiles) micaflow normalize_intensity \ --input t1w.nii.gz \ --output t1w_normalized.nii.gz \ --lower-percentile 2.0 \ --upper-percentile 98.0 # Example 3: Normalize to [0, 1] range (for ML) micaflow normalize_intensity \ --input t1w.nii.gz \ --output t1w_normalized.nii.gz \ --min-value 0 \ --max-value 1 # Example 4: Conservative normalization (0.5th-99.5th percentiles) micaflow normalize_intensity \ --input t1w.nii.gz \ --output t1w_normalized.nii.gz \ --lower-percentile 0.5 \ --upper-percentile 99.5 ─────────── WHY INTENSITY NORMALIZATION? ──────────────── Problem: MRI intensities are arbitrary and vary across: • Different scanners and vendors • Acquisition protocols and parameters • Subjects and scanning sessions Solution: Percentile-based normalization provides: • Consistent intensity ranges across scans • Robustness to outliers (bright/dark spots) Method: 1. Compute percentiles on non-zero voxels only 2. Clamp intensities at specified percentiles 3. Rescale to standardized range (e.g., 0-100) 4. Background (zero) voxels remain unchanged ────────────────────── WHEN TO USE ────────────────────── Recommended: • Before registration across subjects/sessions • Before group-level statistical analysis • For machine learning applications • When combining data from multiple scanners • After bias field correction • For visualization and QC Not recommended: • Quantitative sequences (T1/T2 mapping, ASL) • Before bias field correction • When absolute intensities have meaning • For sequences with specific intensity scales ────────────────────────── NOTES ───────────────────────── • Default: Clamp at 1st and 99th percentiles (clips ~2% of voxels) • Default output range: 0-100 • Percentiles computed on NON-ZERO voxels only • Background (zero) voxels remain zero • Formula: ((clipped - p_low) / (p_high - p_low)) × (max - min) + min • Processing time: < 1 minute for typical 3D volumes • Preserves image geometry and header information • Works with any MRI contrast (T1w, T2w, FLAIR, etc.) • Best applied to brain-extracted images ─────────────── PIPELINE POSITION ─────────────────────── 1. Brain extraction (bet) 2. Bias field correction (bias_correction) 3. Intensity normalization (normalize_intensity) ← You are here 4. Registration (coregister) 5. Analysis/segmentation ────────────────────── EXIT CODES ─────────────────────── 0 : Success - normalization completed 1 : Error - invalid inputs, file not found, or processing failure ───────────────── COMMON ISSUES ───────────────────────── Issue: Output looks over-bright or over-dark Solution: Adjust percentiles (more conservative: 0.5-99.5) Issue: Important features are clipped Solution: Use more conservative percentiles or check for artifacts Issue: Background not zero after normalization Solution: Apply brain extraction first, or check input for NaN values Issue: All voxels have same intensity after normalization Solution: Check input - may have uniform intensity or only zeros