`nicom`¶

DICOM reader

`csareader`	CSA header reader from SPM spec
`dicomreaders`
`dicomwrappers`	Classes to wrap DICOM objects and files
`dwiparams`	Process diffusion imaging parameters
`structreader`	Stream-like reader for packed data

Module: `nicom.ascconv`¶

Parse the “ASCCONV” meta data format found in a variety of Siemens MR files.

`AscconvParseError`	Error parsing ascconv file
`Atom`(op, obj_type, obj_id)	Object to hold operation, object type and object identifier
`NoValue`()	Signals no value present
`assign2atoms`(assign_ast[, default_class])	Parse single assignment ast from ascconv line into atoms
`obj_from_atoms`(atoms, namespace)	Return object defined by list atoms in dict-like namespace
`parse_ascconv`(ascconv_str[, str_delim])	Parse the 'ASCCONV' format from input_str.

Module: `nicom.csareader`¶

CSA header reader from SPM spec

`CSAError`
`CSAReadError`
`get_acq_mat_txt`(csa_dict)
`get_b_matrix`(csa_dict)
`get_b_value`(csa_dict)
`get_csa_header`(dcm_data[, csa_type])	Get CSA header information from DICOM header
`get_g_vector`(csa_dict)
`get_ice_dims`(csa_dict)
`get_n_mosaic`(csa_dict)
`get_scalar`(csa_dict, tag_name)
`get_slice_normal`(csa_dict)
`get_vector`(csa_dict, tag_name, n)
`is_mosaic`(csa_dict)	Return True if the data is of Mosaic type
`nt_str`(s)	Strip string to first null
`read`(csa_str)	Read CSA header from string csa_str

Module: `nicom.dicomreaders`¶

`DicomReadError`
`mosaic_to_nii`(dcm_data)	Get Nifti file from Siemens
`read_mosaic_dir`(dicom_path[, globber, ...])	Read all Siemens mosaic DICOMs in directory, return arrays, params
`read_mosaic_dwi_dir`(dicom_path[, globber, ...])
`slices_to_series`(wrappers)	Sort sequence of slice wrappers into series

Module: `nicom.dicomwrappers`¶

Classes to wrap DICOM objects and files

The wrappers encapsulate the capabilities of the different DICOM formats.

They also allow dictionary-like access to named fields.

For calculated attributes, we return None where needed data is missing. It seemed strange to raise an error during attribute processing, other than an AttributeError - breaking the ‘properties manifesto’. So, any processing that needs to raise an error, should be in a method, rather than in a property, or property-like thing.

`FilterDwiIso`()	Filter out derived ISOTROPIC frames from DWI series
`FilterMultiStack`([keep_id])	Filter out all but one StackID
`FrameFilter`()	Base class for defining how to filter out (ignore) frames from a multiframe file
`MosaicWrapper`(dcm_data[, csa_header, n_mosaic])	Class for Siemens mosaic format data
`MultiframeWrapper`(dcm_data[, frame_filters])	Wrapper for Enhanced MR Storage SOP Class
`SiemensWrapper`(dcm_data[, csa_header])	Wrapper for Siemens format DICOMs
`Wrapper`(dcm_data)	Class to wrap general DICOM files
`WrapperError`
`WrapperPrecisionError`
`none_or_close`(val1, val2[, rtol, atol])	Match if val1 and val2 are both None, or are close
`wrapper_from_data`(dcm_data[, frame_filters])	Create DICOM wrapper from DICOM data object
`wrapper_from_file`(file_like, args, *kwargs)	Create DICOM wrapper from file_like object

Module: `nicom.dwiparams`¶

Process diffusion imaging parameters

q is a vector in Q space
b is a b value
g is the unit vector along the direction of q (the gradient direction)

Thus:

b = norm(q)

g = q / norm(q)

(norm(q) is the Euclidean norm of q)

The B matrix B is a symmetric positive semi-definite matrix. If q_est is the closest q vector equivalent to the B matrix, then:

B ~ (q_est . q_est.T) / norm(q_est)

`B2q`(B[, tol])	Estimate q vector from input B matrix B
`nearest_pos_semi_def`(B)	Least squares positive semi-definite tensor estimation
`q2bg`(q_vector[, tol])	Return b value and q unit vector from q vector q_vector

Module: `nicom.structreader`¶

Stream-like reader for packed data

Unpacker(buf[, ptr, endian])

Class to unpack values from buffer object

Module: `nicom.utils`¶

Utilities for working with DICOM datasets

`Vendor`(value[, names, module, qualname, ...])
`find_private_section`(dcm_data, group_no, creator)	Return start element in group group_no given creator name creator
`vendor_from_private`(dcm_data)	Try to determine the vendor by looking for specific private tags

`AscconvParseError`¶

class nibabel.nicom.ascconv.AscconvParseError¶

Bases: Exception

Error parsing ascconv file

__init__(*args, **kwargs)¶

`Atom`¶

class nibabel.nicom.ascconv.Atom(op, obj_type, obj_id)¶

Bases: object

Object to hold operation, object type and object identifier

An atom represents an element in an expression. For example:

a.b[0].c

has four elements. We call these elements “atoms”.

We represent objects (like a) as dicts for convenience.

The last element (.c) is an op = ast.Attribute operation where the object type (obj_type) of c is not constrained (we can’t tell from the operation what type it is). The obj_id is the name of the object – “c”.

The second to last element [0], is op = ast.Subscript, with object type dict (we know from the subsequent operation .c that this must be an object, we represent the object by a dict). The obj_id is the index 0.

Parameters:

op{‘name’, ‘attr’, ‘list’}: Assignment type. Assignment to name (root namespace), attribute or list element.
obj_type{list, dict, other}: Object type being assigned to.
obj_idstr or int: Key (obj_type is dict) or index (obj_type is list)

__init__(op, obj_type, obj_id)¶

`NoValue`¶

class nibabel.nicom.ascconv.NoValue¶

Bases: object

Signals no value present

__init__(*args, **kwargs)¶

assign2atoms¶

nibabel.nicom.ascconv.assign2atoms(assign_ast, default_class=<class 'int'>)¶

Parse single assignment ast from ascconv line into atoms

Parameters:

assign_astassignment statement ast: ast derived from single line of ascconv file.
default_classclass, optional: Class that will create an object where we cannot yet know the object type in the assignment.

Returns:

atomslist: List of atoms. See docstring for atoms. Defines left to right sequence of assignment in line_ast.

obj_from_atoms¶

nibabel.nicom.ascconv.obj_from_atoms(atoms, namespace)¶

Return object defined by list atoms in dict-like namespace

Parameters:

atomslist: List of atoms
namespacedict-like: Namespace in which object will be defined.

Returns:

obj_rootobject: Namespace such that we can set a desired value to the object defined in atoms with obj_root[obj_key] = value.
obj_keystr or int: Index into list or key into dictionary for obj_root.

parse_ascconv¶

nibabel.nicom.ascconv.parse_ascconv(ascconv_str, str_delim='"')¶

Parse the ‘ASCCONV’ format from input_str.

Parameters:

ascconv_strstr: The string we are parsing
str_delimstr, optional: String delimiter. Typically ‘”’ or ‘””’

Returns:

prot_dictOrderedDict: Meta data pulled from the ASCCONV section.
attrsOrderedDict: Any attributes stored in the ‘ASCCONV BEGIN’ line

Raises:

AsconvParseError: A line of the ASCCONV section could not be parsed.

`CSAError`¶

class nibabel.nicom.csareader.CSAError¶

Bases: Exception

__init__(*args, **kwargs)¶

`CSAReadError`¶

class nibabel.nicom.csareader.CSAReadError¶

Bases: CSAError

__init__(*args, **kwargs)¶

get_acq_mat_txt¶

nibabel.nicom.csareader.get_acq_mat_txt(csa_dict)¶

get_b_matrix¶

nibabel.nicom.csareader.get_b_matrix(csa_dict)¶

get_b_value¶

nibabel.nicom.csareader.get_b_value(csa_dict)¶

get_csa_header¶

nibabel.nicom.csareader.get_csa_header(dcm_data, csa_type='image')¶

Get CSA header information from DICOM header

Return None if the header does not contain CSA information of the specified csa_type

Parameters:

dcm_datadicom.Dataset: DICOM dataset. Should implement __getitem__ and, if initial check for presence of dcm_data[(0x29, 0x10)] passes, should satisfy interface for find_private_section.
csa_type{‘image’, ‘series’}, optional: Type of CSA field to read; default is ‘image’

Returns:

csa_infoNone or dict: Parsed CSA field of csa_type or None, if we cannot find the CSA information.

get_g_vector¶

nibabel.nicom.csareader.get_g_vector(csa_dict)¶

get_ice_dims¶

nibabel.nicom.csareader.get_ice_dims(csa_dict)¶

get_n_mosaic¶

nibabel.nicom.csareader.get_n_mosaic(csa_dict)¶

get_scalar¶

nibabel.nicom.csareader.get_scalar(csa_dict, tag_name)¶

get_slice_normal¶

nibabel.nicom.csareader.get_slice_normal(csa_dict)¶

get_vector¶

nibabel.nicom.csareader.get_vector(csa_dict, tag_name, n)¶

is_mosaic¶

nibabel.nicom.csareader.is_mosaic(csa_dict)¶

Return True if the data is of Mosaic type

Parameters:

csa_dictdict: dict containing read CSA data

Returns:

tfbool: True if the dcm_data appears to be of Siemens mosaic type, False otherwise

nt_str¶

nibabel.nicom.csareader.nt_str(s)¶

Strip string to first null

Parameters:

sbytes

Returns:

sdashstr: s stripped to first occurrence of null (0)

read¶

nibabel.nicom.csareader.read(csa_str)¶

Read CSA header from string csa_str

Parameters:

csa_strstr: byte string containing CSA header information

Returns:

headerdict: header information as dict, where header has fields (at least) type, n_tags, tags. header['tags'] is also a dictionary with one key, value pair for each tag in the header.

`DicomReadError`¶

class nibabel.nicom.dicomreaders.DicomReadError¶

Bases: Exception

__init__(*args, **kwargs)¶

mosaic_to_nii¶

nibabel.nicom.dicomreaders.mosaic_to_nii(dcm_data)¶

Get Nifti file from Siemens

Parameters:

dcm_datadicom.DataSet: DICOM header / image as read by dicom package

Returns:

imgNifti1Image: Nifti image object

read_mosaic_dir¶

nibabel.nicom.dicomreaders.read_mosaic_dir(dicom_path, globber='*.dcm', check_is_dwi=False, dicom_kwargs=None)¶

Read all Siemens mosaic DICOMs in directory, return arrays, params

Parameters:

dicom_pathstr: path containing mosaic DICOM images
globberstr, optional: glob to apply within dicom_path to select DICOM files. Default is *.dcm
check_is_dwibool, optional: If True, raises an error if we don’t find DWI information in the DICOM headers.
dicom_kwargsNone or dict: Extra keyword arguments to pass to the pydicom dcmread function.

Returns:

data4D array: data array with last dimension being acquisition. If there were N acquisitions, each of shape (X, Y, Z), data will be shape (X, Y, Z, N)
affine(4,4) array: affine relating 3D voxel space in data to RAS world space
b_values(N,) array: b values for each acquisition. nan if we did not find diffusion information for these images.
unit_gradients(N, 3) array: gradient directions of unit length for each acquisition. (nan, nan, nan) if we did not find diffusion information.

read_mosaic_dwi_dir¶

nibabel.nicom.dicomreaders.read_mosaic_dwi_dir(dicom_path, globber='*.dcm', dicom_kwargs=None)¶

slices_to_series¶

nibabel.nicom.dicomreaders.slices_to_series(wrappers)¶

Sort sequence of slice wrappers into series

This follows the SPM model fairly closely

Parameters:

wrapperssequence: sequence of Wrapper objects for sorting into volumes

Returns:

seriessequence: sequence of sequences of wrapper objects, where each sequence is wrapper objects comprising a series, sorted into slice order

`FilterDwiIso`¶

class nibabel.nicom.dicomwrappers.FilterDwiIso¶

Bases: FrameFilter

Filter out derived ISOTROPIC frames from DWI series

__init__(*args, **kwargs)¶

applies(dcm_wrp) → bool¶: Returns true if the filter should be applied to a dataset

keep(frame) → bool¶: Return true if the frame should be kept

`FilterMultiStack`¶

class nibabel.nicom.dicomwrappers.FilterMultiStack(keep_id=None)¶

Bases: FrameFilter

Filter out all but one StackID

__init__(keep_id=None)¶

applies(dcm_wrp) → bool¶: Returns true if the filter should be applied to a dataset

keep(frame) → bool¶: Return true if the frame should be kept

`FrameFilter`¶

class nibabel.nicom.dicomwrappers.FrameFilter¶

Bases: object

Base class for defining how to filter out (ignore) frames from a multiframe file

It is guaranteed that the applies method will on a dataset before the keep method is called on any of the frames inside.

__init__(*args, **kwargs)¶

applies(dcm_wrp) → bool¶: Returns true if the filter should be applied to a dataset

keep(frame_data) → bool¶: Return true if the frame should be kept

`MosaicWrapper`¶

class nibabel.nicom.dicomwrappers.MosaicWrapper(dcm_data, csa_header=None, n_mosaic=None)¶

Bases: SiemensWrapper

Class for Siemens mosaic format data

Mosaic format is a way of storing a 3D image in a 2D slice - and it’s as simple as you’d imagine it would be - just storing the slices in a mosaic similar to a light-box print.

We need to allow for this when getting the data and (because of an idiosyncrasy in the way Siemens stores the images) calculating the position of the first voxel.

Adds attributes:

n_mosaic : int
mosaic_size : int

Initialize Siemens Mosaic wrapper

The Siemens-specific information is in the csa_header, either passed in here, or read from the input dcm_data.

Parameters:

dcm_dataobject: object should allow ‘get’ and ‘__getitem__’ access. If csa_header is None, it should also be possible for to extract a CSA header from dcm_data. Usually this will be a dicom.dataset.Dataset object resulting from reading a DICOM file. A dict should also work.
csa_headerNone or mapping, optional: mapping giving values for Siemens CSA image sub-header.
n_mosaicNone or int, optional: number of images in mosaic. If None, try to get this number from csa_header. If this fails, raise an error

__init__(dcm_data, csa_header=None, n_mosaic=None)¶

Initialize Siemens Mosaic wrapper

The Siemens-specific information is in the csa_header, either passed in here, or read from the input dcm_data.

Parameters:

dcm_dataobject: object should allow ‘get’ and ‘__getitem__’ access. If csa_header is None, it should also be possible for to extract a CSA header from dcm_data. Usually this will be a dicom.dataset.Dataset object resulting from reading a DICOM file. A dict should also work.
csa_headerNone or mapping, optional: mapping giving values for Siemens CSA image sub-header.
n_mosaicNone or int, optional: number of images in mosaic. If None, try to get this number from csa_header. If this fails, raise an error

get_unscaled_data()¶

Get scaled image data from DICOMs

Resorts data block from mosaic to 3D

Returns:

dataarray: array with data as scaled from any scaling in the DICOM fields.

Notes

The apparent image in the DICOM file is a 2D array that consists of blocks, that are the output 2D slices. Let’s call the original array the slab, and the contained slices slices. The slices are of pixel dimension n_slice_rows x n_slice_cols. The slab is of pixel dimension n_slab_rows x n_slab_cols. Because the arrangement of blocks in the slab is defined as being square, the number of blocks per slab row and slab column is the same. Let n_blocks be the number of blocks contained in the slab. There is also n_slices - the number of slices actually collected, some number <= n_blocks. We have the value n_slices from the ‘NumberOfImagesInMosaic’ field of the Siemens private (CSA) header. n_row_blocks and n_col_blocks are therefore given by ceil(sqrt(n_slices)), and n_blocks is n_row_blocks ** 2. Also n_slice_rows == n_slab_rows / n_row_blocks, etc. Using these numbers we can therefore reconstruct the slices from the 2D DICOM pixel array.

property image_position¶

Return position of first voxel in data block

Adjusts Siemens mosaic position vector for bug in mosaic format position. See dicom_mosaic in doc/theory for details.

Parameters:

None

Returns:

img_pos(3,) array: position in mm of voxel (0,0,0) in Mosaic array

property image_shape¶: Return image shape as returned by get_data()

is_mosaic = True¶

`MultiframeWrapper`¶

class nibabel.nicom.dicomwrappers.MultiframeWrapper(dcm_data, frame_filters=None)¶

Bases: Wrapper

Wrapper for Enhanced MR Storage SOP Class

Tested with Philips’ Enhanced DICOM implementation.

The specification for the Enhanced MR image IOP / SOP began life as DICOM supplement 49, but as of 2016 it is part of the standard. In particular see:

Attributes:

is_multiframeboolean: Identifies dcmdata as multi-frame
framessequence: A sequence of dicom.dataset.Dataset objects populated by the dicom.dataset.Dataset.PerFrameFunctionalGroupsSequence attribute
sharedobject: The first (and only) dicom.dataset.Dataset object from a dicom.dataset.Dataset.SharedFunctionalgroupSequence.

Methods

vendor(self)
frame_order(self)
image_shape(self)
image_orient_patient(self)
voxel_sizes(self)
image_position(self)
series_signature(self)
scale_factors(self)
get_data(self)

Initializes MultiframeWrapper

Parameters:

dcm_dataobject: object should allow ‘get’ and ‘__getitem__’ access. Usually this will be a dicom.dataset.Dataset object resulting from reading a DICOM file.
frame_filtersIterable of FrameFilter: defines which frames inside the dataset should be ignored. If None then dicomwrappers.DEFAULT_FRAME_FILTERS will be used.

__init__(dcm_data, frame_filters=None)¶

Initializes MultiframeWrapper

Parameters:

dcm_dataobject: object should allow ‘get’ and ‘__getitem__’ access. Usually this will be a dicom.dataset.Dataset object resulting from reading a DICOM file.
frame_filtersIterable of FrameFilter: defines which frames inside the dataset should be ignored. If None then dicomwrappers.DEFAULT_FRAME_FILTERS will be used.

property frame_order¶

get_unscaled_data()¶

Return pixel array that is potentially reshaped, but without any scaling

Returns:

dataarray: array with raw pixel data from DICOM

property image_orient_patient¶: Note that this is _not_ LR flipped

property image_position¶

Return position of first voxel in data block

Parameters:

None

Returns:

img_pos(3,) array: position in mm of voxel (0,0) in image array

property image_shape¶

The array shape as it will be returned by get_data()

The shape is determined by the Rows DICOM attribute, Columns DICOM attribute, and the set of frame indices given by the FrameContentSequence[0].DimensionIndexValues DICOM attribute of each element in the PerFrameFunctionalGroupsSequence. The first two axes of the returned shape correspond to the rows, and columns respectively. The remaining axes correspond to those of the frame indices with order preserved.

What each axis in the frame indices refers to is given by the corresponding entry in the DimensionIndexSequence DICOM attribute. WARNING: Any axis referring to the StackID DICOM attribute will have been removed from the frame indices in determining the shape. This is because only a file containing a single stack is currently allowed by this wrapper.

References

C.7.6.16 Multi-Frame Functional Groups Module: http://dicom.nema.org/medical/dicom/current/output/pdf/part03.pdf#sect_C.7.6.16
C.7.6.17 Multi-Frame Dimension Module: http://dicom.nema.org/medical/dicom/current/output/pdf/part03.pdf#sect_C.7.6.17
Diagram of DimensionIndexSequence and DimensionIndexValues: http://dicom.nema.org/medical/dicom/current/output/pdf/part03.pdf#figure_C.7.6.17-1

is_multiframe = True¶

property scale_factors¶

Return (2, N) array of slope/intercept pairs

If there is a single global scale factor then N will be one, otherwise it will be the number of frames

property series_signature¶

Signature for matching slices into series

We use signature in self.is_same_series(other).

Returns:

signaturedict: with values of 2-element sequences, where first element is value, and second element is function to compare this value with another. This allows us to pass things like arrays, that might need to be allclose instead of equal

property vendor¶: The vendor of the instrument that produced the DICOM

property voxel_sizes¶: Get i, j, k voxel sizes

`SiemensWrapper`¶

class nibabel.nicom.dicomwrappers.SiemensWrapper(dcm_data, csa_header=None)¶

Bases: Wrapper

Wrapper for Siemens format DICOMs

Adds attributes:

csa_header : mapping
b_matrix : (3,3) array
q_vector : (3,) array

Initialize Siemens wrapper

The Siemens-specific information is in the csa_header, either passed in here, or read from the input dcm_data.

Parameters:

dcm_dataobject: object should allow ‘get’ and ‘__getitem__’ access. If csa_header is None, it should also be possible to extract a CSA header from dcm_data. Usually this will be a dicom.dataset.Dataset object resulting from reading a DICOM file.
csa_headerNone or mapping, optional: mapping giving values for Siemens CSA image sub-header. If None, we try and read the CSA information from dcm_data. If this fails, we fall back to an empty dict.

__init__(dcm_data, csa_header=None)¶

Initialize Siemens wrapper

The Siemens-specific information is in the csa_header, either passed in here, or read from the input dcm_data.

Parameters:

dcm_dataobject: object should allow ‘get’ and ‘__getitem__’ access. If csa_header is None, it should also be possible to extract a CSA header from dcm_data. Usually this will be a dicom.dataset.Dataset object resulting from reading a DICOM file.
csa_headerNone or mapping, optional: mapping giving values for Siemens CSA image sub-header. If None, we try and read the CSA information from dcm_data. If this fails, we fall back to an empty dict.

property b_matrix¶

Get DWI B matrix referring to voxel space

Parameters:

None

Returns:

B(3,3) array or None: B matrix in voxel orientation space. Returns None if this is not a Siemens header with the required information. We return None if this is a b0 acquisition

is_csa = True¶

property q_vector¶

Get DWI q vector referring to voxel space

Parameters:

None

Returns:

q: (3,) array: Estimated DWI q vector in voxel orientation space. Returns None if this is not (detectably) a DWI

property series_signature¶: Add ICE dims from CSA header to signature

property slice_normal¶

property vendor¶: The vendor of the instrument that produced the DICOM

`Wrapper`¶

class nibabel.nicom.dicomwrappers.Wrapper(dcm_data)¶

Bases: object

Class to wrap general DICOM files

Methods:

get_data()
get_unscaled_data()
get_pixel_array()
is_same_series(other)
__getitem__ : return attributes from dcm_data
get(key[, default]) - as usual given __getitem__ above

Attributes and things that look like attributes:

affine : (4, 4) array
dcm_data : object
image_shape : tuple
image_orient_patient : (3,2) array
slice_normal : (3,) array
rotation_matrix : (3,3) array
voxel_sizes : tuple length 3
image_position : sequence length 3
slice_indicator : float
series_signature : tuple
scale_factors : (N, 2) array
vendor : Vendor

Initialize wrapper

Parameters:

dcm_dataobject: object should allow ‘get’ and ‘__getitem__’ access. Usually this will be a dicom.dataset.Dataset object resulting from reading a DICOM file.

__init__(dcm_data)¶

Initialize wrapper

Parameters:

dcm_dataobject: object should allow ‘get’ and ‘__getitem__’ access. Usually this will be a dicom.dataset.Dataset object resulting from reading a DICOM file.

property affine¶

Mapping between voxel and DICOM coordinate system

(4, 4) affine matrix giving transformation between voxels in data array and mm in the DICOM patient coordinate system.

b_matrix = None¶

property b_value¶: Return b value for diffusion or None if not available

property b_vector¶: Return b vector for diffusion or None if not available

get(key, default=None)¶: Get values from underlying dicom data

get_data()¶

Get potentially scaled and reshaped image data from DICOMs

We return the data as DICOM understands it, first dimension is rows, second dimension is columns

Returns:

dataarray: array with data as scaled from any scaling in the DICOM fields.

get_pixel_array()¶

Return raw pixel array without reshaping or scaling

Returns:

dataarray: array with raw pixel data from DICOM

get_unscaled_data()¶

Return pixel array that is potentially reshaped, but without any scaling

Returns:

dataarray: array with raw pixel data from DICOM

property image_orient_patient¶: Note that this is _not_ LR flipped

property image_position¶

Return position of first voxel in data block

Parameters:

None

Returns:

img_pos(3,) array: position in mm of voxel (0,0) in image array

property image_shape¶: The array shape as it will be returned by get_data()

property instance_number¶: Just because we use this a lot for sorting

is_csa = False¶

is_mosaic = False¶

is_multiframe = False¶

is_same_series(other)¶

Return True if other appears to be in same series

Parameters:

otherobject: object with series_signature attribute that is a mapping. Usually it’s a Wrapper or sub-class instance.

Returns:

tfbool: True if other might be in the same series as self, False otherwise.

q_vector = None¶

property rotation_matrix¶

Return rotation matrix between array indices and mm

Note that we swap the two columns of the ‘ImageOrientPatient’ when we create the rotation matrix. This is takes into account the slightly odd ij transpose construction of the DICOM orientation fields - see doc/theory/dicom_orientaiton.rst.

property scale_factors¶: Return (2, N) array of slope/intercept pairs

property series_signature¶

Signature for matching slices into series

We use signature in self.is_same_series(other).

Returns:

signaturedict: with values of 2-element sequences, where first element is value, and second element is function to compare this value with another. This allows us to pass things like arrays, that might need to be allclose instead of equal

property slice_indicator¶

A number that is higher for higher slices in Z

Comparing this number between two adjacent slices should give a difference equal to the voxel size in Z.

See doc/theory/dicom_orientation for description

property slice_normal¶

property vendor¶: The vendor of the instrument that produced the DICOM

property voxel_sizes¶: voxel sizes for array as returned by get_data()

`WrapperError`¶

class nibabel.nicom.dicomwrappers.WrapperError¶

Bases: Exception

__init__(*args, **kwargs)¶

`WrapperPrecisionError`¶

class nibabel.nicom.dicomwrappers.WrapperPrecisionError¶

Bases: WrapperError

__init__(*args, **kwargs)¶

none_or_close¶

nibabel.nicom.dicomwrappers.none_or_close(val1, val2, rtol=1e-05, atol=1e-06)¶

Match if val1 and val2 are both None, or are close

Parameters:

val1None or array-like
val2None or array-like
rtolfloat, optional: Relative tolerance; see np.allclose
atolfloat, optional: Absolute tolerance; see np.allclose

Returns:

tfbool: True iff (both val1 and val2 are None) or (val1 and val2 are close arrays, as detected by np.allclose with parameters rtol and atal).

Examples

>>> none_or_close(None, None)
True
>>> none_or_close(1, None)
False
>>> none_or_close(None, 1)
False
>>> none_or_close([1,2], [1,2])
True
>>> none_or_close([0,1], [0,2])
False

wrapper_from_data¶

nibabel.nicom.dicomwrappers.wrapper_from_data(dcm_data, frame_filters=None)¶

Create DICOM wrapper from DICOM data object

Parameters:

dcm_datadicom.dataset.Dataset instance or similar: Object allowing attribute access, with DICOM attributes. Probably a dataset as read by pydicom.
frame_filters: Optionally override the frame_filters used to create a MultiFrameWrapper

Returns:

dcm_wdicomwrappers.Wrapper or subclass: DICOM wrapper corresponding to DICOM data type

wrapper_from_file¶

nibabel.nicom.dicomwrappers.wrapper_from_file(file_like, *args, **kwargs)¶

Create DICOM wrapper from file_like object

Parameters:

file_likeobject: filename string or file-like object, pointing to a valid DICOM file readable by pydicom
*argspositional: args to dicom.dcmread command.
**kwargskeyword: args to dicom.dcmread command. force=True might be a likely keyword argument.

Returns:

dcm_wdicomwrappers.Wrapper or subclass: DICOM wrapper corresponding to DICOM data type

B2q¶

nibabel.nicom.dwiparams.B2q(B, tol=None)¶

Estimate q vector from input B matrix B

We require that the input B is symmetric positive definite.

Because the solution is a square root, the sign of the returned vector is arbitrary. We set the vector to have a positive x component by convention.

Parameters:

B(3,3) array-like: B matrix - symmetric. We do not check the symmetry.
tolNone or float: absolute tolerance below which to consider eigenvalues of the B matrix to be small enough not to worry about them being negative, in check for positive semi-definite-ness. None (default) results in a fairly tight numerical threshold proportional to the maximum eigenvalue

Returns:

q(3,) vector: Estimated q vector from B matrix B

nearest_pos_semi_def¶

nibabel.nicom.dwiparams.nearest_pos_semi_def(B)¶

Least squares positive semi-definite tensor estimation

Reference: Niethammer M, San Jose Estepar R, Bouix S, Shenton M, Westin CF. On diffusion tensor estimation. Conf Proc IEEE Eng Med Biol Soc. 2006;1:2622-5. PubMed PMID: 17946125; PubMed Central PMCID: PMC2791793.

Parameters:

B(3,3) array-like: B matrix - symmetric. We do not check the symmetry.

Returns:

npds(3,3) array: Estimated nearest positive semi-definite array to matrix B.

Examples

>>> B = np.diag([1, 1, -1])
>>> nearest_pos_semi_def(B)
array([[0.75, 0.  , 0.  ],
       [0.  , 0.75, 0.  ],
       [0.  , 0.  , 0.  ]])

q2bg¶

nibabel.nicom.dwiparams.q2bg(q_vector, tol=1e-05)¶

Return b value and q unit vector from q vector q_vector

Parameters:

q_vector(3,) array-like: q vector
tolfloat, optional: q vector L2 norm below which q_vector considered to be b_value of zero, and therefore g_vector also considered to zero.

Returns:

b_valuefloat: L2 Norm of q_vector or 0 if L2 norm < tol
g_vectorshape (3,) ndarray: q_vector / b_value or 0 if L2 norma < tol

Examples

>>> q2bg([1, 0, 0])
(1.0, array([1., 0., 0.]))
>>> q2bg([0, 10, 0])
(10.0, array([0., 1., 0.]))
>>> q2bg([0, 0, 0])
(0.0, array([0., 0., 0.]))

`Unpacker`¶

class nibabel.nicom.structreader.Unpacker(buf, ptr=0, endian=None)¶

Bases: object

Class to unpack values from buffer object

The buffer object is usually a string. Caches compiled struct format strings so that repeated unpacking with the same format string should be faster than using struct.unpack directly.

Examples

>>> a = b'1234567890'
>>> upk = Unpacker(a)
>>> upk.unpack('2s') == (b'12',)
True
>>> upk.unpack('2s') == (b'34',)
True
>>> upk.ptr
4
>>> upk.read(3) == b'567'
True
>>> upk.ptr
7

Initialize unpacker

Parameters:

bufbuffer: object implementing buffer protocol (e.g. str)
ptrint, optional: offset at which to begin reads from buf
endianNone or str, optional: endian code to prepend to format, as for unpack endian codes. None (the default) corresponds to the default behavior of struct - assuming system endian unless you specify the byte order specifically in the format string passed to unpack

__init__(buf, ptr=0, endian=None)¶

Initialize unpacker

Parameters:

bufbuffer: object implementing buffer protocol (e.g. str)
ptrint, optional: offset at which to begin reads from buf
endianNone or str, optional: endian code to prepend to format, as for unpack endian codes. None (the default) corresponds to the default behavior of struct - assuming system endian unless you specify the byte order specifically in the format string passed to unpack

read(n_bytes=-1)¶

Return byte string of length n_bytes at current position

Returns sub-string from self.buf and updates self.ptr to the position after the read data.

Parameters:

n_bytesint, optional: number of bytes to read. Can be -1 (the default) in which case we return all the remaining bytes in self.buf

Returns:

sbyte string

unpack(fmt)¶

Unpack values from contained buffer

Unpacks values from self.buf and updates self.ptr to the position after the read data.

Parameters:

fmtstr: format string as for unpack

Returns:

valuestuple: values as unpacked from self.buf according to fmt

`Vendor`¶

class nibabel.nicom.utils.Vendor(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

__init__(*args, **kwds)¶

GE = 2¶

PHILIPS = 3¶

SIEMENS = 1¶

find_private_section¶

nibabel.nicom.utils.find_private_section(dcm_data, group_no, creator)¶

Return start element in group group_no given creator name creator

Private attribute tags need to announce where they will go by putting a tag in the private group (here group_no) between elements 1 and 0xFF. The element number of these tags give the start of matching information, in the higher tag numbers.

Parameters:

dcm_datadicom dataset: Iterating over dcm_data produces elements with attributes tag, VR, value
group_noint: Group number in which to search
creatorstr or bytes or regex: Name of section - e.g. ‘SIEMENS CSA HEADER’ - or regex to search for section name. Regex used via creator.search(element_value) where element_value is the value of the data element.

Returns:

element_startint: Element number at which named section starts.

vendor_from_private¶

nibabel.nicom.utils.vendor_from_private(dcm_data)¶: Try to determine the vendor by looking for specific private tags

NiBabel

Access a cacophony of neuro-imaging file formats

nicom¶

Module: nicom.ascconv¶

Module: nicom.csareader¶

Module: nicom.dicomreaders¶

Module: nicom.dicomwrappers¶

Module: nicom.dwiparams¶

Module: nicom.structreader¶

Module: nicom.utils¶

assign2atoms¶

obj_from_atoms¶

parse_ascconv¶

get_acq_mat_txt¶

get_b_matrix¶

get_b_value¶

get_csa_header¶

get_g_vector¶

get_ice_dims¶

get_n_mosaic¶

get_scalar¶

get_slice_normal¶

get_vector¶

is_mosaic¶

nt_str¶

read¶

mosaic_to_nii¶

read_mosaic_dir¶

read_mosaic_dwi_dir¶

slices_to_series¶

none_or_close¶

wrapper_from_data¶

wrapper_from_file¶

B2q¶

nearest_pos_semi_def¶

q2bg¶

find_private_section¶

vendor_from_private¶

`nicom`¶

Module: `nicom.ascconv`¶

Module: `nicom.csareader`¶

Module: `nicom.dicomreaders`¶

Module: `nicom.dicomwrappers`¶

Module: `nicom.dwiparams`¶

Module: `nicom.structreader`¶

Module: `nicom.utils`¶