dicom_parser package — dicom_parser 0.0.1 documentation

# dicom_parser package

## Subpackages

- dicom_parser.utils package
  - Subpackages
    - dicom_parser.utils.code_strings package
      - Submodules
      - dicom_parser.utils.code_strings.modality module
      - dicom_parser.utils.code_strings.patient_position module
      - dicom_parser.utils.code_strings.scanning_sequence module
      - dicom_parser.utils.code_strings.sequence_variant module
      - dicom_parser.utils.code_strings.sex module
      - Module contents
    - dicom_parser.utils.sequence_detector package
      - Submodules
      - dicom_parser.utils.sequence_detector.exceptions module
      - dicom_parser.utils.sequence_detector.sequence_detector module
      - dicom_parser.utils.sequence_detector.sequences module
      - Module contents
    - dicom_parser.utils.siemens package
      - Module contents
      - Subpackages
        - dicom_parser.utils.siemens.csa package
          - Module contents
          - Submodules
          - dicom_parser.utils.siemens.csa.data_element module
          - dicom_parser.utils.siemens.csa.header module
          - dicom_parser.utils.siemens.csa.parser module
      - Submodules
      - dicom_parser.utils.siemens.private_tags module
  - Submodules
  - dicom_parser.utils.choice_enum module
  - dicom_parser.utils.peek module
  - dicom_parser.utils.read_file module
  - dicom_parser.utils.value_representation module
  - Module contents

## Submodules

## dicom_parser.header module

Definition of the Header class, which extends the functionality of pydicom.

class `dicom_parser.header.` `Header`(raw, parser=<class 'dicom_parser.parser.Parser'>, sequence_detector=<class 'dicom_parser.utils.sequence_detector.sequence_detector.SequenceDetector'>)

  Bases: `object`

  Facilitates access to DICOM header information from pydicom’s FileDataset.

  `detect_sequence`() → str

    Returns the detected imaging sequence using the modality’s sequence identifying header information.

    Returns

      Imaging sequence name

    Return type

      str

  `get`(tag_or_keyword, default=None, parsed: bool = True, missing_ok: bool = True)

    Returns the value of a pydicom data element, selected by tag (tuple) or keyword (str). Input may also be a list of such identifiers, in which case a dictionary will be returned with the identifiers as keys and header information as values.

    Parameters

      - tag_or_keyword (tuple or str, or list) – Tag or keyword representing the requested data element, or a list of such.

      - parsed (bool, optional) – Whether to return a parsed or raw value (the default is True, which will return the parsed value).

    Returns

      The requested data element value (or a dict for multiple values)

    Return type

      type

  `get_element`(tag_or_keyword) → pydicom.dataelem.DataElement

    Returns a pydicom DataElement from the associated FileDataset either by tag (passed as a tuple) or a keyword (passed as a string). If none found or the tag or keyword are invalid, returns None.

    Parameters

      tag_or_keyword (tuple or str) – Tag or keyword representing the requested data element

    Returns

      The requested data element

    Return type

      DataElement

  `get_element_by_keyword`(keyword: str) → pydicom.dataelem.DataElement

    Returns a pydicom DataElement from the header (FileDataset isntance) by keyword.

    Parameters

      keyword (str) – The keyword representing the DICOM data element in pydicom

    Returns

      The requested data element

    Return type

      DataElement

  `get_element_by_tag`(tag: tuple) → pydicom.dataelem.DataElement

    Returns a pydicom DataElement from the header (FileDataset isntance) by tag.

    Parameters

      tag (tuple) – The DICOM tag of the desired data element

    Returns

      The requested data element

    Return type

      DataElement

  `get_parsed_value`(tag_or_keyword)

    Returns the parsed value of pydicom data element using the this class’s parser attribute. The data element may be represented by tag or by its pydicom keyword. If none is found will return None.

    Parameters

      tag_or_keyword (tuple or str) – Tag or keyword representing the requested data element

    Returns

      Parsed data element value

    Return type

      type

  `get_private_tag`(keyword: str) → tuple

    Returns a vendor-specific private tag corresponding to the provided keyword, if the tag is registered (see the `private_tags` module). This is required because pydicom does not offer keyword access to private tags.

    Parameters

      keyword (str) – Private data element keyword

    Returns

      Private data element tag

    Return type

      tuple

  `get_raw_value`(tag_or_keyword)

    Returns the raw value for the requested data element, as returned by pydicom. If none is found will return None.

    Parameters

      tag_or_keyword (tuple or str) – Tag or keyword representing the requested data element.

    Returns

      The raw value of the data element

    Return type

      type

  `sequence_identifiers` = {'Magnetic Resonance': ['ScanningSequence', 'SequenceVariant']}

## dicom_parser.image module

Definition of the Image class, representing a single pair of `Header` and data (3D NumPy array).

class `dicom_parser.image.` `Image`(raw, parser=<class 'dicom_parser.parser.Parser'>)

  Bases: `object`

  This class represents a single DICOM image (i.e. .dcm file) and provides unified access to it’s header information and data.

  property `data`

    Returns the pixel data array after having applied any required transformations.

    Returns

      Pixel data array.

    Return type

      np.ndarray

  `fix_data`() → numpy.ndarray

    Applies any required transformation to the data.

    Returns

      Pixel array data

    Return type

      np.ndarray

  property `is_fmri`

    Returns True for fMRI images according to their header information.

    Returns

      Whether this image represents fMRI data.

    Return type

      bool

  property `is_mosaic`

    Checks whether a 3D volume is encoded as a 2D Mosaic. For more information, see the `Mosaic` class.

    Returns

      Whether the image is a mosaic encoded volume

    Return type

      bool

  `read_raw_data`() → numpy.ndarray

    Reads the pixel array data as returned by pydicom.

    Returns

      Pixel array data

    Return type

      np.ndarray

## dicom_parser.parser module

Definition of the `Parser` class, used to parse the raw `DataElement` values into “pythonic” types.

class `dicom_parser.parser.` `Parser`(verbose_code_strings: bool = True)

  Bases: `object`

  A default parser to be used by the `Header` class. This class can easily be replaced with custom parser classes, as long as they expose the expected `parse()` method.

  `CODE_STRINGS_DICT` = {'(0008, 0060)': <enum 'Modality'>, '(0010, 0040)': <enum 'Sex'>, '(0018, 0020)': <enum 'ScanningSequence'>, '(0018, 0021)': <enum 'SequenceVariant'>, '(0018, 5100)': <enum 'PatientPosition'>}
  `N_IN_YEAR` = {'D': 365.2422, 'M': 12, 'W': 52.1429, 'Y': 1}
  `PARSING_METHOD` = {<ValueRepresentation.AGE_STRING: 'AS'>: 'parse_age_string', <ValueRepresentation.DATE: 'DA'>: 'parse_date', <ValueRepresentation.TIME: 'TM'>: 'parse_time', <ValueRepresentation.DATE_TIME: 'DT'>: 'parse_datetime', <ValueRepresentation.INTEGER_STRING: 'IS'>: 'parse_integer_string', <ValueRepresentation.DECIMAL_STRING: 'DS'>: 'parse_decimal_string', <ValueRepresentation.UNKNOWN: 'UN'>: 'parse_unknown', <ValueRepresentation.CODE_STRING: 'CS'>: 'parse_code_string'}
  `SINGLE_VALUE_CODE_STRINGS` = ('(0010, 0040)', '(0018, 5100)', '(0008, 0060)')
  `call_parsing_method`(element: pydicom.dataelem.DataElement, value_representation: dicom_parser.utils.value_representation.ValueRepresentation)

    Calls the appropriate parsing method for the `DataElement` based on the provided `ValueRepresentation`.

    Parameters

      - element (`DataElement`) – DICOM data element

      - value_representation (`ValueRepresentation`) – Data element’s value representation

    Returns

      Parsed value

    Return type

      [type]

  `get_code_string_representation`(name: str, enum: enum.Enum) → str

    Returns a Code String (CS) data element value’s according to the class’s verbose_code_strings attribute value. If True, returns the corresponding Enum’s value. Otherwise, simply returns the name itself (raw value).

    Parameters

      - name (str) – Code String (CS) value

      - enum (enum.Enum) – Code String (CS) valid values

    Returns

      Parsed value in coded or verbose form

    Return type

      str

  `get_value_representation`(element: pydicom.dataelem.DataElement) → dicom_parser.utils.value_representation.ValueRepresentation

    Gets the given `DataElement`’s `ValueRepresentation`.

    Parameters

      element (`DataElement`) – DICOM data element

    Returns

      Corresponding data representation enum

    Return type

      `ValueRepresentation`

    Raises

      NotImplementedError – Unknown value represenation

  `parse`(element: pydicom.dataelem.DataElement)

    Tries to parse a pydicom DICOM data element using its value-representation (VR) attribute. If no parser method is registered for the VR under the PARSING_METHOD dictionary, will simply return the raw value.

    Parameters

      element (DataElement) – DICOM data element as represented by pydicom.

    Returns

      Parsed DICOM data element value.

    Return type

      type

  `parse_age_string`(element: pydicom.dataelem.DataElement) → float

    Parses Age String (AS) data elements into a float representation of the age in years.

    Parameters

      element (`DataElement`) – DICOM Age String (AS) data element.

    Returns

      The age in years.

    Return type

      float

  `parse_code_string`(element: pydicom.dataelem.DataElement)

    Parses Code String (CS) data elements to a more readable string or set of strings. This method relies on an Enum representation of the data element’s possible values to be registered in the Parser’s CODE_STRINGS_DICT by tag. If no Enum is registered, will return try to parse out a value or a set of values.

    Parameters

      element (`DataElement`) – DICOM Code String (CS) data element.

    Returns

      Parsed value/s.

    Return type

      str or set

  `parse_code_string_with_enum`(element: pydicom.dataelem.DataElement, enum: enum.Enum)

    Parses a Code String (CS) data element using

    Parameters

      - element (`DataElement`) – Code String (CS) data element

      - enum (enum.Enum) – An Enum representing the element’s valid values

    Returns

      Parsed value/s.

    Return type

      str or set

  `parse_code_string_without_enum`(element: pydicom.dataelem.DataElement)

    Parses a Code String (CS) data element without an Enum representing its valid values. Strings representing arrays are parsed out as sets.

    Parameters

      element (`DataElement`) – DICOM Code String (CS) data element.

    Returns

      Parsed value/s.

    Return type

      str or set

  `parse_date`(element: pydicom.dataelem.DataElement) → None.datetime.date

    Parses Date (DA) data elements to date objects.

    Parameters

      element (`DataElement`) – DICOM Date (DA) data element.

    Returns

      Native python date object.

    Return type

      datetime.date

  `parse_decimal_string`(element: pydicom.dataelem.DataElement)

    Parses Decimal String (DS) data elements to floats. In case the Value Multiplicity (VM) is greater than one, returns a list of floats.

    Parameters

      element (`DataElement`) – DICOM Decimal String (DS) data element.

    Returns

      Data element value/s.

    Return type

      float or list

  `parse_integer_string`(element: pydicom.dataelem.DataElement) → int

    Parses DICOM Integer String (IS) data elements to integers.

    Parameters

      element (`DataElement`) – DICOM Integer String (IS) data element.

    Returns

      Data element value.

    Return type

      int

  `parse_multiple_code_string_with_enum`(element: pydicom.dataelem.DataElement, enum: enum.Enum) → set

    Parses a `pydicom.multival.MultiValue` data element value to set of valid representations.

    Parameters

      - element (`DataElement`) – Code String (CS) data element

      - enum (enum.Enum) – An Enum representing the element’s valid values

    Returns

      Parsed values

    Return type

      set

  `parse_siemens_gradient_direction`(value: bytes) → list

    Parses a SIEMENS MR image’s B-vector as represented in the private (0019, 100E) DiffusionGradientDirection DICOM tag.

    Parameters

      value (bytes) – SIEMENS private DiffusionGradientDirection data element.

    Returns

      Gradient directions (B-vector).

    Return type

      list

  `parse_siemens_slice_timing`(value: bytes) → list

    Parses a SIEMENS MR image’s slice timing as saved in the private (0019, 1029) MosaicRefAcqTimes tag to a list of floats representing slice times in milliseconds.

    Parameters

      value (bytes) – SIEMENS private MosaicRefAcqTimes data element.

    Returns

      Slice times in milliseconds.

    Return type

      list

  `parse_single_code_string_with_enum`(element: pydicom.dataelem.DataElement, enum: enum.Enum)

    Parses a Code String (CS) data element with a value-multiplicity (VM) of 1. The parsed value is returned as a `set` unless it the element is listed in the `SINGLE_VALUE_CODE_STRINGS` attribute, in which case it is returned as a `str`.

    Parameters

      - element (`DataElement`) – Code String (CS) data element

      - enum (enum.Enum) – An Enum representing the element’s valid values

    Returns

      Parsed value

    Return type

      str or set

  `parse_time`(element: pydicom.dataelem.DataElement) → None.datetime.time

    Parses Time (TM) data elements to time objects.

    Parameters

      element (`DataElement`) – DICOM Time (TM) data element.

    Returns

      Native python time object.

    Return type

      datetime.time

  `parse_unknown`(element: pydicom.dataelem.DataElement)

    Parses private tags and other Unknown (UN) data elememts.

    Parameters

      element (`DataElement`) – DICOM Unknown (UN) data element.

  `warn_invalid_code_string_value`(exception: KeyError, enum: enum.Enum) → None

    Displays a warning for invalid Code String (CS) values.

    Parameters

      - exception (KeyError) – The exception raised when trying to parse the invalid value

      - enum (enum.Enum) – An Enum representing the element’s valid values

## dicom_parser.series module

Definition of the Series class, representing a collection of Image instances ordered by the header’s InstanceNumber data element.

class `dicom_parser.series.` `Series`(path: pathlib.Path)

  Bases: `object`

  This class represents a complete collection of Image instances originating from a single directory and ordered by InstanceNumber.

  `check_path`(path) → pathlib.Path

    Converts to a `Path` instance if required and checks that it represents an existing directory.

    Parameters

      path (str or Path) – The provided path.

    Returns

      A pathlib.Path instance representing an existing directory.

    Return type

      Path

    Raises

      ValueError – If the provided path is not an existing directory.

  property `data`

    Caches the stacked 3D array containing the entire series’ data.

    Returns

      Series 3D data.

    Return type

      np.ndarray

  `get`(tag_or_keyword, default=None, parsed: bool = True, missing_ok: bool = True)

    Returns header information from the `Image` that compose this series. If one distinct value is returned from all the images’ headers, returns that value. Otherwise, returns a list of the values (ordered the same as the images attribute, by instance number).

    Parameters

      tag_or_keyword (tuple or str, or list) – Tag or keyword representing the requested data element, or a list of such.

    Returns

      The requested data element value for the entire series

    Return type

      type

  `get_dcm_paths`() → generator

    Returns a generator of .dcm files within the provided directory path.

    Returns

      DICOM images (.dcm files) generator.

    Return type

      GeneratorType

    Raises

      FileNotFoundError – No DICOM images found under provided directory.

  `get_images`() → tuple

    Returns a tuple of `Image` instances ordered by instance number.

    Returns

      Image instance by instance number.

    Return type

      tuple

## Module contents