Utilities (mialab.utilities package)

This package contains various classes and functions for the pipeline construction and execution.

The file access module (mialab.utilities.file_access_utilities)

This modules contains utility functions and classes for the access of the file system.

class mialab.utilities.file_access_utilities.BrainImageFilePathGenerator

Represents a brain image file path generator.

The generator is used to convert a human readable image identifier to an image file path, which allows to load the image.

__init__()

Initializes a new instance of the BrainImageFilePathGenerator class.

static get_full_file_path(id_: str, root_dir: str, file_key, file_extension: str) → str

Gets the full file path for an image.

Parameters:

• id (str) – The image identification.

• root_dir (str) – The image’ root directory.

• file_key (object) – A human readable identifier used to identify the image.

• file_extension (str) – The image’ file extension.

Returns:

The images’ full file path.

Return type:

str

class mialab.utilities.file_access_utilities.DataDirectoryFilter

Represents a data directory filter.

The filter is used to

__init__()

Initializes a new instance of the DataDirectoryFilter class.

static filter_directories(dirs: List[str]) → List[str]

Filters a list of directories.

Parameters:

dirs (List[str]) – A list of directories.

Returns:

The filtered list of directories.

Return type:

List[str]

class mialab.utilities.file_access_utilities.DirectoryFilter

Represents an abstract directory filter.

This class is used in FileSystemDataCrawler to filter a list of directories.

abstract static filter_directories(dirs: List[str]) → List[str]

Filters a list of directories.

Parameters:

dirs (List[str]) – A list of directories.

Returns:

The filtered list of directories.

Return type:

List[str]

class mialab.utilities.file_access_utilities.FilePathGenerator

Represents an abstract file path generator.

This class is used in FileSystemDataCrawler to convert a human readable data identifier to an data file path, which allows to load the data.

abstract static get_full_file_path(id_: str, root_dir: str, file_key, file_extension: str) → str

Gets the full file path for a data file.

Parameters:

• id (str) – The data’s identification.

• root_dir (str) – The data file’s root directory.

• file_key (object) – A human readable identifier used to identify the data file.

• file_extension (str) – The data’s file extension.

Returns:

The data’s full file path.

Return type:

str

class mialab.utilities.file_access_utilities.FileSystemDataCrawler(root_dir: str, file_keys: list, file_path_generator: FilePathGenerator, dir_filter: DirectoryFilter | None = None, file_extension: str = '.nii.gz')

Represents a file system data crawler.

Examples

Suppose we have the following directory structure:

/path/to/root_dir
    ./Patient1
        ./Image.mha
        ./GroundTruth.mha
        ./some_text_file.txt
    ./Patient2
        ./Image.mha
        ./GroundTruth.mha
        ./GroundTruthRater2.mha
    ./Atlas
        ./Atlas.mha

We can use the following code to load the images Image.mha and GroundTruth.mha in the directories Patient1 and Patient2:

>>> class MyImgType(enum.Enum):
>>>     T1 = 1
>>>     GroundTruth = 2
>>>
>>> class MyFilePathGenerator(FilePathGenerator):
>>>     @staticmethod
>>>     def get_full_file_path(_id: str, root_dir: str, file_key, file_extension: str) -> str:
>>>         if file_key == MyImgType.T1:
>>>             file_name = 'Image'
>>>         elif file_key == MyImgType.GroundTruth:
>>>             file_name = 'GroundTruth'
>>>         else:
>>>             raise ValueError('Unknown key')
>>>
>>>         return os.path.join(root_dir, file_name + file_extension)
>>>
>>> class MyDirFilter(DirectoryFilter):
>>>     @staticmethod
>>>     def filter_directories(dirs: t.List[str]) -> t.List[str]:
>>>         return sorted([dir_ for dir_ in dirs if dir_.lower().__contains__('patient')])
>>>
>>> crawler = FileSystemDataCrawler('/path/to/root_dir',
>>>                                 [MyImgType.T1, MyImgType.GroundTruth],
>>>                                 MyFilePathGenerator(),
>>>                                 MyDirFilter(),
>>>                                 '.mha')
>>> for id_, path in crawler.data.items():
>>>     print(id_, path)
Patient1 {'Patient1': '/path/to/root_dir/Patient1',
          <MyImgType.T1: 1>: '/path/to/root_dir/Patient1/Image.mha',
          <MyImgType.GroundTruth: 2>: '/path/to/root_dir/Patient1/GroundTruth.mha'}
Patient2 {'Patient2': '/path/to/root_dir/Patient2',
          <MyImgType.T1: 1>: '/path/to/root_dir/Patient2/Image.mha',
          <MyImgType.GroundTruth: 2>: '/path/to/root_dir/Patient2/GroundTruth.mha'}

__init__(root_dir: str, file_keys: list, file_path_generator: FilePathGenerator, dir_filter: DirectoryFilter | None = None, file_extension: str = '.nii.gz')

Initializes a new instance of the FileSystemDataCrawler class.

Parameters:

• root_dir (str) – The path to the root directory, which contains subdirectories with the data.

• file_keys (list) – A list of objects, which represent human readable data identifiers (one identifier for each data file to crawl).

• file_path_generator (FilePathGenerator) – A file path generator, which converts a human readable data identifier to an data file path.

• dir_filter (DirectoryFilter) – A directory filter, which filters a list of directories.

• file_extension (str) – The data file extension (with or without dot).

The multi processor module (mialab.utilities.multi_processor)

Module for the management of multi-process function calls.

class mialab.utilities.multi_processor.BrainImageToPicklableBridge

A BrainImage to PicklableBrainImage bridge.

static convert(brain_image: BrainImage) → PicklableBrainImage

Converts a BrainImage to PicklableBrainImage.

Parameters:

brain_image (BrainImage) – A brain image.

Returns:

The pickable brain image.

Return type:

PicklableBrainImage

class mialab.utilities.multi_processor.DefaultPickleHelper

Default pickle helper class

make_params_picklable(params)

Default function called to ensure that all parameters can be pickled before transferred to the new process. To be overwritten if non-picklable parameters are contained in params.

Parameters:

params (tuple) – Parameters to be rendered picklable.

Returns:

The modified parameters.

Return type:

tuple

make_return_value_picklable(ret_val)

Default function called to ensure that all return values ret_val can be pickled before transferring back to the original process. To be overwritten if non-picklable objects are contained in ret_val.

Parameters:

ret_val – Return values of the function executed in another process.

Returns:

The modified return values.

recover_params(params)

Default function called to recover (from the pickle state) the original parameters in another process. To be overwritten if non-picklable parameters are contained in params.

Parameters:

params (tuple) – Parameters to be recovered.

Returns:

The recovered parameters.

Return type:

tuple

recover_return_value(ret_val)

Default function called to ensure that all return values ret_val can be pickled before transferring back to the original process. To be overwritten if non-picklable objects are contained in ret_val.

Parameters:

ret_val – Return values of the function executed in another process.

Returns:

The modified return values.

class mialab.utilities.multi_processor.MultiProcessor

Class managing multiprocessing

static run(fn: callable, param_list: iter, fn_kwargs: dict | None = None, pickle_helper_cls: type = <class 'mialab.utilities.multi_processor.DefaultPickleHelper'>)

Executes the function fn in parallel (different processes) for each parameter in the parameter list.

Parameters:

• fn (callable) – Function to be executed in another process.

• param_list (List[tuple]) – List containing the parameters for each fn call.

• fn_kwargs (dict) – kwargs for the fn function call.

• pickle_helper_cls – Class responsible for the pickling of the parameters

Returns:

A list of all return values of the fn calls

Return type:

list

class mialab.utilities.multi_processor.PicklableAffineTransform(transform: SimpleITK.Transform)

Represents a transformation that can be pickled.

get_sitk_transformation()

class mialab.utilities.multi_processor.PicklableBrainImage(id_: str, path: str, np_images: dict, image_properties: pymia.data.conversion.ImageProperties, transform: SimpleITK.Transform)

Represents a brain image that can be pickled.

__init__(id_: str, path: str, np_images: dict, image_properties: pymia.data.conversion.ImageProperties, transform: SimpleITK.Transform)

Initializes a new instance of the BrainImage class.

Parameters:

• id (str) – An identifier.

• path (str) – Full path to the image directory.

• np_images (dict) – The images, where the key is a BrainImageTypes and the value is a numpy image.

class mialab.utilities.multi_processor.PicklableToBrainImageBridge

A PicklableBrainImage to BrainImage bridge.

static convert(picklable_brain_image: PicklableBrainImage) → BrainImage

Converts a PicklableBrainImage to BrainImage.

Parameters:

picklable_brain_image (PicklableBrainImage) – A pickable brain image.

Returns:

The brain image.

Return type:

BrainImage

class mialab.utilities.multi_processor.PostProcessingPickleHelper

Post-processing pickle helper class

make_params_picklable(params: Tuple[BrainImage, SimpleITK.Image, SimpleITK.Image, dict])

Ensures that all post-processing parameters can be pickled before transferred to the new process.

Parameters:

params (tuple) – Post-processing parameters to be rendered picklable.

Returns:

The modified post-processing parameters.

Return type:

tuple

make_return_value_picklable(ret_val: SimpleITK.Image) → Tuple[ndarray, pymia.data.conversion.ImageProperties]

Ensures that all post-processing return values ret_val can be pickled before transferring back to the original process.

Parameters:

ret_val (sitk.Image) – Return values of the post-processing function executed in another process.

Returns:

The modified post-processing return values.

recover_params(params: Tuple[PicklableBrainImage, ndarray, ndarray, dict])

Recovers (from the pickle state) the original post-processing parameters in another process.

Parameters:

params (tuple) – Post-processing parameters to be recovered.

Returns:

The recovered post-processing parameters.

Return type:

tuple

recover_return_value(ret_val: Tuple[ndarray, pymia.data.conversion.ImageProperties]) → SimpleITK.Image

Recovers (from the pickle state) the original post-processing return values.

Parameters:

ret_val – Post-processing return values to be recovered.

Returns:

The recovered post-processing return values.

Return type:

sitk.Image

class mialab.utilities.multi_processor.PreProcessingPickleHelper

Pre-processing pickle helper class

make_return_value_picklable(ret_val: BrainImage) → PicklableBrainImage

Ensures that all pre-processing return values ret_val can be pickled before transferring back to the original process.

Parameters:

ret_val (BrainImage) – Return values of the pre-processing function executed in another process.

Returns:

The modified pre-processing return values.

Return type:

PicklableBrainImage

recover_return_value(ret_val: PicklableBrainImage) → BrainImage

Recovers (from the pickle state) the original pre-processing return values.

Parameters:

ret_val (PicklableBrainImage) – Pre-processing return values to be recovered.

Returns:

The recovered pre-processing return values.

Return type:

BrainImage

The pipeline module (mialab.utilities.pipeline_utilities)

This module contains utility classes and functions.

class mialab.utilities.pipeline_utilities.FeatureExtractor(img: BrainImage, **kwargs)

Represents a feature extractor.

__init__(img: BrainImage, **kwargs)

Initializes a new instance of the FeatureExtractor class.

Parameters:

img (structure.BrainImage) – The image to extract features from.

execute() → BrainImage

Extracts features from an image.

Returns:

The image with extracted features.

Return type:

structure.BrainImage

class mialab.utilities.pipeline_utilities.FeatureImageTypes(value)

Represents the feature image types.

ATLAS_COORD = 1

T1w_GRADIENT_INTENSITY = 3

T1w_INTENSITY = 2

T2w_GRADIENT_INTENSITY = 5

T2w_INTENSITY = 4

mialab.utilities.pipeline_utilities.init_evaluator() → pymia.evaluation.evaluator.Evaluator

Initializes an evaluator.

Returns:

An evaluator.

Return type:

eval.Evaluator

mialab.utilities.pipeline_utilities.load_atlas_images(directory: str)

Loads the T1 and T2 atlas images.

Parameters:

directory (str) – The atlas data directory.

mialab.utilities.pipeline_utilities.post_process(img: BrainImage, segmentation: SimpleITK.Image, probability: SimpleITK.Image, **kwargs) → SimpleITK.Image

Post-processes a segmentation.

Parameters:

• img (structure.BrainImage) – The image.

• segmentation (sitk.Image) – The segmentation (label image).

• probability (sitk.Image) – The probabilities images (a vector image).

Returns:

The post-processed image.

Return type:

sitk.Image

mialab.utilities.pipeline_utilities.post_process_batch(brain_images: List[BrainImage], segmentations: List[SimpleITK.Image], probabilities: List[SimpleITK.Image], post_process_params: dict | None = None, multi_process: bool = True) → List[SimpleITK.Image]

Post-processes a batch of images.

Parameters:

• brain_images (List[structure.BrainImageTypes]) – Original images that were used for the prediction.

• segmentations (List[sitk.Image]) – The predicted segmentation.

• probabilities (List[sitk.Image]) – The prediction probabilities.

• post_process_params (dict) – Post-processing parameters.

• multi_process (bool) – Whether to use the parallel processing on multiple cores or to run sequentially.

Returns:

List of post-processed images

Return type:

List[sitk.Image]

mialab.utilities.pipeline_utilities.pre_process(id_: str, paths: dict, **kwargs) → BrainImage

Loads and processes an image.

The processing includes:

• Registration

• Pre-processing

• Feature extraction

Parameters:

• id (str) – An image identifier.

• paths (dict) – A dict, where the keys are an image identifier of type structure.BrainImageTypes and the values are paths to the images.

Return type:

(structure.BrainImage)

mialab.utilities.pipeline_utilities.pre_process_batch(data_batch: Dict[BrainImageTypes, BrainImage], pre_process_params: dict | None = None, multi_process: bool = True) → List[BrainImage]

Loads and pre-processes a batch of images.

The pre-processing includes:

• Registration

• Pre-processing

• Feature extraction

Parameters:

• data_batch (Dict[structure.BrainImageTypes, structure.BrainImage]) – Batch of images to be processed.

• pre_process_params (dict) – Pre-processing parameters.

• multi_process (bool) – Whether to use the parallel processing on multiple cores or to run sequentially.

Returns:

A list of images.

Return type:

List[structure.BrainImage]