Subject Module#

Module: pyradise.data.subject

General#

The subject module provides the Subject which is the main data holding object in PyRaDiSe. The subject is constructed during loading an is used through the whole processing in PyRaDiSe.

main concept data model — Fig. 5 Schematic illustration of the subject and its contents.#

Class Overview#

The following class is provided by the subject module:

Class	Description
`Subject`	Class that holds all information about a subject / patient.

Details#

class Subject(name, images=None, data=None)[source]#

Bases: object

The Subject is the main data object which holds all IntensityImage s and SegmentationImage s associated with the subject. Furthermore, it can hold any type of additional data associated with the patient. Currently, the routines implemented in PyRaDiSe do not use this mechanism so it can be used freely by the user.

Parameters:

name (str) – The name of the subject.
images (Optional[Union[Image, Sequence[Image]]]) – One or multiple images to add to the subject.
data (Optional[Dict[str, Any]]) – Additional data which is associated with the subject.

Examples

The following example demonstrates the manual construction of a Subject:

>>> from argparse import ArgumentParser
>>> from typing import Tuple
>>> import os
>>>
>>> import SimpleITK as sitk
>>>
>>> from pyradise.data import (Subject, IntensityImage, SegmentationImage,
>>>                            Modality, Organ, Annotator)
>>> from pyradise.fileio import SubjectWriter, ImageFileFormat
>>>
>>>
>>> def get_segmentation_file_paths(path: str,
>>>                                 valid_organs: Tuple[Organ, ...]
>>>                                 ) -> Tuple[str]:
>>>     file_paths = []
>>>
>>>     for file in os.listdir(path):
>>>         if not file.endswith('.nii.gz'):
>>>             continue
>>>
>>>         if any(entry.name in file for entry in valid_organs):
>>>             file_paths.append(os.path.join(path, file))
>>>
>>>     return tuple(sorted(file_paths))
>>>
>>>
>>> def get_intensity_file_paths(path: str,
>>>                              valid_modalities: Tuple[Modality, ...]
>>>                              ) -> Tuple[str]:
>>>     file_paths = []
>>>
>>>     for file in os.listdir(path):
>>>         if not file.endswith('.nii.gz'):
>>>             continue
>>>
>>>         if any(entry.get_name() in file for entry in valid_modalities):
>>>             file_paths.append(os.path.join(path, file))
>>>
>>>     return tuple(sorted(file_paths))
>>>
>>>
>>> def main(input_dir: str,
>>>          output_dir: str
>>>          ) -> None:
>>>     # Retrieve image file paths
>>>     organs = (Organ('Brainstem'), Organ('Eyes'),
>>>               Organ('Hippocampi'), Organ('OpticNerves'))
>>>     modalities = (Modality('CT'), Modality('T1c'),
>>>                   Modality('T1w'), Modality('T2w'))
>>>
>>>     segmentation_file_paths = get_segmentation_file_paths(input_dir, organs)
>>>     intensity_file_paths = get_intensity_file_paths(input_dir, modalities)
>>>
>>>     # Load the segmentation image files
>>>     images = []
>>>     for path, organ in zip(segmentation_file_paths, organs):
>>>         image = SegmentationImage(sitk.ReadImage(path, sitk.sitkUInt8),
>>>                                   organ, Annotator.get_default())
>>>         images.append(image)
>>>
>>>     # Load the intensity image files
>>>     for path, modality in zip(intensity_file_paths, modalities):
>>>         image = IntensityImage(sitk.ReadImage(path, sitk.sitkFloat32),
>>>                                modality)
>>>         images.append(image)
>>>
>>>     # Construct the subject
>>>     subject = Subject(os.path.basename(input_dir), images)
>>>
>>>     # Display the subject name and properties of the intensity and
>>>     # segmentation images
>>>     print(f'Subject {subject.get_name()} contains the following images:')
>>>
>>>     for image in subject.intensity_images:
>>>         print(f'Intensity image of modality {image.get_modality(True)} '
>>>               f'with size: {image.get_size()}')
>>>
>>>     for image in subject.segmentation_images:
>>>         print(f'Segmentation image of {image.get_organ(True)} '
>>>               f'with size: {image.get_size()}')
>>>
>>>     # Write the subject to disk
>>>     SubjectWriter(ImageFileFormat.NRRD).write(output_dir, subject,
>>>                                               write_transforms=False)
>>>
>>>
>>> if __name__ == '__main__':
>>>     parser = ArgumentParser()
>>>     parser.add_argument('-input_dir', type=str)
>>>     parser.add_argument('-output_dir', type=str)
>>>     args = parser.parse_args()
>>>
>>>     main(args.input_dir, args.output_dir)
>>>
>>> # Output:
>>> # Subject subject_1 contains the following images:
>>> # Intensity image of modality CT with size: (256, 256, 256)
>>> # Intensity image of modality T1c with size: (256, 256, 256)
>>> # Intensity image of modality T1w with size: (256, 256, 256)
>>> # Intensity image of modality T2w with size: (256, 256, 256)
>>> # Segmentation image of Brainstem with size: (256, 256, 256)
>>> # Segmentation image of Eyes with size: (256, 256, 256)
>>> # Segmentation image of Hippocampi with size: (256, 256, 256)
>>> # Segmentation image of OpticNerves with size: (256, 256, 256)

get_name()[source]#

Get the name of the subject.

Returns:: The name of the subject.
Return type:: str

get_modalities(as_str=False)[source]#

Get the modalities of the subject-associated intensity images.

Parameters:: as_str (bool, optional) – Whether to return the modalities as strings. Defaults to False.
Returns:: The modalities of the intensity images as objects or strings.
Return type:: Tuple[Optional[Modality, str], …]

get_organs(as_str=False)[source]#

Get the organs of the subject-associated segmentation images.

Parameters:: as_str (bool, optional) – Whether to return the organs as strings. Defaults to False.
Returns:: The organs of the segmentation images as objects or strings.
Return type:: Tuple[Optional[Organ, str], …]

get_annotators(as_str=False)[source]#

Get the annotators of the subject-associated segmentation images.

Parameters:: as_str (bool, optional) – Whether to return the annotators as strings. Defaults to False.
Returns:: Annotators of the segmentation images as objects or strings
Return type:: Tuple[Optional[Rater, str], …]

add_image(image, force=False)[source]#

Add an image to the subject.

Parameters:

image (Union[IntensityImage, SegmentationImage]) – The image to add to the subject.
force (bool) – Indicates if addition should be performed even if a similar (same modality for intensity images or same organ for segmentation images) image is already contained (default: False).

Raises:

ValueError – If an intensity image with similar modality is already contained or a segmentation image with similar organ is already contained and force if False.

Return type:

None

Returns:

None

add_images(images, force=False)[source]#

Add multiple images to the subject.

Parameters:

images (Sequence[Union[IntensityImage, SegmentationImage]]) – The images to add to the subject.
force (bool) – Indicates if addition should be performed even if a similar (same modality for intensity images or same organ for segmentation images) image is already contained (default: False).

Return type:

None

Returns:

None

get_images()[source]#

Get all images of the subject.

Returns:: All images of the subject.
Return type:: List[Union[IntensityImage, SegmentationImage]]

get_image_by_modality(modality, return_first_on_multiple=False)[source]#

Get one intensity image by its modality.

Parameters:

modality (Union[Modality, str]) – The modality of the image to retrieve.
return_first_on_multiple (bool) – Indicates if the first found image should be returned if there are multiple candidates, otherwise an error is raised on multiple candidates (default: False).

Returns:

The intensity image or None if there are multiple candidates.

Return type:

Optional[IntensityImage]

get_image_by_organ(organ, return_first_on_multiple=False)[source]#

Get one segmentation image by its organ.

Parameters:

organ (Union[Organ, str]) – The organ of the image to retrieve.
return_first_on_multiple (bool) – Indicates if the first found image should be returned if there are multiple candidates, otherwise an error is raised on multiple candidates (default: False).

Returns:

The segmentation image or None if there are multiple candidates.

Return type:

Optional[SegmentationImage]

get_images_by_annotator(annotator)[source]#

Get one or multiple segmentation images by their annotator.

Parameters:: annotator (Union[Annotator, str]) – The annotator of the image to retrieve.
Returns:: The segmentation images or None if there is no image with this annotator.
Return type:: Optional[Union[SegmentationImage, Tuple[SegmentationImage]]]

get_image_by_organ_and_annotator(organ, annotator, return_first_on_multiple=False)[source]#

Get one segmentation image by its organ and annotator.

Parameters:

organ (Union[Organ, str]) – The organ of the image to retrieve.
annotator (Union[Annotator, str]) – The annotator of the image to retrieve.
return_first_on_multiple (bool) – Indicates if the first found image should be returned if there are multiple candidates, otherwise an error is raised on multiple candidates (default: False).

Returns:

The segmentation image or None if there are multiple candidates.

Return type:

Optional[SegmentationImage]

get_images_by_type(image_type)[source]#

Get all images of a specific type.

Parameters:: image_type (type) – The type of the images to retrieve.
Returns:: A list of all images of the specified type.
Return type:: List[Image]

replace_image(new_image, old_image=None)[source]#

Replace an image in the subject either specified by an old image or by the properties of the new image.

The following properties are used to identify the image to be replaced:

IntensityImage: The Modality of the image.
SegmentationImage: The Organ and the Rater of the image.

Parameters:

new_image (Union[IntensityImage, SegmentationImage]) – The new image which will be inserted into the subject.
old_image (Optional[Union[IntensityImage, SegmentationImage]]) – The old image which will be replaced by the new image. If None, the new image properties are used to find an image to replace (default: None).

Returns:

True if the image is replaced successfully, False otherwise.

Return type:

bool

remove_image_by_modality(modality)[source]#

Remove one or multiple images as specified by the modality.

Parameters:: modality (Union[Modality, str]) – The modality of all images to remove.
Returns:: True when the removal procedure was successful otherwise False.
Return type:: bool

remove_image_by_organ(organ)[source]#

Remove one or multiple images as specified by the organ.

Parameters:: organ (Union[Organ, str]) – The organ of all images to remove.
Returns:: True when the removal procedure was successful otherwise False.
Return type:: bool

remove_image_by_annotator(annotator)[source]#

Remove one or multiple images as specified by the annotator.

Parameters:: annotator (Union[Annotator, str]) – The annotator of all images to remove.
Returns:: True when the removal procedure was successful, otherwise False.
Return type:: bool

remove_image_by_organ_and_annotator(organ, annotator)[source]#

Remove one or multiple images as specified by the organ and annotator.

Parameters:

organ (Union[Organ, str]) – The organ of all images to remove.
annotator (Union[Annotator, str]) – The annotator of all images to remove.

Returns:

True when the removal procedure was successful, otherwise False.

Return type:

bool

remove_image(image)[source]#

Remove a given image from the subject.

Parameters:: image (Union[IntensityImage, SegmentationImage]) – The image to remove from the subject.
Returns:: True when the removal procedure was successful otherwise False.
Return type:: bool

add_data(data)[source]#

Add additional data to the subject.

Parameters:: data (Dict[str, Any]) – The additional datas.
Return type:: None
Returns:: None

add_data_by_key(key, data)[source]#

Add additional data by key to the subject.

Parameters:

key (str) – The key of the additional data.
data (Any) – The additional data.

Return type:

None

Returns:

None

get_data()[source]#

Get the additional data associated with the subject.

Returns:: The additional data associated with the subject.
Return type:: Dict[str, Any]

get_data_by_key(key)[source]#

Get additional data by key or None if the key is not existing.

Parameters:: key (str) – The key of the specific additional data.
Returns:: The data or None.
Return type:: Any

replace_data(key, new_data, add_if_missing=False)[source]#

Replace data by a new value.

Parameters:

key (str) – The key of the additional data.
new_data (Any) – The new additional data.
add_if_missing (bool) – If True, the additional data will be added if the key is not existing (default: False).

Returns:

True if the additional data is replaced successfully, False otherwise.

Return type:

bool

remove_additional_data()[source]#

Remove all additional data from the subject.

Return type:: None
Returns:: None

remove_additional_data_by_key(key)[source]#

Remove additional data by a key from the subject.

Parameters:: key (str) – The key of the additional data.
Returns:: True when the removal procedure was successful otherwise False.
Return type:: bool

playback_transform_tapes()[source]#

Playback the transform tapes.

Return type:: None
Returns:: None