Series Information Module#

Module: pyradise.fileio.series_info

General#

The series_info module provides functionality to hold and retrieve information about data entities which are required during the loading procedure for Subject and Image creation. The base class of this module is the SeriesInfo which is named in accordance with the DICOM Standard because it manages information about a single data entity (e.g. a DICOM-RTSS) or a series of associated data entities (e.g. a series of image slices). For each supported type of data this module provides separate classes because the information required for loading varies between the different types of data.

The SeriesInfo instances are typically generated automatically during crawling (see Crawling Module) and render the selection (see Selection Module) of appropriate SeriesInfo instances feasible before executing the time consuming loading procedure. This is especially useful if the user wants to process specific data exclusively and wants to keep the computation time and the memory footprint low. Afterwards, the SeriesInfo instances are used to load the data (see Loading Module) and to create the Subject instance.

Class Overview#

The following SeriesInfo classes are provided:

Class	Description
`SeriesInfo`	Base class for all `SeriesInfo` classes.
`FileSeriesInfo`	Base class for all discrete image file format `SeriesInfo` classes.
`DicomSeriesInfo`	Base class for all DICOM format `SeriesInfo` classes.
`IntensityFileSeriesInfo`	`SeriesInfo` class for discrete intensity image files.
`SegmentationFileSeriesInfo`	`SeriesInfo` class for discrete segmentation image files.
`DicomSeriesImageInfo`	`SeriesInfo` class for DICOM image files.
`DicomSeriesRegistrationInfo`	`SeriesInfo` class for DICOM registration files.
`DicomSeriesRTSSInfo`	`SeriesInfo` class for DICOM-RTSS files.

Details#

class SeriesInfo(path)[source]#

Bases: ABC

An abstract base class for all SeriesInfo classes. A SeriesInfo class is used to retrieve and store content-specific information which is required by the SubjectLoader in order to correctly load the data and to construct a Subject.

Depending on the type of data, the SeriesInfo subclasses retrieve different information which is essential for loading and Subject construction. For example, the DicomSeriesImageInfo retrieves and holds data about the Modality whereas the DicomSeriesRTSSInfo manages information about the Annotator and information about the referenced DICOM image series.

Parameters:: path (Union[str, Tuple[str, ...]]) – The path or paths to the files to load.

get_path()[source]#

Get the file paths assigned to the SeriesInfo instance.

Returns:: The file paths assigned to the SeriesInfo instance.
Return type:: Tuple[str]

get_patient_name()[source]#

Get the patient name.

Returns:: The patient name.
Return type:: str

get_patient_id()[source]#

Get the patient ID.

Returns:: The patient ID.
Return type:: str

is_updated()[source]#

Check if is updated.

Returns:: True if is updated, False otherwise.
Return type:: bool

abstract update()[source]#

Update the SeriesInfo instance.

Return type:: None
Returns:: None

class FileSeriesInfo(path, subject_name)[source]#

Bases: SeriesInfo

An abstract base SeriesInfo class for all discrete image files (e.g. NIFTI, NRRD, MHA, etc.).

Important

For DICOM files use a DicomSeriesInfo subclass instead.

Parameters:

path (str) – The path to the discrete image file to load.
subject_name (str) – The name of the subject.

abstract update()[source]#

Update the FileSeriesInfo instance.

Return type:: None
Returns:: None

get_path()#

Get the file paths assigned to the SeriesInfo instance.

Returns:: The file paths assigned to the SeriesInfo instance.
Return type:: Tuple[str]

get_patient_id()#

Get the patient ID.

Returns:: The patient ID.
Return type:: str

get_patient_name()#

Get the patient name.

Returns:: The patient name.
Return type:: str

is_updated()#

Check if is updated.

Returns:: True if is updated, False otherwise.
Return type:: bool

class IntensityFileSeriesInfo(path, subject_name, modality)[source]#

Bases: FileSeriesInfo

A FileSeriesInfo class for intensity images. In addition to the information provided by the FileSeriesInfo class, this class contains also a Modality instance.

Parameters:

path (str) – The path to the discrete intensity image file to load.
subject_name (str) – The name of the subject.
modality (Union[str, Modality]) – The modality of the intensity image.

get_modality()[source]#

Get the Modality.

Returns:: The Modality.
Return type:: Modality

set_modality(modality)[source]#

Set the Modality.

Parameters:: modality (Modality) – The Modality to be set.
Return type:: None
Returns:: None

update()[source]#

Update the IntensityFileSeriesInfo.

Return type:: None
Returns:: None

get_path()#

Get the file paths assigned to the SeriesInfo instance.

Returns:: The file paths assigned to the SeriesInfo instance.
Return type:: Tuple[str]

get_patient_id()#

Get the patient ID.

Returns:: The patient ID.
Return type:: str

get_patient_name()#

Get the patient name.

Returns:: The patient name.
Return type:: str

is_updated()#

Check if is updated.

Returns:: True if is updated, False otherwise.
Return type:: bool

class SegmentationFileSeriesInfo(path, subject_name, organ, annotator)[source]#

Bases: FileSeriesInfo

A FileSeriesInfo class for segmentation images. In addition to the information provided by the FileSeriesInfo class, this class contains also an Organ instance and a Annotator instance.

Note

We assume that the segmentation image is a binary image with the foreground having the value 1 and the background being 0. If your images are different we recommend to separate the segmentation masks into separate files because in RT practice segmentations may overlap.

Parameters:

path (str) – The path to the discrete segmentation image file to load.
subject_name (str) – The name of the subject.
organ (Union[Organ, str]) – The organ the segmentation is representing.
annotator (Union[Annotator, str]) – The annotator who created the segmentation.

get_organ()[source]#

Get the Organ.

Returns:: The Organ.
Return type:: Organ

set_organ(organ)[source]#

Set the Organ.

Parameters:: organ (Organ) – The Organ to be set.
Return type:: None
Returns:: None

get_annotator()[source]#

Get the Annotator.

Returns:: The Annotator.
Return type:: Annotator

set_annotator(annotator)[source]#

Set the Annotator.

Parameters:: annotator (Annotator) – The Annotator to be set.
Return type:: None
Returns:: None

update()[source]#

Update the SegmentationFileSeriesInfo instance.

Return type:: None
Returns:: None

get_path()#

Get the file paths assigned to the SeriesInfo instance.

Returns:: The file paths assigned to the SeriesInfo instance.
Return type:: Tuple[str]

get_patient_id()#

Get the patient ID.

Returns:: The patient ID.
Return type:: str

get_patient_name()#

Get the patient name.

Returns:: The patient name.
Return type:: str

is_updated()#

Check if is updated.

Returns:: True if is updated, False otherwise.
Return type:: bool

class DicomSeriesInfo(path)[source]#

Bases: SeriesInfo

An abstract base SeriesInfo class for all DICOM data (i.e. DICOM image, DICOM registration, DICOM-RTSS).

Important

For discrete image files use a FileSeriesInfo subclass instead.

Parameters:: path (Union[str, Tuple[str, ...]]) – The path or paths specifying DICOM files to load.

abstract update()[source]#

Update the DicomSeriesInfo instance.

Return type:: None
Returns:: None

get_path()#

Get the file paths assigned to the SeriesInfo instance.

Returns:: The file paths assigned to the SeriesInfo instance.
Return type:: Tuple[str]

get_patient_id()#

Get the patient ID.

Returns:: The patient ID.
Return type:: str

get_patient_name()#

Get the patient name.

Returns:: The patient name.
Return type:: str

is_updated()#

Check if is updated.

Returns:: True if is updated, False otherwise.
Return type:: bool

class DicomSeriesImageInfo(paths)[source]#

Bases: DicomSeriesInfo

A DicomSeriesInfo class for DICOM images. In addition to the information provided by the DicomSeriesInfo class, this class contains also a Modality instance.

Parameters:: paths (Tuple[str, ...]) – The paths to the DICOM image files to load.

get_modality()[source]#

Get the Modality property.

Returns:: The Modality property.
Return type:: Modality

set_modality(modality)[source]#

Set the Modality.

Parameters:: modality (Modality) – The Modality to be assigned.
Return type:: None
Returns:: None

update()[source]#

Update the DicomSeriesImageInfo instance.

Return type:: None
Returns:: None

get_path()#

Get the file paths assigned to the SeriesInfo instance.

Returns:: The file paths assigned to the SeriesInfo instance.
Return type:: Tuple[str]

get_patient_id()#

Get the patient ID.

Returns:: The patient ID.
Return type:: str

get_patient_name()#

Get the patient name.

Returns:: The patient name.
Return type:: str

is_updated()#

Check if is updated.

Returns:: True if is updated, False otherwise.
Return type:: bool

class DicomSeriesRegistrationInfo(path, image_infos, persistent_image_infos=False)[source]#

Bases: DicomSeriesInfo

A DicomSeriesInfo class for DICOM registrations. In addition to the information provided by the DicomSeriesInfo class, this class contains transformation parameters and references to the pair of DICOM images associated with the registration.

Parameters:

path (str) – The path to the DICOM registration file to load.
image_infos (Tuple[DicomSeriesImageInfo, ...]) – The DicomSeriesImageInfo used.
persistent_image_infos (bool) – If True the class holds to the image_infos after updating, otherwise not (default: False).

static get_referenced_series_info(registration_dataset)[source]#

Get the ReferenceInfo entries from a dataset.

Parameters:: registration_dataset (Dataset) – The registration dataset to extract the infos from.
Returns:: The ReferenceInfo retrieved from the Dataset.
Return type:: Tuple[ReferenceInfo, …]

static get_registration_infos(registration_dataset, image_infos)[source]#

Extract the RegistrationInfo entries with the corresponding ReferenceInfo.

Parameters:

registration_dataset (Dataset) – The registration dataset to extract the registration infos from.
image_infos (Union[Tuple[DicomSeriesImageInfo, ...], Tuple[Dataset, ...]]) – The image infos or datasets to use for the combination.

Returns:

The combined RegistrationInfo.

Return type:

Tuple[RegistrationInfo, …]

set_image_infos(image_infos)[source]#

Set the DicomSeriesImageInfo entries.

Parameters:: image_infos (Tuple[DicomSeriesImageInfo, ...]) – The DicomSeriesImageInfo entries to set.
Return type:: None
Returns:: None

get_image_infos()[source]#

Get the DicomSeriesImageInfo entries.

Returns:: The DicomSeriesImageInfo entries.
Return type:: Tuple[DicomSeriesImageInfo, …]

update()[source]#

Update the DicomSeriesRegistrationInfo.

Return type:: None
Returns:: None

get_path()#

Get the file paths assigned to the SeriesInfo instance.

Returns:: The file paths assigned to the SeriesInfo instance.
Return type:: Tuple[str]

get_patient_id()#

Get the patient ID.

Returns:: The patient ID.
Return type:: str

get_patient_name()#

Get the patient name.

Returns:: The patient name.
Return type:: str

is_updated()#

Check if is updated.

Returns:: True if is updated, False otherwise.
Return type:: bool

class DicomSeriesRTSSInfo(path)[source]#

Bases: DicomSeriesInfo

A DicomSeriesInfo class for DICOM-RTSS. In addition to the information provided by the DicomSeriesInfo class, this class contains a Annotator instance and a reference to the DICOM image associated with the DICOM-RTSS.

Parameters:: path (str) – The path to the DICOM-RTSS file to load.

get_annotator()[source]#

Get the Annotator.

Returns:: The annotator.
Return type:: Annotator

get_path()#

Get the file paths assigned to the SeriesInfo instance.

Returns:: The file paths assigned to the SeriesInfo instance.
Return type:: Tuple[str]

get_patient_id()#

Get the patient ID.

Returns:: The patient ID.
Return type:: str

get_patient_name()#

Get the patient name.

Returns:: The patient name.
Return type:: str

is_updated()#

Check if is updated.

Returns:: True if is updated, False otherwise.
Return type:: bool

update()[source]#

Update the DicomSeriesRTSSInfo.

Return type:: None
Returns:: None

class ReferenceInfo(series_instance_uid, study_instance_uid, is_same_study)[source]#

Bases: object

A class storing one of multiple reference infos from a DICOM registration file.

Warning

This class is intended for internal use only.

Parameters:

series_instance_uid (str) – The SeriesInstanceUID.
study_instance_uid (str) – The StudyInstanceUID.
is_same_study (bool) – Indicates if the series is from the same study as the reference.

class RegistrationInfo(registration_info, reference_info, is_reference_image)[source]#

Bases: object

A class storing all necessary infos for applying a registration transformation to a DICOM image.

Warning

This class is intended for internal use only.

Parameters:

registration_info (RegistrationSequenceInfo) – The registration sequence info.
reference_info (ReferenceInfo) – The reference info.
is_reference_image (bool) – Indicates if the image is the reference image.

class RegistrationSequenceInfo(frame_of_reference_uid, transforms, transform_parameters)[source]#

Bases: object

A class storing one of multiple registration sequence infos from a DICOM registration file.

Warning

This class is intended for internal use only.

Parameters:

frame_of_reference_uid (str) – The FrameOfReferenceUID.
transforms (Tuple[sitk.AffineTransform, ...]) – The transforms.
transform_parameters (Tuple[List, ...]) – The transformation parameters.