Modality Configuration Module#

Module: pyradise.fileio.modality_config

General#

One drawback of the DICOM standard is that it does only provide the imaging modality in a minimal way (i.e. MR, CT, etc.) and little extra information about the acquisition parameters. If working with multiple images from the same modality, this information may not sufficient to distinguish between the different images. Therefore, the modality_config module provides functionality to build a persistent mapping between the DICOM images and their modality. This mapping is stored in a JSON file and may need to be modified manually. If there are not multiple images of the same DICOM modality, the modality configuration file is not required and can be omitted.

This mechanism of identifying the different images is especially useful when working recurrently with the same DICOM data or if the DICOM attributes are guaranteed to be named consistently. If the DICOM attributes are not guaranteed to be named consistently, the user may want to use the ModalityExtractor mechanism to extract the modality information directly from the DICOM data based on user defined rules or by accessing a different data source which provides the necessary modality information. The extractor approach is more flexible but requires the user to implement a custom set of rules to extract the modality information. The modality configuration approach is more convenient but requires the user to manually modify the configuration files if there is more than one DICOM image of the same DICOM modality.

If using the modality configuration approach, the modality configuration file skeleton filled with the DICOM modalities can be generated automatically using the appropriate DICOM Crawler. The generated modality configuration files are stored in the same directory as the DICOM files. After modifying the generated modality configuration files manually or via an appropriate script, the data can be loaded using the appropriate Loader.

Class Overview#

The following class is provided by the modality_config module:

Class	Description
`ModalityConfiguration`	Class handling all information to identify a modality and its details.

Details#

class ModalityConfiguration[source]#

Bases: object

A class representation the mapping between the Modality and multiple DICOM images from one subject.

The modality configuration us used for the identification of the detailed modalities belonging to multiple DICOM images from one subject. Typically, the modality configuration is stored in the subjects directory as a JSON file which can be modified manually. The ModalityConfiguration class provides methods to load and write the modality configuration file. In addition, it provides functionality to retrieve the modality information from a DicomSeriesInfo entries and to add the modality information to DicomSeriesInfo entries.

Typically, the ModalityConfiguration class is used as part of a Crawler which generates the modality configuration skeleton from a series of DICOM series. The modality configuration skeleton can then be stored on disk and manually modified. After modification, the modality configuration can be loaded and used to retrieve the modality information from a series of DICOM series.

Examples

Generate the modality configuration skeleton from a series of DICOM series:

>>> from pyradise.fileio import DatasetDicomCrawler
>>>
>>> def generate_skeleton(dataset_path: str) -> None:
>>>     # Generate the modality configuration file skeleton by setting
>>>     # write_modality_config = True
>>>     crawler = DatasetDicomCrawler(dataset_path, write_modality_config=True)
>>>     crawler.execute()
>>>
>>>
>>> if __name__ == '__main__':
>>>     generate_skeleton('path/to/dataset')

Example of modality configuration file skeleton (named: modality_config.json):

>>> [
>>>    {
>>>        "SOPClassUID": "1.2.840.10008.5.1.4.1.1.4",
>>>        "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.1556635153761.6.0",
>>>        "SeriesInstanceUID": "1.3.6.1.4.1.5962.99.1.1556635153761.239.0",
>>>        "SeriesDescription": "t1_mpr_sag_we_p2_iso",
>>>        "SeriesNumber": "7",
>>>        "DICOM_Modality": "MR",
>>>        "Modality": "MR"
>>>   },
>>>   {
>>>        "SOPClassUID": "1.2.840.10008.5.1.4.1.1.2",
>>>        "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.1557406273346.1015.0",
>>>        "SeriesInstanceUID": "1.3.6.1.4.1.5962.99.1.1557406273346.1016.0",
>>>        "SeriesDescription": "t2_fl_sag_p2_iso",
>>>        "SeriesNumber": "2",
>>>        "DICOM_Modality": "MR",
>>>        "Modality": "MR"
>>>    }
>>> ]

Example of modality configuration file (named: modality_config.json) content with filled “Modality” field:

>>> [
>>>    {
>>>        "SOPClassUID": "1.2.840.10008.5.1.4.1.1.4",
>>>        "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.1556635153761.6.0",
>>>        "SeriesInstanceUID": "1.3.6.1.4.1.5962.99.1.1556635153761.239.0",
>>>        "SeriesDescription": "t1_mpr_sag_we_p2_iso",
>>>        "SeriesNumber": "7",
>>>        "DICOM_Modality": "MR",
>>>        "Modality": "T1c"
>>>   },
>>>   {
>>>        "SOPClassUID": "1.2.840.10008.5.1.4.1.1.2",
>>>        "StudyInstanceUID": "1.3.6.1.4.1.5962.99.1.1557406273346.1015.0",
>>>        "SeriesInstanceUID": "1.3.6.1.4.1.5962.99.1.1557406273346.1016.0",
>>>        "SeriesDescription": "t2_fl_sag_p2_iso",
>>>        "SeriesNumber": "2",
>>>        "DICOM_Modality": "MR",
>>>        "Modality": "FLAIR"
>>>    }
>>> ]

Load the data with modalities assigned according to the generated and modified modality configuration file:

>>> from pyradise.fileio import DatasetDicomCrawler, SubjectLoader
>>>
>>> def load_data(dataset_path: str) -> None:
>>>     # Create a crawler with write_modality_config = False to avoid
>>>     # overwriting the existing file
>>>     crawler = DatasetDicomCrawler(dataset_path,
>>>                                   write_modality_config=False)
>>>
>>>     # Load the data with modalities assigned according to the modality
>>>     # configuration file
>>>     for subject_info in crawler:
>>>         subject = SubjectLoader().load(subject_info)
>>>         # Do something with the subject
>>>         print(subject.get_name())
>>>
>>>
>>> if __name__ == '__main__':
>>>     load_data('path/to/dataset')

classmethod from_file(path)[source]#

Class method to load a modality configuration from file.

Parameters:: path (str) – The path to the modality configuration file.
Returns:: The loaded modality configuration.
Return type:: ModalityConfiguration

classmethod from_dicom_series_info(dicom_infos)[source]#

Class method to generate a ModalityConfiguration from a list of DicomSeriesInfo entries.

Parameters:: dicom_infos (Tuple[DicomSeriesInfo, ...]) – The info entries from which the modality information will be retrieved.
Returns:: The generated modality configuration.
Return type:: ModalityConfiguration

to_file(path, override=False)[source]#

Write the current modality configuration to a modality configuration file.

Parameters:

path (str) – The file path for the modality file.
override (bool) – Indicates if an existing modality file should be overwritten.

Return type:

None

Returns:

None

add_modality_to_info(info)[source]#

Add the modality information from the modality configuration to a DicomSeriesImageInfo entry, if the information is available.

Parameters:: info (DicomSeriesImageInfo) – The DicomSeriesImageInfo to which the modality should be added.
Return type:: None
Returns:: None

add_modalities_to_info(infos)[source]#

Add the modality information from the modality configuration to the provided DicomSeriesImageInfos if available.

Parameters:: infos (Tuple[DicomSeriesImageInfo]) – The DicomSeriesImageInfos to which the modalities should be added.
Return type:: None
Returns:: None

add_modality_entry(sop_class_uid, study_instance_uid, series_instance_uid, series_description, series_number, dicom_modality, modality)[source]#

Add a modality configuration entry to the current modality configuration.

Parameters:

sop_class_uid (str) – The SOP Class UID of the DICOM image series.
study_instance_uid (str) – The Study Instance UID of the DICOM image series.
series_instance_uid (str) – The Series Instance UID of the DICOM image series.
series_description (str) – The Series Description of the DICOM image series.
series_number (str) – The Series Number of the DICOM image series.
dicom_modality (str) – The DICOM Modality of the DICOM image series that is retrieved from the DICOM file.
modality (Union[Modality, str]) – The user-defined modality of the DICOM image series.

Return type:

None

Returns:

None

has_default_modalities()[source]#

Indicate if the modality configuration contains default modalities.

Returns:: True if the modality configuration contains default modalities, otherwise False.
Return type:: bool

has_duplicate_modalities()[source]#

Indicate if the modality configuration contains duplicate Modality entries.

Returns:: True if the modality configuration contains duplicate modality entries, otherwise False.
Return type:: bool