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: typing.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.

DICTIONARY_APPENDICES = {'Magnetic Resonance': ['phase_encoding_direction']}

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_DIRECTION: Dict[str, str] = {'COL': 'j', 'ROW': 'i'}: Dictionary used to convert in-plane phase encoding direction to the NIfTI appropriate equivalent.

PHASE_ENCODING_SIGN: Dict[int, str] = {0: '', 1: '-'}

SEQUENCE_IDENTIFIERS = {'Magnetic Resonance': ['ScanningSequence', 'SequenceVariant', 'SeriesDescription', 'ImageType', 'ScanOptions', 'phase_encoding_direction']}: Header fields to pass to SequenceDetector. # noqa: E501

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

property detected_sequence: str

estimate_acquisition_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(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.

See also

n_diffusion_directions()

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_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

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.

See also

get_n_diffusion_directions()

Returns: Number of diffusion directions
Return type: int

property phase_encoding_direction: str

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

get_affine()

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

b_vector()

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.

See also

get_default_relative_path()

Returns: Default relative path for this image
Return type: Path

fix_data() → numpy.ndarray

Applies any required transformation to the data.

See also

Returns: Fixed pixel array data
Return type: np.ndarray

get_affine() → numpy.array

Returns the affine transformation of this image.

See also

affine()

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

b_vector()

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.

See also

default_relative_path()

Returns: Default relative path for this image
Return type: Path

get_image_orientation_patient() → numpy.array

Returns the image position and orientation.

References

https://dicom.innolitics.com/ciods/mr-image/image-plane/00200037

See also

image_orientation_patient()

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

image_position()

Returns: First voxel position
Return type: np.ndarray

get_image_shape() → Tuple[int, int]

Returns the image shape based on header metadata.

See also

image_shape()

Returns: Rows, columns
Return type: Tuple[int, int]

get_q_vector() → numpy.ndarray

Calculates Siemens DWI q-vector in voxel space.

See also

Returns: q-vector
Return type: np.ndarray

get_rotation_matrix() → numpy.array

Returns the rotation matrix between array indices and mm.

References

https://nipy.org/nibabel/dicom/dicom_orientation.html

Returns: Rotation matrix
Return type: np.array
Raises: PrecisionError – Unorthogonal rotation matrix

get_slice_normal() → numpy.array

Returns the slice normal.

See also

slice_normal()

Returns: Slice normal
Return type: np.array

get_spatial_resolution() → Tuple[float]

Returns the spatial resolution of the image in millimeters.

See also

spatial_resolution()

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

See also

voxel_space_b_matrix()

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

See also

voxel_space_b_value()

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.

See also

get_image_orientation_patient()

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.

See also

get_image_position()

Returns: First voxel position
Return type: np.ndarray

property image_shape: Tuple[int, int]

Returns the image shape based on header metadata.

See also

get_image_shape()

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.

See also

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.

See also

get_rotation_matrix()

Returns: Rotation matrix
Return type: np.array

property slice_normal: numpy.array

Returns the slice normal.

See also

get_slice_normal()

Returns: Slice normal
Return type: np.array

property spatial_resolution: Tuple[float]

Returns the spatial resolution of the image in millimeters.

See also

get_spatial_resolution()

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

See also

voxel_space_b_matrix()

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

See also

get_voxel_space_b_value()

Returns: Adjusted B value
Return type: float

dicom_parser.series module

Definition of the Series class.

class dicom_parser.series.Series(path: Optional[pathlib.Path] = None, images: Optional[Iterable[dicom_parser.image.Image]] = None, extension: Optional[Iterable[str]] = ('.dcm', '.ima'), 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_images(mime: bool = False, extension: Optional[Iterable[str]] = ('.dcm', '.ima')) → 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
extension (Iterable[str], optional) – Extensions to filter files in parent directory by

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