BrainLes-Preprocessing

<!-- [](https://codecov.io/gh/BrainLesion/brainles-preprocessing) -->

BrainLes preprocessing is a comprehensive, modular toolkit for preprocessing multi-modal brain MRI and other biomedical imaging data. It provides flexible preprocessing pipelines that can be customized to your specific needs.

Features

Core Preprocessing Steps

• Normalization: Intensity normalization using various methods (e.g., percentile-based)
• Co-registration: Align multiple modalities to a reference modality
• Atlas Registration: Register images to standard atlas spaces (MNI152, SRI24, etc.)
• Brain Extraction: Skull stripping using state-of-the-art methods (HD-BET, SynthStrip)
• N4 Bias Correction: Correct intensity inhomogeneities
• Defacing: Anonymize images by removing facial features

Preprocessing Modes

• Atlas-Centric: Process images in atlas space with optional atlas-based intensity correction
• Native Space: Process images in patient/native space without atlas registration

Key Benefits

• Modular & Backend-Agnostic: Easily swap or skip preprocessing steps and choose from multiple backends
• Flexible Output Options: Generate any combination of outputs (brain extracted, with skull, defaced, raw, normalized)
• Bidirectional Transforms: Transform images and segmentations between native and atlas space
• Extensible: Add custom normalizers, registrators, brain extractors, or defacing methods

<!-- TODO include image here -->

Installation

With a Python 3.10+ environment you can install directly from pypi.org:

pip install brainles-preprocessing

We recommend using Python 3.10 / 3.11 / 3.12.

[!NOTE]
For python 3.13 the installation can currently fail with the error Failed to build antspyx. This usually means that there is no pre-built wheel for the package and it has to be build locally. This will require cmake (install e.g. with pip install cmake) and quite some time. Rerunning the installation with cmake installed should fix the error.

Usage

Atlas-Centric Preprocessing

Use AtlasCentricPreprocessor to register images to an atlas, perform atlas correction, and skull strip. This is useful when you want all images in a common atlas space.

Key features:

• Co-registration of moving modalities to center modality
• Registration to atlas space
• Optional atlas correction (intensity adjustment based on atlas)
• N4 bias correction
• Brain extraction
• Defacing for anonymization

Example with all output options:

This example demonstrates all possible output paths. You can specify any combination of:

• Raw outputs (without normalization): raw_bet_output_path, raw_skull_output_path, raw_defaced_output_path
• Normalized outputs (requires a normalizer): normalized_bet_output_path, normalized_skull_output_path, normalized_defaced_output_path
• Masks (only for CenterModality): bet_mask_output_path, defacing_mask_output_path

Note: At least one output path must be specified per modality. All output paths are optional except that at least one must be provided.

from pathlib import Path
from brainles_preprocessing.modality import Modality, CenterModality
from brainles_preprocessing.normalization.percentile_normalizer import (
    PercentileNormalizer,
)
from brainles_preprocessing.preprocessor import AtlasCentricPreprocessor

patient_folder = Path("/path/to/patient")
output_folder = Path("/path/to/output")

# specify a normalizer (required if using any normalized_* output paths)
percentile_normalizer = PercentileNormalizer(
    lower_percentile=0.1,
    upper_percentile=99.9,
    lower_limit=0,
    upper_limit=1,
)

# define center modality with all possible outputs
center = CenterModality(
    modality_name="t1c",  # required
    input_path=patient_folder / "t1c.nii.gz",  # required
    normalizer=percentile_normalizer,  # optional: required for normalized_* outputs
    # Raw outputs (optional)
    raw_bet_output_path=output_folder / "raw_bet/t1c_bet_raw.nii.gz",  # brain extracted
    raw_skull_output_path=output_folder / "raw_skull/t1c_skull_raw.nii.gz",  # with skull
    raw_defaced_output_path=output_folder / "raw_defaced/t1c_defaced_raw.nii.gz",  # defaced
    # Normalized outputs (optional, requires normalizer)
    normalized_bet_output_path=output_folder / "normalized_bet/t1c_bet_normalized.nii.gz",
    normalized_skull_output_path=output_folder / "normalized_skull/t1c_skull_normalized.nii.gz",
    normalized_defaced_output_path=output_folder / "normalized_defaced/t1c_defaced_normalized.nii.gz",
    # Masks (optional, only for CenterModality)
    bet_mask_output_path=output_folder / "masks/t1c_bet_mask.nii.gz",
    defacing_mask_output_path=output_folder / "masks/t1c_defacing_mask.nii.gz",
    # Optional parameters
    atlas_correction=True,  # default: True
    n4_bias_correction=False,  # default: False
)

# define moving modalities
moving_modalities = [
    Modality(
        modality_name="flair",  # required
        input_path=patient_folder / "flair.nii.gz",  # required
        normalizer=percentile_normalizer,  # optional: required for normalized_* outputs
        # Raw outputs (optional)
        raw_bet_output_path=output_folder / "raw_bet/flair_bet_raw.nii.gz",
        raw_skull_output_path=output_folder / "raw_skull/flair_skull_raw.nii.gz",
        raw_defaced_output_path=output_folder / "raw_defaced/flair_defaced_raw.nii.gz",
        # Normalized outputs (optional, requires normalizer)
        normalized_bet_output_path=output_folder / "normalized_bet/flair_bet_normalized.nii.gz",
        normalized_skull_output_path=output_folder / "normalized_skull/flair_skull_normalized.nii.gz",
        normalized_defaced_output_path=output_folder / "normalized_defaced/flair_defaced_normalized.nii.gz",
        # Optional parameters
        atlas_correction=True,  # default: True
        n4_bias_correction=False,  # default: False
    )
]

# instantiate and run the preprocessor
preprocessor = AtlasCentricPreprocessor(
    center_modality=center,
    moving_modalities=moving_modalities,
    # Optional: customize backends (defaults shown below)
    # registrator=ANTsRegistrator(),
    # brain_extractor=HDBetExtractor(),
    # n4_bias_corrector=SitkN4BiasCorrector(),
    # defacer=QuickshearDefacer(),
)

preprocessor.run(
    # Optional: save intermediate results to these directories
    save_dir_coregistration=output_folder / "coregistration",
    save_dir_atlas_registration=output_folder / "atlas_registration",
    save_dir_atlas_correction=output_folder / "atlas_correction",
    save_dir_n4_bias_correction=output_folder / "n4_bias_correction",
    save_dir_brain_extraction=output_folder / "brain_extraction",
    save_dir_defacing=output_folder / "defacing",
)

Native Space Preprocessing

Use NativeSpacePreprocessor to perform coregistration, N4 bias correction, brain extraction, and defacing while keeping images in native space (no atlas registration).

Key features:

• Co-registration of moving modalities to center modality
• N4 bias correction
• Brain extraction
• Defacing for anonymization
• No atlas registration - stays in native/patient space

Example with all output options:

This example demonstrates all possible output paths. You can specify any combination of:

• Raw outputs (without normalization): raw_bet_output_path, raw_skull_output_path, raw_defaced_output_path
• Normalized outputs (requires a normalizer): normalized_bet_output_path, normalized_skull_output_path, normalized_defaced_output_path
• Masks (only for CenterModality): bet_mask_output_path, defacing_mask_output_path

Note: At least one output path must be specified per modality. All output paths are optional except that at least one must be provided.

from pathlib import Path
from brainles_preprocessing.modality import Modality, CenterModality
from brainles_preprocessing.normalization.percentile_normalizer import (
    PercentileNormalizer,
)
from brainles_preprocessing.preprocessor import NativeSpacePreprocessor

patient_folder = Path("/path/to/patient")
output_folder = Path("/path/to/output")

# specify a normalizer (required if using any normalized_* output paths)
percentile_normalizer = PercentileNormalizer(
    lower_percentile=0.1,
    upper_percentile=99.9,
    lower_limit=0,
    upper_limit=1,
)

# define center modality with all possible outputs
center = CenterModality(
    modality_name="t1c",  # required
    input_path=patient_folder / "t1c.nii.gz",  # required
    normalizer=percentile_normalizer,  # optional: required for normalized_* outputs
    # Raw outputs (optional)
    raw_bet_output_path=output_folder / "raw_bet/t1c_bet_raw.nii.gz",  # brain extracted
    raw_skull_output_path=output_folder / "raw_skull/t1c_skull_raw.nii.gz",  # with skull
    raw_defaced_output_path=output_folder / "raw_defaced/t1c_defaced_raw.nii.gz",  # defaced
    # Normalized outputs (optional, requires normalizer)
    normalized_bet_output_path=output_folder / "normali