dicom_parser.utils.siemens.csa package — dicom_parser 0.0.1 documentation

# dicom_parser.utils.siemens.csa package

## Module contents

CSA headers are Siemens-specific private data elements that are embedded in some DICOM headers, specifically as the (0029, 1010)/”CSA Image Header Info” and (0029, 1020)/”CSA Series Header Info” tags. For more information see this NiBabel article.

## Submodules

## dicom_parser.utils.siemens.csa.data_element module

Definition of a single CSA header data element. These elements are parsed from the full string header using new line characters.

class `dicom_parser.utils.siemens.csa.data_element.` `CsaDataElement`(raw_element: str)

  Bases: `object`

  Represents a single CSA header data element as extracted from the raw header information.

  `CLEAN_PART_PATTERN` = '[A-Z].*'
  `LIST_PART_PATTERN` = '\\[\\d+\\]'
  `clean_part`(part: str) → str

    Returns a the part’s name without any prefixed lowercase characters.

    Parameters

      part (str) – One of the listed key’s parts

    Returns

      Prefix-omitted part name

    Return type

      str

  `key_to_list`(chained_key: str) → list

    The string data elements represents nested keys using a ‘.’ character. Returns a clean (prefix-omitted) list of the nested key structure.

    Parameters

      chained_key (str) – CSA header data element key

    Returns

      Clean and listed representation of the provided key

    Return type

      list

  `search_array_pattern`(part: str) → int

    Checks if the pattern indicating a particular key part represents an array.

    Parameters

      part (str) – Some part of a listed key

    Returns

      The value’s index if array pattern found, else None

    Return type

      int

  `split`() → tuple

    Splits the raw CSA element to a clean and listed key and a value.

    Returns

      key, value

    Return type

      tuple

## dicom_parser.utils.siemens.csa.header module

Definition of the `CsaHeader` class which handles the parsing of CSA header values returned by pydicom as bytes.

class `dicom_parser.utils.siemens.csa.header.` `CsaHeader`(header: bytes)

  Bases: `object`

  Represents a full CSA header data element, i.e. either (0029, 1010)/”CSA Image Header Info” or (0029, 1020)/”CSA Series Header Info”, and provides access to the header as a parsed dictionary. This implementation is heavily based on dicom2nifti’s code (particularly this module).

  `ELEMENT_PATTERN` = '([A-Z][^\\n]*)'
  `ENCODING` = 'ISO-8859-1'
  `HEADER_INFORMATION_PATTERN` = '### ASCCONV BEGIN(.*)### ASCCONV END ###'
  `create_csa_data_elements`(raw_elements: list = None) → list

    Creates `CsaDataElement` instances that parse the key and the value

    Parameters

      raw_elements (list) – Raw (string) CSA header elements

    Returns

      `CsaDataElement` instances.

    Return type

      list

  property `csa_data_elements`

    Caches the `CsaDataElement` instances representing the entire header information.

    Returns

      `CsaDataElement` instances

    Return type

      list

  `decode`() → str

    Decodes the raw (ASCII) information to string.

    Returns

      Decoded information

    Return type

      str

  `get_header_information`() → str

    Returns the decoded and extracted header information from the full data element’s value.

    Returns

      Decoded clean header information

    Return type

      str

  `get_raw_data_elements`() → list

    Splits the decoded header information into a list of raw (string) data elements, each containing a key-value pair. The first item is skipped because it is an unrequired heading.

    Returns

      CSA data elements in raw string format

    Return type

      list

  property `n_slices`

    Returns the number of slices (tiles) in a mosaic.

    Returns

      Number of slices encoded as a 2D mosaic.

    Return type

      int

  `parse`(csa_data_elements: list = None) → dict

    Parses a list of `CsaDataElement` instances (or all if left None) as a dictionary.

    Parameters

      csa_data_elements (list, optional) – `CsaDataElement` instances, by default None

    Returns

      Header information as a dictionary

    Return type

      dict

  property `parsed`

    Caches the parsed dictionary as a private attribute.

    Returns

      Header information as dictionary

    Return type

      dict

  property `raw_elements`

    Caches the raw (sting) CSA data elements as a private attribute.

    Returns

      Raw CSA header data elements

    Return type

      list

## dicom_parser.utils.siemens.csa.parser module

Definition of parser that accepts `CsaDataElement` instances to be parsed and keeps a pointer to a dictionary that may aggregate the results.

class `dicom_parser.utils.siemens.csa.parser.` `CsaParser`(destination: dict = None)

  Bases: `object`

  Parses CSA header data elements given as `CsaDataElement` instances into a public dictionary.

  `assign_list_element`(part: str, value, destination: dict)

    Appends to an existing list value or creates a new list instance for it.

    Parameters

      - part (str) – Last part’s name

      - value ([type]) – The `CsaDataElement`’s value

      - destination (dict) – A pointer to the appropriate destination with the parsed dictionary

  `assign_listed_element`(csa_data_element: dicom_parser.utils.siemens.csa.data_element.CsaDataElement, destination: dict)

    Once the destination for the `CsaDataElement`’s value has been retrieved or created, this method assigns the value at that destination.

    Parameters

      - csa_data_element (`CsaDataElement`) – The instance from which to assign the value

      - destination (dict) – The appropriate destination within the parsed values dictionary

  `create_new_element_list`(part_name: str, destination: dict) → dict

    If an array part (part containing the [<index>] pattern) exists as any part of the listed key except for the last, it indicates a list of dictionary instances. This method creates a new list with a single dict instances and returns a pointer to it.

    Parameters

      - part_name (str) – The key for the list in the current dict level of the constructed scaffolding.

      - destination (dict) – The current level of scaffolding within the parsed dictionary

    Returns

      The next level of the key’s scaffolding within the parsed dictionary

    Return type

      dict

  `fix_value`(value)

    Covert a CSA header element’s value to float or int if possible. Also cleans up redundant quotation marks and decodes hexadecimal values.

    Parameters

      value ([type]) – Some CSA header element value

    Returns

      Fixed (converted) value

    Return type

      str, int, or float

  `parse`(csa_data_element: dicom_parser.utils.siemens.csa.data_element.CsaDataElement)

    Parses a raw CSA header element into the provided dictionary or creates a new one.

    Parameters

      csa_data_element (`CsaDataElement`) – CSA header element to be parsed

  `scaffold_dict_part`(part: str, destination: dict) → dict

    Returns the destination of a given key’s dict part within the parsed dictionary.

    Parameters

      - part (str) – List part’s name

      - destination (dict) – The current level of scaffolding within the parsed dictionary

    Returns

      The next level of the key’s scaffolding within the parsed dictionary

    Return type

      dict

  `scaffold_list_part`(part: str, index: int, destination: dict) → dict

    Returns the destination of a given key’s list part within the parsed dictionary.

    Parameters

      - part (str) – List part’s name

      - index (int) – The index within the list for the next part in the nested key

      - destination (dict) – The current level of scaffolding within the parsed dictionary

    Returns

      The next level of the key’s scaffolding within the parsed dictionary

    Return type

      dict

  `scaffold_listed_key`(csa_data_element: dicom_parser.utils.siemens.csa.data_element.CsaDataElement, destination: dict = None) → dict

    Creates a scaffolding within the parsed values dictionary. This means that it runs over the data elements nested key structure (LevelA.ListLevelB[5].LevelC = ‘value’) and returns a pointer to the appropriate destination for the value within the parsed values dictionary.

    Parameters

      - csa_data_element (`CsaDataElement`) – Instance to scaffold a destination for

      - destination (dict, optional) – An existing destination dictionary, by default None

    Returns

      A pointer to the appropriate destination for the `CsaDataElement`’s value

    Return type

      dict

  `scaffold_part`(csa_data_element: dicom_parser.utils.siemens.csa.data_element.CsaDataElement, part: str, destination: dict) → dict

    Returns the destination of a given key’s part within the parsed dictionary.

    Parameters

      - csa_data_element (`CsaDataElement`) – The source instance

      - part (str) – List part’s name

      - destination (dict) – The current level of scaffolding within the parsed dictionary

    Returns

      The next level of the key’s scaffolding within the parsed dictionary

    Return type

      dict

  `update_existing_element_list`(part_name: str, index: int, destination: dict) → dict

    If an array part (part containing the [<index>] pattern) exists as any part of the listed key except for the last, it indicates a list of dictionary instances. This method check whether a dictionary exists already at the given list’s index. If it does, returns that dict instance, otherwise, creates a new one and returns it.

    Parameters

      - part_name (str) – The list’s key within the destination dictionary

      - index (int) – The index of the nested part

      - destination (dict) – The current level of scaffolding within the parsed dictionary

    Returns

      The next level of the key’s scaffolding within the parsed dictionary

    Return type

      dict