# NiBabel

### Access a cacophony of neuro-imaging file formats

# `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`(*values) |
`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_id str 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_ast assignment statement ast

      ast derived from single line of ascconv file.

    default_class class, optional

      Class that will create an object where we cannot yet know the object type in the assignment.

  Returns:
    atoms list

      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:
    atoms list

      List of `atoms`

    namespace dict-like

      Namespace in which object will be defined.

  Returns:
    obj_root object

      Namespace such that we can set a desired value to the object defined in atoms with `obj_root[obj_key] = value`.

    obj_key str 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_str str

      The string we are parsing

    str_delim str, optional

      String delimiter. Typically ‘”’ or ‘””’

  Returns:
    prot_dict OrderedDict

      Meta data pulled from the ASCCONV section.

    attrs OrderedDict

      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_data dicom.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_info None 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_dict dict

      dict containing read CSA data

  Returns:
    tf bool

      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:
    s bytes
  Returns:
    sdash str

      s stripped to first occurrence of null (0)

### read

nibabel.nicom.csareader.read(csa_str)

  Read CSA header from string csa_str

  Parameters:
    csa_str str

      byte string containing CSA header information

  Returns:
    header dict

      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_data `dicom.DataSet`

      DICOM header / image as read by `dicom` package

  Returns:
    img `Nifti1Image`

      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_path str

      path containing mosaic DICOM images

    globber str, optional

      glob to apply within dicom_path to select DICOM files. Default is `*.dcm`

    check_is_dwi bool, optional

      If True, raises an error if we don’t find DWI information in the DICOM headers.

    dicom_kwargs None or dict

      Extra keyword arguments to pass to the pydicom `dcmread` function.

  Returns:
    data 4D 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:
    wrappers sequence

      sequence of `Wrapper` objects for sorting into volumes

  Returns:
    series sequence

      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 called 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_data object

      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_header None or mapping, optional

      mapping giving values for Siemens CSA image sub-header.

    n_mosaic None 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_data object

        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_header None or mapping, optional

        mapping giving values for Siemens CSA image sub-header.

      n_mosaic None 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:
      data array

        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:

  - A.36 Enhanced MR Information Object Definitions;

  - C.7.6.16 Multi-Frame Functional Groups Module;

  - C.7.6.17 Multi-Frame Dimension Module.

  Attributes:
    is_multiframe boolean

      Identifies dcmdata as multi-frame

    frames sequence

      A sequence of `dicom.dataset.Dataset` objects populated by the `dicom.dataset.Dataset.PerFrameFunctionalGroupsSequence` attribute

    shared object

      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_data object

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

    frame_filters Iterable 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_data object

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

      frame_filters Iterable of FrameFilter

        defines which frames inside the dataset should be ignored. If None then dicomwrappers.DEFAULT_FRAME_FILTERS will be used.

  property frame_order

    The ordering of frames to make nD array

  get_unscaled_data()

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

    Returns:
      data array

        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:
      signature dict

        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_data object

      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_header None 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_data object

        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_header None 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_data object

      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_data object

        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:
      data array

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

  get_pixel_array()

    Return raw pixel array without reshaping or scaling

    Returns:
      data array

        array with raw pixel data from DICOM

  get_unscaled_data()

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

    Returns:
      data array

        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:
      other object

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

    Returns:
      tf bool

        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:
      signature dict

        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:
    val1 None or array-like
    val2 None or array-like
    rtol float, optional

      Relative tolerance; see `np.allclose`

    atol float, optional

      Absolute tolerance; see `np.allclose`

  Returns:
    tf bool

      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_data `dicom.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_w `dicomwrappers.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_like object

      filename string or file-like object, pointing to a valid DICOM file readable by `pydicom`

    *args positional

      args to `dicom.dcmread` command.

    **kwargs keyword

      args to `dicom.dcmread` command. `force=True` might be a likely keyword argument.

  Returns:
    dcm_w `dicomwrappers.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.

    tol None 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

    tol float, 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_value float

      L2 Norm of q_vector or 0 if L2 norm < tol

    g_vector shape (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:
    buf buffer

      object implementing buffer protocol (e.g. str)

    ptr int, optional

      offset at which to begin reads from buf

    endian None 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:
      buf buffer

        object implementing buffer protocol (e.g. str)

      ptr int, optional

        offset at which to begin reads from buf

      endian None 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_bytes int, optional

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

    Returns:
      s byte 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:
      fmt str

        format string as for `unpack`

    Returns:
      values tuple

        values as unpacked from `self.buf` according to fmt

### `Vendor`

class nibabel.nicom.utils.Vendor(*values)

  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_data dicom `dataset`

      Iterating over dcm_data produces `elements` with attributes `tag`, `VR`, `value`

    group_no int

      Group number in which to search

    creator str 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_start int

      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