Reference

Module contents

dicom_parser facilitates access to DICOM header information using the subpackages and submodules documented below.

Subpackages

Submodules

dicom_parser.data_element module

Definition of the DataElement class.

class dicom_parser.data_element.DataElement(raw: pydicom.dataelem.DataElement)

Bases: object

A wrapper around pydicom’s DataElement class. This is a parent class for the data elements defined in data_elements.

PRIVATE_ELEMENT_DESCRIPTION_PATTERN: str = '\\[(.*)\\]|Private Creator'
VALUE_REPRESENTATION: dicom_parser.utils.value_representation.ValueRepresentation = None
get_private_element_keyword() str

Returns the keyword of private data elements if it can be extracted.

Returns

Private data element keyword

Return type

str

property is_private: bool

Checks whether this data element is private or not.

Returns

Whether this data element is private or not

Return type

bool

property is_public: bool

Checks whether this data element is public or not.

Returns

Whether this data element is public or not

Return type

bool

parse_keyword() str

Returns the keyword for this instance.

Returns

This instance’s keyword

Return type

str

parse_value(value: Any) Any

Default parse_value() method that simply decodes the raw value if it’s in bytes. This method is meant to be overridden by subclasses.

Parameters

value (Any) – This instance’s raw value

Returns

This instance’s parsed value

Return type

Any

parse_values() Any

Return the parsed value or values of this instance.

Returns

This instance’s parsed value or values

Return type

Any

to_dict() dict

Create a dictionary representation of this instance.

Returns

This instance as a dictionary

Return type

dict

to_series(**kwargs)
property value: Any

Caches the parsed value or values of this instance.

Returns

This instance’s parsed value or values

Return type

Any

dicom_parser.header module

Definition of the Header class.

class dicom_parser.header.Header(raw: Union[pydicom.dataset.FileDataset, str, pathlib.Path], sequence_detector=<class 'dicom_parser.utils.sequence_detector.sequence_detector.SequenceDetector'>, bids_detector=<class 'dicom_parser.utils.bids.bids_detector.BidsDetector'>)

Bases: object

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

DATAFRAME_COLUMNS: Iterable[str] = ('Tag', 'Keyword', 'VR', 'VM', 'Value')

Column names to use when converting to dataframe.

DATAFRAME_INDEX: str = 'Tag'

Name of column to be used as an index when converting to dataframe.

IOP_TO_PLANE: Dict[Tuple[int], dicom_parser.utils.plane.Plane] = {(0, 1, 0, 0, 0, -1): Plane.SAGITTAL, (1, 0, 0, 0, 0, -1): Plane.CORONAL, (1, 0, 0, 0, 1, 0): Plane.AXIAL}

Infer image plane from the rounded ImageOrientationPatient value. Based on https://stackoverflow.com/a/56670334/4416932

PHASE_ENCODING: Dict[dicom_parser.utils.plane.Plane, Dict[str, str]] = {Plane.AXIAL: {'i': 'LR', 'i-': 'RL', 'j': 'PA', 'j-': 'AP'}}
PHASE_ENCODING_DIRECTION: Dict[str, str] = {'COL': 'i', 'ROW': 'j'}

Dictionary used to convert in-plane phase encoding direction to the NIfTI appropriate equivalent.

PHASE_ENCODING_SIGN: Dict[int, str] = {0: '-', 1: ''}
property as_dict: dict

Returns a dictionary representation of this instance.

Returns

Header information

Return type

dict

property b_value: float

Returns the B value of Siemens scans.

See also

get_b_value()

Returns

B value

Return type

float

build_bids_path() str

Returns the derived BIDS path for this series.

Returns

Imaging sequence name

Return type

str

property data_elements: generator

Generates non-pixel array data elements from the header.

Yields

GeneratorType – Header information data elements

detect_sequence(verbose: bool = False) str

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

Parameters

verbose (bool) – Whether to show evaluation logs

Returns

Imaging sequence name

Return type

str

get(tag_or_keyword, default=None, parsed: bool = True, missing_ok: bool = True, as_json: bool = False) Any

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

  • default (Any, optional) – Default value to be returned if the key doesn’t exist, default is None

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

  • missing_ok (bool, optional) – Whether to treat missing key as None (otherwise, raises an exception), default is True

  • as_json (bool, optional) – Whether to return a JSON encoded string of the value, default is False

Returns

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

Return type

Any

get_b_value() float

Returns the B value of Siemens DWI scans.

See also

b_value()

Returns

B value

Return type

float

get_data_element(tag_or_keyword: Union[str, tuple, pydicom.dataelem.DataElement]) dicom_parser.data_element.DataElement

Returns a DataElement subclass instance matching the requested tag or keyword.

Parameters

tag_or_keyword (Union[str, tuple, PydicomDataElement]) – Tag or keyword representing the requested data element

Returns

Header data element

Return type

DataElement

Raises

TypeError – Invalid data element identifier

get_data_elements(value_representation=None, exclude=None, private: Optional[bool] = None) List[dicom_parser.data_element.DataElement]

Returns a list of data elements included in this header.

Parameters
  • value_representation (Union[str, tuple, list], optional) – Tag, keyword, value representation, or iterable of such, by default None

  • exclude (Union[str, tuple, list], optional) – Tag, keyword, value representation, or iterable of such, by default None

  • private (bool, optional) – If set to True or False, only public or private tags will be displayed accordingly, by default None

Returns

Data elements contained in this header

Return type

List[DataElement]

get_n_diffusion_directions() int

Returns the number of diffusion directions for DWI scans.

Returns

Number of diffusion directions

Return type

int

get_parsed_value(tag_or_keyword) Any

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

Any

get_phase_encoding_direction() str

Returns NIfTI-style phase encoding direction information (i/j[-]).

Returns

Phase encoding direction

Return type

str

get_plane() dicom_parser.utils.plane.Plane

Returns the image plane (see dicom_parser.utils.plane.Plane) based on the header’s ‘ImageOrientationPatient’ (0x20, 0x37) tag.

Returns

Acquisition plane

Return type

Plane

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: Union[str, tuple]) 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 (Union[str, tuple]) – 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 instance) 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 instance) 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

infer_phase_encoding() str

Returns the applied phase encoding as defined in the AP/PA or LR/RL format, based on the acquisition plane and phase encoding direction.

Returns

Phase encoding as AP/PA/LR/RL

Return type

str

property keys: List[str]

Returns a list of header keywords included in this instance.

Returns

Header keywords

Return type

List[str]

keyword_contains(query: str, exact: bool = False) List[dicom_parser.data_element.DataElement]

Returns a list of data elements in which the keyword contains the specified provided string.

Parameters
  • query (str) – String to look for in the data elements’ keyword

  • exact (bool, optional) – Whether to look for exact matches or use a case-insensitive query, default to False

Returns

Data elements containing the provided string in their keyword

Return type

List[DataElement]

property n_diffusion_directions: float

Returns the number of diffusion directions for DWI scans.

Returns

Number of diffusion directions

Return type

int

sequence_identifiers = {'Magnetic Resonance': ['ScanningSequence', 'SequenceVariant', 'SeriesDescription', 'ImageType', 'ScanOptions']}

Header fields to pass to SequenceDetector. # noqa: E501

to_dataframe(**kwargs)
to_dict(parsed: bool = True) dict

Returns a dictionary representation of this instance.

Parameters

parsed (bool, optional) – Whether to parse the returned value or not, by default True

Returns

Header information

Return type

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: Union[pydicom.dataset.FileDataset, str, pathlib.Path])

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 affine: numpy.array

Returns the affine transformation of this image.

See also

Returns

Affine transformation matrix

Return type

np.array

property b_matrix: numpy.ndarray

Returns the B matrix of Siemens scans.

Returns

B matrix

Return type

np.ndarray

property b_vector: numpy.ndarray

Returns the B vector of a Siemens DWI image.

See also

Returns

B vector

Return type

np.ndarray

property bids_path: str

Builds BIDS-appropriate path according to DICOM’s header :returns: BIDS-appropriate path :rtype: str

check_multi_frame() bool

Checks whether this image is a multi-frame image or not.

See also

  • func

    is_multi_frame

Returns

Whether this image is a multi-frame image or not

Return type

bool

property data: numpy.ndarray

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

Returns

Pixel data array

Return type

np.ndarray

property default_relative_path: pathlib.Path

Returns the default relative path for this image within a DICOM archive.

Returns

Default relative path for this image

Return type

Path

fix_data() numpy.ndarray

Applies any required transformation to the data.

Returns

Fixed pixel array data

Return type

np.ndarray

get_affine() numpy.array

Returns the affine transformation of this image.

See also

Returns

Affine transformation matrix

Return type

np.array

get_b_matrix() numpy.ndarray

Returns the B matrix of Siemens DWI scans.

Returns

B matrix

Return type

np.ndarray

get_b_vector() numpy.ndarray

Returns the B vector of a Siemens DWI image.

See also

Returns

B vector

Return type

np.ndarray

get_bids_path() str

Build BIDS-appropriate path for the series. :returns: BIDS-appropriate path :rtype: str

get_default_relative_path() pathlib.Path

Returns the default relative path for this image within a DICOM archive.

Returns

Default relative path for this image

Return type

Path

get_image_orientation_patient() numpy.array

Returns the image position and orientation.

References

Returns

Parsed image orientation (patient) attribute information

Return type

np.array

get_image_position() numpy.ndarray

Returns the position of the first voxel in the data block.

See also

Returns

First voxel position

Return type

np.ndarray

get_image_shape() Tuple[int, int]

Returns the image shape based on header metadata.

See also

Returns

Rows, columns

Return type

Tuple[int, int]

get_q_vector() numpy.ndarray

Calculates Siemens DWI q-vector in voxel space.

Returns

q-vector

Return type

np.ndarray

get_rotation_matrix() numpy.array

Returns the rotation matrix between array indices and mm.

References

Returns

Rotation matrix

Return type

np.array

Raises

PrecisionError – Unorthogonal rotation matrix

get_slice_normal() numpy.array

Returns the slice normal.

See also

Returns

Slice normal

Return type

np.array

get_spatial_resolution() Tuple[float]

Returns the spatial resolution of the image in millimeters.

Returns

Spatial resolution in millimeters

Return type

Tuple[float]

get_voxel_space_b_matrix() numpy.ndarray

Returns the B matrix in voxel space (rather than patient space).

Returns

Rotated B matrix

Return type

np.ndarray

get_voxel_space_b_value(tol: float = 1e-05) float

Returns the B value in voxel space (rather than patient space).

Parameters

tol (float, optional) – Norm tolerance, by default 1e-5

Returns

Adjusted B value

Return type

float

property image_orientation_patient: numpy.array

Returns the image position and orientation.

Returns

Parsed image orientation (patient) attribute information

Return type

np.array

property image_position: Tuple[float]

Returns the position of the first voxel in the data block.

Returns

First voxel position

Return type

np.ndarray

property image_shape: Tuple[int, int]

Returns the image shape based on header metadata.

Returns

Rows, columns

Return type

Tuple[int, int]

property is_fmri: bool

Returns True for fMRI images according to their header information.

Returns

Whether this image represents fMRI data

Return type

bool

property is_mosaic: bool

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

property is_multi_frame: bool

Checks whether this image is a multi-frame image or not.

See also

  • func

    check_multi_frame

Returns

Whether this image is a multi-frame image or not

Return type

bool

property mosaic: dicom_parser.utils.siemens.mosaic.Mosaic

Returns mosaic information.

Returns

Mosaic encoded image information

Return type

Mosaic

property multi_frame: dicom_parser.utils.multi_frame.multi_frame.MultiFrame

Returns multi-frame encoded data.

Returns

Multi-frame encoded image information

Return type

MultiFrame

property q_vector: numpy.ndarray

Calculates Siemens DWI q-vector in voxel space.

Returns

q-vector

Return type

np.ndarray

read_raw_data() numpy.ndarray

Reads the pixel array data as returned by pydicom.

Returns

Pixel array data

Return type

np.ndarray

rescale_data(data: numpy.array) numpy.array

Rescales the provided data pixel array using the Rescale Slope and Rescale Intercept header fields.

Parameters

data (np.array) – Pixel array

Returns

Fixed pixel array

Return type

np.array

property rotation_matrix: numpy.array

Returns the rotation matrix between array indices and mm.

Returns

Rotation matrix

Return type

np.array

property slice_normal: numpy.array

Returns the slice normal.

Returns

Slice normal

Return type

np.array

property spatial_resolution: Tuple[float]

Returns the spatial resolution of the image in millimeters.

Returns

Spatial resolution in millimeters

Return type

Tuple[float]

property voxel_space_b_matrix: numpy.ndarray

Returns the B matrix in voxel space (rather than patient space).

Returns

Rotated B matrix

Return type

np.ndarray

property voxel_space_b_value: float

Returns the B value in voxel space (rather than patient space).

Returns

Adjusted B value

Return type

float

dicom_parser.series module

Definition of the Series class.

class dicom_parser.series.Series(path: pathlib.Path, mime: bool = False)

Bases: object

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

property bids_path: str

Builds BIDS-appropriate path according to DICOM’s header :returns: BIDS-appropriate path :rtype: str

static 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: numpy.ndarray

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) Any

Returns header information from the Image instances 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

  • default (Any, optional) – Default value to be returned if the key doesn’t exist, default is None

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

  • missing_ok (bool, optional) – Whether to treat missing key as None (otherwise, raises an exception), default is True

Returns

The requested data element value for the entire series

Return type

Any

get_bids_path() str

Build BIDS-appropriate path for the series. :returns: BIDS-appropriate path :rtype: str

get_dcm_paths(mime: bool = False) Generator

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

Parameters

mime (bool, optional) – Whether to return files by mime type (instead of extension), by default False

Returns

DICOM images generator

Return type

GeneratorType

Raises

FileNotFoundError – No DICOM images found under provided directory

get_images(mime: bool = False) tuple

Returns a tuple of Image instances ordered by instance number.

Returns

  • tuple – Image instance by instance number

  • mime (bool, optional) – Whether to find DICOM images by file mime type instead of extension, defaults to False

get_spatial_resolution() Tuple[float]

Returns the spatial resolution of the series in millimeters.

Returns

Spatial resolution in millimeters

Return type

Tuple[float]

property spatial_resolution: tuple

Returns the spatial resolution of the series.

Returns

Spatial resolution

Return type

tuple