brainles_preprocessing

modality

class brainles_preprocessing.modality.CenterModality(modality_name: str, input_path: str | Path, normalizer: Normalizer | None = None, raw_bet_output_path: str | Path | None = None, raw_skull_output_path: str | Path | None = None, raw_defaced_output_path: str | Path | None = None, normalized_bet_output_path: str | Path | None = None, normalized_skull_output_path: str | Path | None = None, normalized_defaced_output_path: str | Path | None = None, atlas_correction: bool = True, bet_mask_output_path: str | Path | None = None, defacing_mask_output_path: str | Path | None = None)

Bases: Modality

Represents a medical image center modality with associated preprocessing information.

Parameters:
  • modality_name (str) – Name of the modality, e.g., “T1”, “T2”, “FLAIR”.

  • input_path (str or Path) – Path to the input modality data.

  • normalizer (Normalizer, optional) – An optional normalizer for intensity normalization.

  • raw_bet_output_path (str or Path, optional) – Path to save the raw brain extracted modality data.

  • raw_skull_output_path (str or Path, optional) – Path to save the raw modality data with skull.

  • raw_defaced_output_path (str or Path, optional) – Path to save the raw defaced modality data.

  • normalized_bet_output_path (str or Path, optional) – Path to save the normalized brain extracted modality data. Requires a normalizer.

  • normalized_skull_output_path (str or Path, optional) – Path to save the normalized modality data with skull. Requires a normalizer.

  • normalized_defaced_output_path (str or Path, optional) – Path to save the normalized defaced modality data. Requires a normalizer.

  • atlas_correction (bool, optional) – Indicates whether atlas correction should be performed.

  • bet_mask_output_path (str or Path, optional) – Path to save the brain extraction mask.

  • defacing_mask_output_path (str or Path, optional) – Path to save the defacing mask.

modality_name

Name of the modality.

Type:

str

input_path

Path to the input modality data.

Type:

str or Path

normalizer

An optional normalizer for intensity normalization.

Type:

Normalizer, optional

raw_bet_output_path

Path to save the raw brain extracted modality data.

Type:

str or Path, optional

raw_skull_output_path

Path to save the raw modality data with skull.

Type:

str or Path, optional

raw_defaced_output_path

Path to save the raw defaced modality data.

Type:

str or Path, optional

normalized_bet_output_path

Path to save the normalized brain extracted modality data. Requires a normalizer.

Type:

str or Path, optional

normalized_skull_output_path

Path to save the normalized modality data with skull. Requires a normalizer.

Type:

str or Path, optional

normalized_defaced_output_path

Path to save the normalized defaced modality data. Requires a normalizer.

Type:

str or Path, optional

bet

Indicates whether brain extraction is enabled.

Type:

bool

atlas_correction

Indicates whether atlas correction should be performed.

Type:

bool

bet_mask_output_path

Path to save the brain extraction mask.

Type:

Path, optional

defacing_mask_output_path

Path to save the defacing mask.

Type:

Path, optional

Example

>>> t1_modality = CenterModality(
...     modality_name="T1",
...     input_path="/path/to/input_t1.nii",
...     normalizer=PercentileNormalizer(),
...     raw_bet_output_path="/path/to/raw_bet_t1.nii",
...     normalized_bet_output_path="/path/to/norm_bet_t1.nii",
...     bet_mask_output_path="/path/to/bet_mask_t1.nii",
... )
deface(defacer, defaced_dir_path: str | Path) Path

Deface the current modality using the specified defacer.

Parameters:
  • defacer (Defacer) – The defacer object.

  • defaced_dir_path (str or Path) – Directory to store defacing results.

Returns:

Path to the extracted brain mask.

Return type:

Path

extract_brain_region(brain_extractor: BrainExtractor, bet_dir_path: str | Path) Path

Extract the brain region using the specified brain extractor.

Parameters:
  • brain_extractor (BrainExtractor) – The brain extractor object.

  • bet_dir_path (str or Path) – Directory to store brain extraction results.

Returns:

Path to the extracted brain mask.

Return type:

Path

save_mask(mask_path: str | Path, output_path: Path) None

Save the mask to the specified output path.

Parameters:
  • mask_path (Union[str, Path]) – Mask NifTI file path.

  • output_path (Path) – Output NifTI file path.

class brainles_preprocessing.modality.Modality(modality_name: str, input_path: str | Path, normalizer: Normalizer | None = None, raw_bet_output_path: str | Path | None = None, raw_skull_output_path: str | Path | None = None, raw_defaced_output_path: str | Path | None = None, normalized_bet_output_path: str | Path | None = None, normalized_skull_output_path: str | Path | None = None, normalized_defaced_output_path: str | Path | None = None, atlas_correction: bool = True)

Bases: object

Represents a medical image modality with associated preprocessing information.

Parameters:
  • modality_name (str) – Name of the modality, e.g., “T1”, “T2”, “FLAIR”.

  • input_path (str or Path) – Path to the input modality data.

  • normalizer (Normalizer, optional) – An optional normalizer for intensity normalization.

  • raw_bet_output_path (str or Path, optional) – Path to save the raw brain extracted modality data.

  • raw_skull_output_path (str or Path, optional) – Path to save the raw modality data with skull.

  • raw_defaced_output_path (str or Path, optional) – Path to save the raw defaced modality data.

  • normalized_bet_output_path (str or Path, optional) – Path to save the normalized brain extracted modality data. Requires a normalizer.

  • normalized_skull_output_path (str or Path, optional) – Path to save the normalized modality data with skull. Requires a normalizer.

  • normalized_defaced_output_path (str or Path, optional) – Path to save the normalized defaced modality data. Requires a normalizer.

  • atlas_correction (bool, optional) – Indicates whether atlas correction should be performed.

modality_name

Name of the modality.

Type:

str

input_path

Path to the input modality data.

Type:

str or Path

normalizer

An optional normalizer for intensity normalization.

Type:

Normalizer, optional

raw_bet_output_path

Path to save the raw brain extracted modality data.

Type:

str or Path, optional

raw_skull_output_path

Path to save the raw modality data with skull.

Type:

str or Path, optional

raw_defaced_output_path

Path to save the raw defaced modality data.

Type:

str or Path, optional

normalized_bet_output_path

Path to save the normalized brain extracted modality data. Requires a normalizer.

Type:

str or Path, optional

normalized_skull_output_path

Path to save the normalized modality data with skull. Requires a normalizer.

Type:

str or Path, optional

normalized_defaced_output_path

Path to save the normalized defaced modality data. Requires a normalizer.

Type:

str or Path, optional

bet

Indicates whether brain extraction is enabled.

Type:

bool

atlas_correction

Indicates whether atlas correction should be performed.

Type:

bool

Example

>>> t1_modality = Modality(
...     modality_name="T1",
...     input_path="/path/to/input_t1.nii",
...     normalizer=PercentileNormalizer(),
...     raw_bet_output_path="/path/to/raw_bet_t1.nii",
...     normalized_bet_output_path="/path/to/norm_bet_t1.nii",
... )
apply_bet_mask(brain_extractor: BrainExtractor, mask_path: str | Path, bet_dir: str | Path) None

Apply a brain mask to the current modality using the specified brain extractor.

Parameters:
  • brain_extractor (BrainExtractor) – The brain extractor object.

  • mask_path (str or Path) – Path to the brain mask.

  • bet_dir (str or Path) – Directory to store computed bet images.

Returns:

None

apply_deface_mask(defacer: Defacer, mask_path: str | Path, deface_dir: str | Path) None

Apply a deface mask to the current modality using the specified brain extractor.

Parameters:
  • defacer (Defacer) – The Defacer object.

  • mask_path (str or Path) – Path to the deface mask.

  • defaced_masked_dir_path (str or Path) – Directory to store masked images.

property bet: bool

Check if any brain extraction output is specified.

Returns:

True if any brain extraction output is specified, False otherwise.

Return type:

bool

deface(defacer, defaced_dir_path: str | Path) Path

WARNING: Legacy method. Please Migrate to use the CenterModality Class. Will be removed in future versions.

Deface the current modality using the specified defacer.

Parameters:
  • defacer (Defacer) – The defacer object.

  • defaced_dir_path (str or Path) – Directory to store defacing results.

Returns:

Path to the extracted brain mask.

Return type:

Path

extract_brain_region(brain_extractor: BrainExtractor, bet_dir_path: str | Path) Path

WARNING: Legacy method. Please Migrate to use the CenterModality Class. Will be removed in future versions.

Extract the brain region using the specified brain extractor.

Parameters:
  • brain_extractor (BrainExtractor) – The brain extractor object.

  • bet_dir_path (str or Path) – Directory to store brain extraction results.

Returns:

Path to the extracted brain mask.

Return type:

Path

normalize(temporary_directory: str | Path, store_unnormalized: str | Path | None = None) None

Normalize the image using the specified normalizer.

Parameters:
  • temporary_directory (str or Path) – Path to the temporary directory.

  • store_unnormalized (str or Path, optional) – Path to store unnormalized images.

Returns:

None

register(registrator: Registrator, fixed_image_path: str | Path, registration_dir: str | Path, moving_image_name: str, step: PreprocessorSteps) Path

Register the current modality to a fixed image using the specified registrator.

Parameters:
  • registrator (Registrator) – The registrator object.

  • fixed_image_path (str or Path) – Path to the fixed image.

  • registration_dir (str or Path) – Directory to store registration results.

  • moving_image_name (str) – Name of the moving image.

Returns:

Path to the registration matrix.

Return type:

Path

property requires_deface: bool

Check if any defacing output is specified.

Returns:

True if any defacing output is specified, False otherwise.

Return type:

bool

save_current_image(output_path: str | Path, normalization: bool = False) None

Save the current image to the specified output path.

Parameters:
  • output_path (str or Path) – The output file path.

  • normalization (bool, optional) – If True, apply normalization before saving.

Returns:

None

transform(registrator: Registrator, fixed_image_path: str | Path, registration_dir_path: str | Path, moving_image_name: str, transformation_matrix_path: str | Path, step: PreprocessorSteps) None

Transform the current modality using the specified registrator and transformation matrix.

Parameters:
  • registrator (Registrator) – The registrator object.

  • fixed_image_path (str or Path) – Path to the fixed image.

  • registration_dir_path (str or Path) – Directory to store transformation results.

  • moving_image_name (str) – Name of the moving image.

  • transformation_matrix_path (str or Path) – Path to the transformation matrix.

Returns:

None

preprocessor

class brainles_preprocessing.preprocessor.Preprocessor(center_modality: CenterModality, moving_modalities: List[Modality], registrator: Registrator | None = None, brain_extractor: BrainExtractor | None = None, defacer: Defacer | None = None, atlas_image_path: str | Path | None = None, temp_folder: str | Path | None = None, use_gpu: bool | None = None, limit_cuda_visible_devices: str | None = None)

Bases: object

Preprocesses medical image modalities using coregistration, normalization, brain extraction, and more.

Parameters:
  • center_modality (CenterModality) – The central modality for coregistration.

  • moving_modalities (List[Modality]) – List of modalities to be coregistered to the central modality.

  • registrator (Registrator) – The registrator object for coregistration and registration to the atlas.

  • brain_extractor (Optional[BrainExtractor]) – The brain extractor object for brain extraction.

  • defacer (Optional[Defacer]) – The defacer object for defacing images.

  • atlas_image_path (Optional[str or Path]) – Path to the atlas image for registration (default is the T1 atlas).

  • temp_folder (Optional[str or Path]) – Path to a folder for storing intermediate results.

  • use_gpu (Optional[bool]) – Use GPU for processing if True, CPU if False, or automatically detect if None.

  • limit_cuda_visible_devices (Optional[str]) – Limit CUDA visible devices to a specific GPU ID.

_configure_gpu(use_gpu: bool | None, limit_cuda_visible_devices: str | None = None) None

Configures the environment for GPU usage based on the use_gpu parameter and CUDA availability.

Parameters:

use_gpu (Optional[bool]) – Determines the GPU usage strategy.

static _cuda_is_available() bool

Checks if CUDA is available on the system by attempting to run ‘nvidia-smi’.

Returns:

True if ‘nvidia-smi’ can be executed successfully, indicating CUDA is available.

Return type:

bool

_save_output(src: str | Path, save_dir: str | Path | None)

Save the output from a source directory to the specified save directory.

property all_modalities: List[Modality]

Returns a list of all modalities including the center modality.

ensure_remove_log_file_handler()
property requires_defacing: bool

Returns True if any modality requires defacing otherwise returns False.

run(save_dir_coregistration: str | Path | None = None, save_dir_atlas_registration: str | Path | None = None, save_dir_atlas_correction: str | Path | None = None, save_dir_brain_extraction: str | Path | None = None, save_dir_defacing: str | Path | None = None, log_file: str | Path | None = None)

Execute the preprocessing pipeline, encompassing coregistration, atlas-based registration, atlas correction, and optional brain extraction.

Parameters:
  • save_dir_coregistration (str or Path, optional) – Directory path to save intermediate coregistration results.

  • save_dir_atlas_registration (str or Path, optional) – Directory path to save intermediate atlas registration results.

  • save_dir_atlas_correction (str or Path, optional) – Directory path to save intermediate atlas correction results.

  • save_dir_brain_extraction (str or Path, optional) – Directory path to save intermediate brain extraction results.

  • save_dir_defacing (str or Path, optional) – Directory path to save intermediate defacing results.

  • log_file (str or Path, optional) – Path to save the log file. Defaults to a timestamped file in the current directory.

This method orchestrates the entire preprocessing workflow by sequentially performing:

  1. Co-registration: Aligning moving modalities to the central modality.

  2. Atlas Registration: Aligning the central modality to a predefined atlas.

  3. Atlas Correction: Applying additional correction in atlas space if specified.

  4. Brain Extraction: Optionally extracting brain regions using specified masks. Only executed if any modality requires a brain extraction output (or a defacing output that requires prior brain extraction).

  5. Defacing: Optionally deface images to remove facial features. Only executed if any modality requires a defacing output.

Results are saved in the specified directories, allowing for modular and configurable output storage.

run_atlas_correction(save_dir_atlas_correction: str | Path | None = None) None

Apply optional atlas correction to moving modalities.

Parameters:

save_dir_atlas_correction (Optional[str or Path], optional) – Directory path to save intermediate atlas correction results. Defaults to None.

run_atlas_registration(save_dir_atlas_registration: str | Path | None = None) None

Register center modality to atlas.

Parameters:

save_dir_atlas_registration (Optional[str or Path], optional) – Directory path to save intermediate atlas registration results. Defaults to None.

run_brain_extraction(save_dir_brain_extraction: str | Path | None = None) None

Extract brain regions using specified BrainExtractor.

Parameters:

save_dir_brain_extraction (Optional[str or Path], optional) – Directory path to save intermediate brain extraction results. Defaults to None.

run_coregistration(save_dir_coregistration: str | Path | None = None) None

Coregister moving modalities to center modality.

Parameters:

save_dir_coregistration (str, optional) – Directory path to save intermediate coregistration results.

run_defacing(save_dir_defacing: str | Path | None = None) None

Deface images to remove facial features using specified Defacer.

Parameters:

save_dir_defacing (Optional[str or Path], optional) – Directory path to save intermediate defacing results. Defaults to None.