Loading Module#

Module: pyradise.fileio.loading

General#

The loading module provides extensible functionality to load a Subject (including all selected and associated Image) specified by a list of SeriesInfo entries. This module provides the SubjectLoader class to load a single subject and an iterative loader variant called IterableSubjectLoader to load multiple subjects iteratively. Furthermore, the module provides the Loader and the ExplicitLoader base classes from which new loader can be derived.

Class Overview#

The following Loader classes are provided by the loading module:

Class	Description
`Loader`	Base class for all `Loader` subclasses
`ExplicitLoader`	Base class for `Loader` subclasses containing an explicit `load()` method.
`SubjectLoader`	A `Loader` class for explicit loading `Subject` instances.
`IterableSubjectLoader`	A `Loader` class for iterative loading of `Subject` instances.

Details#

class Loader[source]#

Bases: ABC

An abstract base class for all Loader classes. A Loader class typically takes a sequence of SeriesInfo entries and loads the data based on the information provided by the SeriesInfo entries. The data is then returned as a Subject such that it can be used directly for further processing with for example the process package or the writing module.

class ExplicitLoader[source]#

Bases: Loader, ABC

An abstract Loader class that implements a load() method such that multiple sets of SeriesInfo entries can be loaded with the same Loader instance.

abstract load(info)[source]#

Load the Subject.

Parameters:: info (Tuple[SeriesInfo, ...]) – The SeriesInfo entries to be loaded.
Returns:: The loaded Subject.
Return type:: Subject

class SubjectLoader(intensity_pixel_value_type=8, segmentation_pixel_value_type=1, fill_hole_search_distance=0)[source]#

Bases: ExplicitLoader

An ExplicitLoader for loading a Subject based on its SeriesInfo entries. This loader can load both DICOM data (i.e. DicomSeriesInfo) and discrete image data (i.e. FileSeriesInfo). The loader validates the provided SeriesInfo entries before loading and raises appropriate errors if the information is not valid.

Examples

Load and normalize NIFTI files and save the subject as NRRD files:

>>> from argparse import ArgumentParser
>>> from pyradise.fileio import (SubjectFileCrawler, SubjectLoader,
>>>                              SubjectWriter, ImageFileFormat)
>>> from pyradise.process import (ZScoreNormFilter,
>>>                               ZScoreNormFilterParams)
>>>
>>>
>>> def main(input_path: str, output_path: str, subject_name: str) -> None:
>>>   # Crawl the input directory for compressed NIFTI files
>>>   info = SubjectFileCrawler(input_path, subject_name, 'nii.gz').execute()
>>>
>>>   # Load the subject
>>>   subject = SubjectLoader().load(info)
>>>
>>>   # Perform the normalization
>>>   normalization_params = ZScoreNormFilterParams(loop_axis=1)
>>>   normalization_filter = ZScoreNormFilter(normalization_params)
>>>   subject = normalization_filter.execute(subject)
>>>
>>>   # Write the subject to the output directory
>>>   writer = SubjectWriter(ImageFileFormat.NRRD)
>>>   writer.write(output_path, subject, write_transforms=False)
>>>
>>>
>>> if __name__ == '__main__':
>>>   parser = ArgumentParser()
>>>   parser.add_argument('input_path', type=str, help='The input directory.')
>>>   parser.add_argument('output_path', type=str, help='The output directory.')
>>>   parser.add_argument('subject_name', type=str, help='The name of the subject.')
>>>   args = parser.parse_args()
>>>
>>>   main(args.input_path, args.output_path, args.subject_name)

Load DICOM data and save the converted data as NIFTI files:

>>> from argparse import ArgumentParser
>>> from pyradise.fileio import SubjectDicomCrawler, SubjectLoader, SubjectWriter
>>>
>>>
>>> def main(input_path: str, output_path: str) -> None:
>>>   # Crawl the input directory for DICOM data
>>>   # Note: We assume that the modality configuration file (modality_config.json)
>>>   # is existing.
>>>   info = SubjectDicomCrawler(input_path).execute()
>>>
>>>   # Load the subject
>>>   subject = SubjectLoader().load(info)
>>>
>>>   # Write the subject to the output directory
>>>   writer = SubjectWriter()
>>>   writer.write(output_path, subject, write_transforms=False)
>>>
>>>
>>> if __name__ == '__main__':
>>>   parser = ArgumentParser()
>>>   parser.add_argument('input_path', type=str, help='The input directory.')
>>>   parser.add_argument('output_path', type=str, help='The output directory.')
>>>   args = parser.parse_args()
>>>
>>>   main(args.input_path, args.output_path)

Parameters:

intensity_pixel_value_type (int) – The pixel value type of the intensity imagesm when loading discrete image files (default: sitk.sitkFloat32).
segmentation_pixel_value_type (int) – The pixel value type of the segmentation images when loading discrete files (default: sitk.sitkUInt8).
fill_hole_search_distance (int) – The search distance for the hole filling algorithm. If the search distance is set to zero the hole filling algorithm is omitted. The search distance must be an odd number larger than 1 (default: 0).

load(info)[source]#

Load a Subject from the provided SeriesInfo entries.

Parameters:

info (Tuple[SeriesInfo, ...]) – The SeriesInfo entries containing the necessary information for loading the subject.

Raises:

ValueError – If info is an empty tuple.
ValueError – If info is not a tuple of SeriesInfo entries.
ValueError – If the patient name and patient id of the provided SeriesInfo entries are not equal.
ValueError – If not all referenced DicomSeriesImageInfo entries are provided for registration.
ValueError – If not all referenced DicomSeriesImageInfo entries are provided for RTSS loading.

Returns:

The loaded subject.

Return type:

Subject

class IterableSubjectLoader(info, intensity_pixel_value_type=8, segmentation_pixel_value_type=1, fill_hole_search_distance=0)[source]#

Bases: Loader

An Loader for loading a sequence of Subject s based on their SeriesInfo entries. This loader can load both DICOM data (i.e. DicomSeriesInfo) and discrete image data (i.e. FileSeriesInfo). The loader validates the provided SeriesInfo entries before loading and raises appropriate errors if the information is not valid.

Notes

For loading large DICOM dataset we recommend to use the SubjectLoader instead because the antecedent crawling process can require a lot of computation time and memory.

Raises:

ValueError – If info is an empty tuple.
ValueError – If info is not a tuple of tuples of SeriesInfo entries.

Parameters:

info (Tuple[Tuple[SeriesInfo, ...], ...]) – The SeriesInfo entries for all subjects to load.
intensity_pixel_value_type (int) – The pixel value type of the intensity imagesm when loading discrete image files (default: sitk.sitkFloat32).
segmentation_pixel_value_type (int) – The pixel value type of the segmentation images when loading discrete files (default: sitk.sitkUInt8).
fill_hole_search_distance (int) – The search distance for the hole filling algorithm. If the search distance is set to zero the hole filling algorithm is omitted. The search distance must be an odd number larger than 1 (default: 0).

Examples

Load, normalize and save a NIFTI dataset with multiple subjects:

>>> from argparse import ArgumentParser
>>> from pyradise.fileio import (DatasetFileCrawler, IterableSubjectLoader,
>>>                              SubjectWriter)
>>> from pyradise.process import (ZScoreNormFilter,
>>>                               ZScoreNormFilterParams)
>>>
>>>
>>> def main(input_path: str, output_path: str) -> None:
>>>     # Crawl the dataset info
>>>     info = DatasetFileCrawler(input_path, '.nii.gz').execute()
>>>
>>>     # Construct the loader
>>>     loader = IterableSubjectLoader(info)
>>>
>>>     # Construct the normalization filter
>>>     normalization_params = ZScoreNormFilterParams(loop_axis=1)
>>>     normalization_filter = ZScoreNormFilter(normalization_params)
>>>
>>>     # Construct the writer
>>>     writer = SubjectWriter()
>>>
>>>     # Iteratively load the subjects
>>>     for subject in loader:
>>>         # Normalize the images
>>>         subject = normalization_filter.execute(subject)
>>>
>>>         # Save the subject
>>>         writer.write_to_subject_folder(output_path, subject, write_transforms=False)
>>>
>>>
>>> if __name__ == '__main__':
>>>     parser = ArgumentParser()
>>>     parser.add_argument('--input_path', type=str,
>>>                         help='The dataset input directory.')
>>>     parser.add_argument('--output_path', type=str,
>>>                         help='The dataset output directory.')
>>>     args = parser.parse_args()
>>>
>>>     main(args.input_path, args.output_path)