moosez package

Submodules

moosez.constants module

This module contains the constants that are used in the moosez.

Added in version 3.0.0.

moosez.constants.USAGE_MESSAGE = '\nUsage:\n  moosez -d <MAIN_DIRECTORY> -m <MODEL_NAMES> -b\nExample:  \n  moosez -d /Documents/Data_to_moose/ -m clin_ct_organs\n\nDescription:\n  MOOSE (Multi-organ objective segmentation) - A data-centric AI solution that\n  generates multilabel organ segmentations for systemic TB whole-person research.'

This module contains the constants that are used in the moosez.

Constants are values that are fixed and do not change during the execution of a program. They are used to store values that are used repeatedly throughout the program, such as file paths, folder names, and display parameters.

This module contains the following constants:

• ALLOWED_MODALITIES: A constant that stores a list of allowed modalities for the moosez algorithm.

• ANSI_ORANGE: A constant that stores the ANSI color code for orange.

• ANSI_GREEN: A constant that stores the ANSI color code for green.

• ANSI_VIOLET: A constant that stores the ANSI color code for violet.

• ANSI_RESET: A constant that stores the ANSI color code for resetting the color.

• TRACER_FDG: A constant that stores the name of the tracer used by the moosez algorithm.

• SEGMENTATIONS_FOLDER: A constant that stores the name of the folder that contains the segmentations generated by

  the moosez algorithm.

• STATS_FOLDER: A constant that stores the name of the folder that contains the statistics generated by

  the moosez algorithm.

• INTERPOLATION: A constant that stores the interpolation method used by the moosez algorithm.

• CHUNK_THRESHOLD: A constant that stores the chunk threshold used by the moosez algorithm.

• TUMOR_LABEL: A constant that stores the label used for tumors by the moosez algorithm.

• MIP_ROTATION_STEP: A constant that stores the MIP rotation step used by the moosez algorithm.

• DISPLAY_VOXEL_SPACING: A constant that stores the display voxel spacing used by the moosez algorithm.

• FRAME_DURATION: A constant that stores the frame duration used by the moosez algorithm.

This module is imported by other modules in the moosez package and the constants are used throughout the package to provide fixed values that are used repeatedly.

moosez.display module

moosez.download module

moosez.download.download_enhance_data(download_directory: str | None, output_manager: OutputManager)

moosez.download.get_default_download_folder()

moosez.file_utilities module

moosez.file_utilities.copy_file(file: str, destination: str) → None

Copies a file to the specified destination.

Parameters:

• file (str) – The path to the file to be copied.

• destination (str) – The path to the destination directory.

moosez.file_utilities.copy_files_to_destination(files: list[str], destination: str) → None

Copies the files inside the list to the destination directory in a parallel fashion.

Parameters:

• files (list) – The list of files to be copied.

• destination (str) – The path to the destination directory.

moosez.file_utilities.create_directory(directory_path: str) → None

Creates a directory at the specified path.

Parameters:

directory_path (str) – The path to the directory.

moosez.file_utilities.find_pet_file(folder: str) → str | None

Finds the PET file in the specified folder.

Parameters:

folder (str) – The path to the folder.

Returns:

The path to the PET file.

Return type:

str

moosez.file_utilities.get_files(directory: str, prefix: str, suffix: str | tuple) → list[str]

Returns the list of files in the directory with the specified wildcard.

Parameters:

• directory (str) – The directory path.

• suffix (str) – The wildcard to be used.

• prefix (str) – The wildcard to be used.

Returns:

The list of files.

Return type:

list

moosez.file_utilities.get_nifti_file_stem(file_path: str) → str

moosez.file_utilities.moose_folder_structure(parent_directory: str) → tuple[str, str, str]

Creates the moose folder structure.

Parameters:

parent_directory (str) – The path to the parent directory.

Returns:

A tuple containing the paths to the moose directory, output directory, and stats directory.

Return type:

tuple

moosez.file_utilities.select_files_by_modality(moose_compliant_subjects: list[str], modality_tag: str) → list

Selects the files with the selected modality tag from the moose-compliant folders.

Parameters:

• moose_compliant_subjects (list) – The list of moose-compliant subjects paths.

• modality_tag (str) – The modality tag to be selected.

Returns:

The list of selected files.

Return type:

list

moosez.image_conversion module

moosez.image_conversion.create_dicom_lookup(dicom_dir: str) → dict

Create a lookup dictionary from DICOM files.

Parameters:

dicom_dir (str) – The directory where DICOM files are stored.

Returns:

A dictionary where the key is the anticipated filename that dicom2nifti will produce and the value is the modality of the DICOM series.

Return type:

dict

moosez.image_conversion.dcm2niix(input_path: str) → str

Converts DICOM images into NIfTI images using dcm2niix.

Parameters:

input_path (str) – The path to the folder containing the DICOM files to convert.

Returns:

The path to the folder containing the converted NIfTI files.

Return type:

str

moosez.image_conversion.is_dicom_file(filename: str) → bool

Checks if a file is a DICOM file.

Parameters:

filename (str) – The path to the file to check.

Returns:

True if the file is a DICOM file, False otherwise.

Return type:

bool

moosez.image_conversion.non_nifti_to_nifti(input_path: str, output_manager: OutputManager, output_directory: str = None) → None

Converts any image format known to ITK to NIFTI

param input_path:

The path to the directory or filename to convert to nii.gz.

type input_path:

str

param output_directory:

Optional. The output directory to write the image to. If not specified, the output image will be written to the same directory as the input image.

type output_directory:

str

param output_manager:

The OutputManager for handling console output

type output_manager:

system.OutputManager

return:

None

rtype:

None

raises:

FileNotFoundError if the input path does not exist.

Usage: This function can be used to convert any image format known to ITK to NIFTI. If the input path is a directory, the function will convert all images in the directory to NIFTI format. If the input path is a file, the function will convert the file to NIFTI format. The output image will be written to the specified output directory, or to the same directory as the input image if no output directory is specified.

moosez.image_conversion.remove_accents(unicode_filename: str) → str

Removes accents and special characters from a Unicode filename.

Parameters:

unicode_filename (str) – The Unicode filename to clean.

Returns:

The cleaned filename.

Return type:

str

moosez.image_conversion.rename_nifti_files(nifti_dir: str, dicom_info: dict) → None

Rename NIfTI files based on a lookup dictionary.

Parameters:

• nifti_dir (str) – The directory where NIfTI files are stored.

• dicom_info (dict) – A dictionary where the key is the anticipated filename that dicom2nifti will produce and the value is the modality of the DICOM series.

moosez.image_conversion.standardize_to_nifti(parent_dir: str, output_manager: OutputManager) → None

Converts all non-NIfTI images in a parent directory and its subdirectories to NIfTI format.

Parameters:

• parent_dir (str) – The path to the parent directory containing the images to convert.

• output_manager (system.OutputManager) – The output manager to handle console and log output.

Returns:

None

moosez.image_processing module

class moosez.image_processing.ImageChunker

Bases: object

static array_to_chunks(image_array: ndarray, splits_per_dimension: list[int] | tuple[int, ...], overlap_per_dimension: list[int] | tuple[int, ...])

static chunks_to_array(image_chunks: list[ndarray], image_chunk_positions: dict, final_shape: list[int] | tuple[int, ...]) → ndarray

static determine_splits(image_array: ndarray) → tuple

class moosez.image_processing.ImageResampler

Bases: object

static chunk_along_axis(axis: int) → int

Determines the maximum number of evenly-sized chunks that the axis can be split into. Each chunk is at least of size CHUNK_THRESHOLD.

Parameters:

axis (int) – Length of the axis.

Returns:

The maximum number of evenly-sized chunks.

Return type:

int

Raises:

ValueError – If axis is negative or if CHUNK_THRESHOLD is less than or equal to 0.

static resample_chunk_SimpleITK(image_chunk: array, input_spacing: tuple, interpolation_method: int, output_spacing: tuple, output_size: tuple) → array

Resamples a dask array chunk.

Parameters:

• image_chunk (da.array) – The chunk (part of an image) to be resampled.

• input_spacing (tuple) – The original spacing of the chunk (part of an image).

• interpolation_method (int) – SimpleITK interpolation type.

• output_spacing (tuple) – Spacing of the newly resampled chunk.

• output_size (tuple) – Size of the newly resampled chunk.

Returns:

The resampled chunk (part of an image).

Return type:

da.array

static resample_image_SimpleITK_DASK(sitk_image: Image, interpolation: str, output_spacing: tuple = (1.5, 1.5, 1.5), output_size: tuple = None) → Image

Resamples a sitk_image using Dask and SimpleITK.

Parameters:

• sitk_image (sitk.Image) – The SimpleITK image to be resampled.

• interpolation (str) – nearest|linear|bspline.

• output_spacing (tuple) – The desired output spacing of the resampled sitk_image.

• output_size (tuple) – The new size to use.

Returns:

The resampled sitk_image as SimpleITK.Image.

Return type:

sitk.Image

Raises:

ValueError – If the interpolation method is not supported.

static resample_image_SimpleITK_DASK_array(sitk_image: Image, interpolation: str, output_spacing: tuple = (1.5, 1.5, 1.5), output_size: tuple = None) → array

static resample_segmentation(reference_image: Image, segmentation_image: Image)

static reslice_identity(reference_image: Image, moving_image: Image, output_image_path: str = None, is_label_image: bool = False) → Image

Reslices an image to the same space as another image.

Parameters:

• reference_image (SimpleITK.Image) – The reference image.

• moving_image (SimpleITK.Image) – The image to reslice to the reference image.

• output_image_path (str) – Path to the resliced image. Default is None.

• is_label_image (bool) – Determines if the image is a label image. Default is False.

Returns:

The resliced image as SimpleITK.Image.

Return type:

SimpleITK.Image

moosez.image_processing.confirm_orientation(image: Nifti1Image) → tuple[Nifti1Image, bool]

moosez.image_processing.confirm_orthonormality(image: Nifti1Image) → tuple[Nifti1Image, bool]

moosez.image_processing.convert_to_sitk(image: Nifti1Image) → Image

moosez.image_processing.determine_orientation_code(image: Nifti1Image) → [tuple | list, <class 'str'>]

moosez.image_processing.expand_segmentation_fov(limited_fov_segmentation_array: ndarray, original_fov_info: dict) → ndarray

moosez.image_processing.get_intensity_statistics(image: Image, mask_image: Image, model: Model, out_csv: str) → None

Get the intensity statistics of a NIFTI image file.

Parameters:

• image (sitk.Image) – The source image from which the intensity statistics are calculated.

• mask_image (sitk.Image) – The multilabel mask image.

• model (Model) – The model.

• out_csv (str) – The path to the output CSV file.

Returns:

None

moosez.image_processing.get_shape_statistics(mask_image: Image, model: Model, out_csv: str) → None

Get the shape statistics of a NIFTI image file.

Parameters:

• mask_image (sitk.Image) – The multilabel mask image.

• model (Model) – The model.

• out_csv (str) – The path to the output CSV file.

Returns:

None

moosez.image_processing.largest_connected_component(segmentation_array, intensities)

Extracts the largest connected component for one or more specific intensities from a multilabel segmentation array and returns a new multilabel array where the largest components retain their original intensity.

Parameters: - segmentation_array: 3D or 2D numpy array with multiple labels. - intensities: A single intensity or a list of intensities for which the largest component(s) should be extracted.

Returns: - largest_components_multilabel: A multilabel array of the same shape as segmentation_array, where the largest

connected component(s) of the specified intensity or intensities retain their original intensity, and all other areas are 0.

moosez.image_processing.limit_fov(image_array: array, segmentation_array: array, fov_label: list[int] | int, largest_component_only: bool = False)

moosez.image_processing.standardize_image(image_path: str, output_manager: OutputManager, standardization_output_path: str | None) → Image

moosez.input_validation module

moosez.input_validation.determine_model_expectations(model_routine: dict[tuple, list[ModelWorkflow]], output_manager: OutputManager) → list

Display expected modality for the model.

This function displays the expected modality for the given model name. It also checks for a special case where ‘FDG-PET-CT’ should be split into ‘FDG-PET’ and ‘CT’.

Parameters:

• model_routine (dict[tuple, list[models.ModelWorkflow]]) – The model routine

• output_manager (system.OutputManager) – The output manager

Returns:

A list of modalities.

Return type:

list

moosez.input_validation.select_moose_compliant_subjects(subject_paths: list[str], modality_tags: list[str], output_manager: OutputManager) → list[str]

Selects the subjects that have the files that have names that are compliant with the moosez.

Parameters:

• subject_paths (List[str]) – The path to the list of subjects that are present in the parent directory.

• modality_tags (List[str]) – The list of appropriate modality prefixes that should be attached to the files for them to be moose compliant.

• output_manager (system.OutputManager) – The output manager that will be used to write the output files.

Returns:

The list of subject paths that are moose compliant.

Return type:

List[str]

moosez.moosez module

moosez.moosez.main()

moosez.moosez.moose(input_data: str | tuple[ndarray, tuple[float, float, float]] | Image, model_names: str | list[str], output_dir: str = None, accelerator: str = None) → str | Image | ndarray

Execute the MOOSE 3.0 image segmentation process.

Parameters:

• input_data – The input data to process, which can be one of the following: - str: A file path to a NIfTI file. - tuple[numpy.ndarray, tuple[float, float, float]]: A tuple containing a numpy array and spacing. - SimpleITK.Image: An image object to process.

• model_names (str or list[str]) – The name(s) of the model(s) to be used for segmentation.

• output_dir (Optional[str]) – Path to the directory where the output will be saved if the input is a file path.

• accelerator (Optional[str]) – Specifies the accelerator type, e.g., “cpu” or “cuda”.

Returns:

The output type aligns with the input type: - str (file path): If input_data is a file path. - SimpleITK.Image: If input_data is a SimpleITK.Image. - numpy.ndarray: If input_data is a numpy array.

Return type:

str or SimpleITK.Image or numpy.ndarray

Example:

>>> moose('/path/to/input/file', '[list, of, models]', '/path/to/output', 'cuda')
>>> moose((numpy_array, (1.5, 1.5, 1.5)), 'model_name', '/path/to/output', 'cuda')
>>> moose(simple_itk_image, 'model_name', '/path/to/output', 'cuda')

moosez.moosez.moose_subject(subject: str, subject_index: int, number_of_subjects: int, model_routine: dict, accelerator: str, output_manager: OutputManager | None, benchmark: bool = False)

moosez.predict module

moosez.predict.cropped_fov_prediction_pipeline(image, segmentation_array, workflow: ModelWorkflow, accelerator, nnunet_log_filename)

Process segmentation by resampling, limiting FOV, and predicting.

Parameters:

image (SimpleITK.Image): The input image. segmentation_array (np.array): The segmentation array to be processed. workflow (models.ModelWorkflow): List of routines where the second element contains model info. accelerator (any): The accelerator used for prediction. nnunet_log_filename (str): Path to the nnunet log file.

Returns:

model (str): The model name used in the process. segmentation_array (np.array): The final processed segmentation array.

moosez.predict.initialize_predictor(model: Model, accelerator: str) → nnUNetPredictor

Initializes the model for prediction.

Parameters:

• model (Model) – The model object.

• accelerator (str) – The accelerator for prediction.

Returns:

The initialized predictor object.

Return type:

nnUNetPredictor

moosez.predict.predict_from_array_by_iterator(image_array: ndarray, model: Model, accelerator: str, nnunet_log_filename: str = None)

moosez.predict.preprocessing_iterator_from_array(image_array: ~numpy.ndarray, image_properties: dict, predictor: ~nnunetv2.inference.predict_from_raw_data.nnUNetPredictor) -> (<built-in function iter>, <class 'list'>)

moosez.resources module

Module contents

moosez.moose(input_data: str | tuple[ndarray, tuple[float, float, float]] | Image, model_names: str | list[str], output_dir: str = None, accelerator: str = None) → str | Image | ndarray

Execute the MOOSE 3.0 image segmentation process.

Parameters:

• input_data – The input data to process, which can be one of the following: - str: A file path to a NIfTI file. - tuple[numpy.ndarray, tuple[float, float, float]]: A tuple containing a numpy array and spacing. - SimpleITK.Image: An image object to process.

• model_names (str or list[str]) – The name(s) of the model(s) to be used for segmentation.

• output_dir (Optional[str]) – Path to the directory where the output will be saved if the input is a file path.

• accelerator (Optional[str]) – Specifies the accelerator type, e.g., “cpu” or “cuda”.

Returns:

The output type aligns with the input type: - str (file path): If input_data is a file path. - SimpleITK.Image: If input_data is a SimpleITK.Image. - numpy.ndarray: If input_data is a numpy array.

Return type:

str or SimpleITK.Image or numpy.ndarray

Example:

>>> moose('/path/to/input/file', '[list, of, models]', '/path/to/output', 'cuda')
>>> moose((numpy_array, (1.5, 1.5, 1.5)), 'model_name', '/path/to/output', 'cuda')
>>> moose(simple_itk_image, 'model_name', '/path/to/output', 'cuda')