dicom_parser package

Submodules

dicom_parser.header module

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

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

Bases: object

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

DATAFRAME_COLUMNS = ('Tag', 'Keyword', 'VR', 'VM', 'Value')
DATAFRAME_INDEX = 'Tag'
property as_dict
property data_elements
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, as_json: bool = False)

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_data_element(tag_or_keyword) → dicom_parser.data_element.DataElement
get_data_elements(value_representation=None, exclude=None, private: bool = None) → list
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_element(tag_or_keyword) → pydicom.dataelem.DataElement

Returns a pydicom PydicomDataElement 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

PydicomDataElement

get_raw_element_by_keyword(keyword: str) → pydicom.dataelem.DataElement

Returns a pydicom PydicomDataElement 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

PydicomDataElement

get_raw_element_by_tag(tag: tuple) → pydicom.dataelem.DataElement

Returns a pydicom PydicomDataElement 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

PydicomDataElement

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

property keys
sequence_identifiers = {'Magnetic Resonance': ['ScanningSequence', 'SequenceVariant']}
to_dataframe(data_elements: list = None, value_representation=None, exclude=None, private: bool = None) → pandas.core.frame.DataFrame
to_dict(parsed: bool = True) → dict

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)

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

property default_relative_path
fix_data() → numpy.ndarray

Applies any required transformation to the data.

Returns

Pixel array data

Return type

np.ndarray

get_default_relative_path() → pathlib.Path
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.AS: 'Age String'>: 'parse_age_string', <ValueRepresentation.CS: 'Code String'>: 'parse_code_string', <ValueRepresentation.DA: 'Date'>: 'parse_date', <ValueRepresentation.DS: 'Decimal String'>: 'parse_decimal_string', <ValueRepresentation.DT: 'Date Time'>: 'parse_datetime', <ValueRepresentation.IS: 'Integer String'>: 'parse_integer_string', <ValueRepresentation.OW: 'Other Word'>: 'parse_other_word', <ValueRepresentation.PN: 'Person Name'>: 'parse_person_name', <ValueRepresentation.SQ: 'Sequence of Items'>: 'parse_sequence_of_items', <ValueRepresentation.TM: 'Time'>: 'parse_time', <ValueRepresentation.UN: 'Unknown'>: 'parse_unknown'}
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
Returns

Parsed value

Return type

[type]

get_code_string_representation(value: 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
  • value (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

handle_unregistered_vr(value, **kwargs)
parse(element: pydicom.dataelem.DataElement, index: int = None, ignore_warnings: bool = False, return_warnings: bool = False)

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(value: str, **kwargs) → float

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

Parameters

value (str) – DICOM Age String (AS) data element value

Returns

Age in years

Return type

float

parse_code_string(value: str, tag: tuple, **kwargs)

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(value: str, enum: enum.Enum)

Parses a Code String (CS) data element using

Parameters
  • element (str) – Code String (CS) data element value

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

Returns

Parsed value/s.

Return type

str or set

parse_date(value: str, **kwargs) → None.datetime.date

Parses a Date (DA) data element value to date object.

Parameters

element (str) – DICOM Date (DA) data element value

Returns

Native python date object

Return type

datetime.date

parse_decimal_string(value: str, **kwargs)

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

Parameters

value (str) – DICOM Decimal String (DS) data element value

Returns

Decimal string value

Return type

float

parse_integer_string(value: str, **kwargs) → int

Parses DICOM Integer String (IS) data element value to integer.

Parameters

element (str) – DICOM Integer String (IS) data element value

Returns

Integer string value

Return type

int

parse_other_word(value: bytes, **kwargs) → list
parse_person_name(value: pydicom.valuerep.PersonName, **kwargs)
parse_sequence_of_items(value: pydicom.sequence.Sequence)
parse_siemens_gradient_direction(value: bytes, **kwargs) → 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, **kwargs) → 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_time(value: str, **kwargs) → None.datetime.time

Parses Time (TM) data elements to time objects.

Parameters

element (str) – DICOM Time (TM) data element value

Returns

Native python time object

Return type

datetime.time

parse_unknown(value, tag: tuple, **kwargs)

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

Parameters

value (type) – 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

get_spatial_resolution() → tuple
property spatial_resolution

Module contents