# NiBabel

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

# `spm99analyze`

Read / write access to SPM99 version of analyze image format

`Spm99AnalyzeHeader`([binaryblock, ...]) | Class for SPM99 variant of basic Analyze header
`Spm99AnalyzeImage`(dataobj, affine[, header, ...]) | Class for SPM99 variant of basic Analyze image
`SpmAnalyzeHeader`([binaryblock, endianness, ...]) | Basic scaling Spm Analyze header

## `Spm99AnalyzeHeader`

class nibabel.spm99analyze.Spm99AnalyzeHeader(binaryblock=None, endianness=None, check=True)

  Bases: `SpmAnalyzeHeader`

  Class for SPM99 variant of basic Analyze header

  SPM99 variant adds the following to basic Analyze format:

  - voxel origin;

  - slope scaling of data.

  Initialize header from binary data block

  Parameters:
    binaryblock{None, string} optional

      binary block to set into header. By default, None, in which case we insert the default empty header block

    endianness{None, ‘<’,’>’, other endian code} string, optional

      endianness of the binaryblock. If None, guess endianness from the data.

    check bool, optional

      Whether to check content of header in initialization. Default is True.

  Examples

      >>> hdr1 = AnalyzeHeader() # an empty header
      >>> hdr1.endianness == native_code
      True
      >>> hdr1.get_data_shape()
      (0,)
      >>> hdr1.set_data_shape((1,2,3)) # now with some content
      >>> hdr1.get_data_shape()
      (1, 2, 3)

  We can set the binary block directly via this initialization. Here we get it from the header we have just made

      >>> binblock2 = hdr1.binaryblock
      >>> hdr2 = AnalyzeHeader(binblock2)
      >>> hdr2.get_data_shape()
      (1, 2, 3)

  Empty headers are native endian by default

      >>> hdr2.endianness == native_code
      True

  You can pass valid opposite endian headers with the `endianness` parameter. Even empty headers can have endianness

      >>> hdr3 = AnalyzeHeader(endianness=swapped_code)
      >>> hdr3.endianness == swapped_code
      True

  If you do not pass an endianness, and you pass some data, we will try to guess from the passed data.

      >>> binblock3 = hdr3.binaryblock
      >>> hdr4 = AnalyzeHeader(binblock3)
      >>> hdr4.endianness == swapped_code
      True

  __init__(binaryblock=None, endianness=None, check=True)

    Initialize header from binary data block

    Parameters:
      binaryblock{None, string} optional

        binary block to set into header. By default, None, in which case we insert the default empty header block

      endianness{None, ‘<’,’>’, other endian code} string, optional

        endianness of the binaryblock. If None, guess endianness from the data.

      check bool, optional

        Whether to check content of header in initialization. Default is True.

    Examples

        >>> hdr1 = AnalyzeHeader() # an empty header
        >>> hdr1.endianness == native_code
        True
        >>> hdr1.get_data_shape()
        (0,)
        >>> hdr1.set_data_shape((1,2,3)) # now with some content
        >>> hdr1.get_data_shape()
        (1, 2, 3)

    We can set the binary block directly via this initialization. Here we get it from the header we have just made

        >>> binblock2 = hdr1.binaryblock
        >>> hdr2 = AnalyzeHeader(binblock2)
        >>> hdr2.get_data_shape()
        (1, 2, 3)

    Empty headers are native endian by default

        >>> hdr2.endianness == native_code
        True

    You can pass valid opposite endian headers with the `endianness` parameter. Even empty headers can have endianness

        >>> hdr3 = AnalyzeHeader(endianness=swapped_code)
        >>> hdr3.endianness == swapped_code
        True

    If you do not pass an endianness, and you pass some data, we will try to guess from the passed data.

        >>> binblock3 = hdr3.binaryblock
        >>> hdr4 = AnalyzeHeader(binblock3)
        >>> hdr4.endianness == swapped_code
        True

  get_best_affine()

    Get affine from header, using SPM origin field if sensible

    The default translations are got from the `origin` field, if set, or from the center of the image otherwise.

    Examples

        >>> hdr = Spm99AnalyzeHeader()
        >>> hdr.set_data_shape((3, 5, 7))
        >>> hdr.set_zooms((3, 2, 1))
        >>> hdr.default_x_flip
        True
        >>> hdr.get_origin_affine() # from center of image
        array([[-3.,  0.,  0.,  3.],
               [ 0.,  2.,  0., -4.],
               [ 0.,  0.,  1., -3.],
               [ 0.,  0.,  0.,  1.]])
        >>> hdr['origin'][:3] = [3,4,5]
        >>> hdr.get_origin_affine() # using origin
        array([[-3.,  0.,  0.,  6.],
               [ 0.,  2.,  0., -6.],
               [ 0.,  0.,  1., -4.],
               [ 0.,  0.,  0.,  1.]])
        >>> hdr['origin'] = 0 # unset origin
        >>> hdr.set_data_shape((3, 5, 7))
        >>> hdr.get_origin_affine() # from center of image
        array([[-3.,  0.,  0.,  3.],
               [ 0.,  2.,  0., -4.],
               [ 0.,  0.,  1., -3.],
               [ 0.,  0.,  0.,  1.]])

  get_origin_affine()

    Get affine from header, using SPM origin field if sensible

    The default translations are got from the `origin` field, if set, or from the center of the image otherwise.

    Examples

        >>> hdr = Spm99AnalyzeHeader()
        >>> hdr.set_data_shape((3, 5, 7))
        >>> hdr.set_zooms((3, 2, 1))
        >>> hdr.default_x_flip
        True
        >>> hdr.get_origin_affine() # from center of image
        array([[-3.,  0.,  0.,  3.],
               [ 0.,  2.,  0., -4.],
               [ 0.,  0.,  1., -3.],
               [ 0.,  0.,  0.,  1.]])
        >>> hdr['origin'][:3] = [3,4,5]
        >>> hdr.get_origin_affine() # using origin
        array([[-3.,  0.,  0.,  6.],
               [ 0.,  2.,  0., -6.],
               [ 0.,  0.,  1., -4.],
               [ 0.,  0.,  0.,  1.]])
        >>> hdr['origin'] = 0 # unset origin
        >>> hdr.set_data_shape((3, 5, 7))
        >>> hdr.get_origin_affine() # from center of image
        array([[-3.,  0.,  0.,  3.],
               [ 0.,  2.,  0., -4.],
               [ 0.,  0.,  1., -3.],
               [ 0.,  0.,  0.,  1.]])

  set_origin_from_affine(affine)

    Set SPM origin to header from affine matrix.

    The `origin` field was read but not written by SPM99 and 2. It was used for storing a central voxel coordinate, that could be used in aligning the image to some standard position - a proxy for a full translation vector that was usually stored in a separate matlab .mat file.

    Nifti uses the space occupied by the SPM `origin` field for important other information (the transform codes), so writing the origin will make the header a confusing Nifti file. If you work with both Analyze and Nifti, you should probably avoid doing this.

    Parameters:
      affine array-like, shape (4,4)

        Affine matrix to set

    Returns:
      None

    Examples

        >>> hdr = Spm99AnalyzeHeader()
        >>> hdr.set_data_shape((3, 5, 7))
        >>> hdr.set_zooms((3,2,1))
        >>> hdr.get_origin_affine()
        array([[-3.,  0.,  0.,  3.],
               [ 0.,  2.,  0., -4.],
               [ 0.,  0.,  1., -3.],
               [ 0.,  0.,  0.,  1.]])
        >>> affine = np.diag([3,2,1,1])
        >>> affine[:3,3] = [-6, -6, -4]
        >>> hdr.set_origin_from_affine(affine)
        >>> np.all(hdr['origin'][:3] == [3,4,5])
        True
        >>> hdr.get_origin_affine()
        array([[-3.,  0.,  0.,  6.],
               [ 0.,  2.,  0., -6.],
               [ 0.,  0.,  1., -4.],
               [ 0.,  0.,  0.,  1.]])

## `Spm99AnalyzeImage`

class nibabel.spm99analyze.Spm99AnalyzeImage(dataobj, affine, header=None, extra=None, file_map=None, dtype=None)

  Bases: `AnalyzeImage`

  Class for SPM99 variant of basic Analyze image

  Initialize image

  The image is a combination of (array-like, affine matrix, header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.

  Parameters:
    dataobj object

      Object containing image data. It should be some object that returns an array from `np.asanyarray`. It should have a `shape` attribute or property

    affine None or (4,4) array-like

      homogeneous affine giving relationship between voxel coordinates and world coordinates. Affine can also be None. In this case, `obj.affine` also returns None, and the affine as written to disk will depend on the file format.

    header None or mapping or header instance, optional

      metadata for this image format

    extra None or mapping, optional

      metadata to associate with image that cannot be stored in the metadata of this image type

    file_map mapping, optional

      mapping giving file information for this image format

  __init__(dataobj, affine, header=None, extra=None, file_map=None, dtype=None)

    Initialize image

    The image is a combination of (array-like, affine matrix, header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.

    Parameters:
      dataobj object

        Object containing image data. It should be some object that returns an array from `np.asanyarray`. It should have a `shape` attribute or property

      affine None or (4,4) array-like

        homogeneous affine giving relationship between voxel coordinates and world coordinates. Affine can also be None. In this case, `obj.affine` also returns None, and the affine as written to disk will depend on the file format.

      header None or mapping or header instance, optional

        metadata for this image format

      extra None or mapping, optional

        metadata to associate with image that cannot be stored in the metadata of this image type

      file_map mapping, optional

        mapping giving file information for this image format

  files_types: tuple[tuple[str, str], ...] = (('image', '.img'), ('header', '.hdr'), ('mat', '.mat'))
  classmethod from_file_map(file_map, *, mmap=True, keep_file_open=None)

    Class method to create image from mapping in `file_map`

    Parameters:
      file_map dict

        Mapping with (key, value) pairs of (`file_type`, FileHolder instance giving file-likes for each file needed for this image type.

      mmap{True, False, ‘c’, ‘r’}, optional, keyword only

        mmap controls the use of numpy memory mapping for reading image array data. If False, do not try numpy `memmap` for data array. If one of {‘c’, ‘r’}, try numpy memmap with `mode=mmap`. A mmap value of True gives the same behavior as `mmap='c'`. If image data file cannot be memory-mapped, ignore mmap value and read array from file.

      keep_file_open{ None, True, False }, optional, keyword only

        keep_file_open controls whether a new file handle is created every time the image is accessed, or a single file handle is created and used for the lifetime of this `ArrayProxy`. If `True`, a single file handle is created and used. If `False`, a new file handle is created every time the image is accessed. If `file_map` refers to an open file handle, this setting has no effect. The default value (`None`) will result in the value of `nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT` being used.

    Returns:
      img Spm99AnalyzeImage instance
  has_affine = True
  header_class

    alias of `Spm99AnalyzeHeader`

  makeable: bool = True
  rw: bool = True
  to_file_map(file_map=None, dtype=None)

    Write image to file_map or contained `self.file_map`

    Extends Analyze `to_file_map` method by writing `mat` file

    Parameters:
      file_map None or mapping, optional

        files mapping. If None (default) use object’s `file_map` attribute instead

## `SpmAnalyzeHeader`

class nibabel.spm99analyze.SpmAnalyzeHeader(binaryblock=None, endianness=None, check=True)

  Bases: `AnalyzeHeader`

  Basic scaling Spm Analyze header

  Initialize header from binary data block

  Parameters:
    binaryblock{None, string} optional

      binary block to set into header. By default, None, in which case we insert the default empty header block

    endianness{None, ‘<’,’>’, other endian code} string, optional

      endianness of the binaryblock. If None, guess endianness from the data.

    check bool, optional

      Whether to check content of header in initialization. Default is True.

  Examples

      >>> hdr1 = AnalyzeHeader() # an empty header
      >>> hdr1.endianness == native_code
      True
      >>> hdr1.get_data_shape()
      (0,)
      >>> hdr1.set_data_shape((1,2,3)) # now with some content
      >>> hdr1.get_data_shape()
      (1, 2, 3)

  We can set the binary block directly via this initialization. Here we get it from the header we have just made

      >>> binblock2 = hdr1.binaryblock
      >>> hdr2 = AnalyzeHeader(binblock2)
      >>> hdr2.get_data_shape()
      (1, 2, 3)

  Empty headers are native endian by default

      >>> hdr2.endianness == native_code
      True

  You can pass valid opposite endian headers with the `endianness` parameter. Even empty headers can have endianness

      >>> hdr3 = AnalyzeHeader(endianness=swapped_code)
      >>> hdr3.endianness == swapped_code
      True

  If you do not pass an endianness, and you pass some data, we will try to guess from the passed data.

      >>> binblock3 = hdr3.binaryblock
      >>> hdr4 = AnalyzeHeader(binblock3)
      >>> hdr4.endianness == swapped_code
      True

  __init__(binaryblock=None, endianness=None, check=True)

    Initialize header from binary data block

    Parameters:
      binaryblock{None, string} optional

        binary block to set into header. By default, None, in which case we insert the default empty header block

      endianness{None, ‘<’,’>’, other endian code} string, optional

        endianness of the binaryblock. If None, guess endianness from the data.

      check bool, optional

        Whether to check content of header in initialization. Default is True.

    Examples

        >>> hdr1 = AnalyzeHeader() # an empty header
        >>> hdr1.endianness == native_code
        True
        >>> hdr1.get_data_shape()
        (0,)
        >>> hdr1.set_data_shape((1,2,3)) # now with some content
        >>> hdr1.get_data_shape()
        (1, 2, 3)

    We can set the binary block directly via this initialization. Here we get it from the header we have just made

        >>> binblock2 = hdr1.binaryblock
        >>> hdr2 = AnalyzeHeader(binblock2)
        >>> hdr2.get_data_shape()
        (1, 2, 3)

    Empty headers are native endian by default

        >>> hdr2.endianness == native_code
        True

    You can pass valid opposite endian headers with the `endianness` parameter. Even empty headers can have endianness

        >>> hdr3 = AnalyzeHeader(endianness=swapped_code)
        >>> hdr3.endianness == swapped_code
        True

    If you do not pass an endianness, and you pass some data, we will try to guess from the passed data.

        >>> binblock3 = hdr3.binaryblock
        >>> hdr4 = AnalyzeHeader(binblock3)
        >>> hdr4.endianness == swapped_code
        True

  classmethod default_structarr(endianness=None)

    Create empty header binary block with given endianness

  get_slope_inter()

    Get scalefactor and intercept

    If scalefactor is 0.0 return None to indicate no scalefactor. Intercept is always None because SPM99 analyze cannot store intercepts.

  has_data_intercept = False
  has_data_slope = True
  set_slope_inter(slope, inter=None)

    Set slope and / or intercept into header

    Set slope and intercept for image data, such that, if the image data is `arr`, then the scaled image data will be `(arr * slope) + inter`

    The SPM Analyze header can’t save an intercept value, and we raise an error unless inter is None, NaN or 0

    Parameters:
      slope None or float

        If None, implies slope of NaN. NaN is a signal to the image writing routines to rescale on save. 0, Inf, -Inf are invalid and cause a HeaderDataError

      inter None or float, optional

        intercept. Must be None, NaN or 0, because SPM99 cannot store intercepts.

  template_dtype = dtype([('sizeof_hdr', '<i4'), ('data_type', 'S10'), ('db_name', 'S18'), ('extents', '<i4'), ('session_error', '<i2'), ('regular', 'S1'), ('hkey_un0', 'S1'), ('dim', '<i2', (8,)), ('vox_units', 'S4'), ('cal_units', 'S8'), ('unused1', '<i2'), ('datatype', '<i2'), ('bitpix', '<i2'), ('dim_un0', '<i2'), ('pixdim', '<f4', (8,)), ('vox_offset', '<f4'), ('scl_slope', '<f4'), ('funused2', '<f4'), ('funused3', '<f4'), ('cal_max', '<f4'), ('cal_min', '<f4'), ('compressed', '<i4'), ('verified', '<i4'), ('glmax', '<i4'), ('glmin', '<i4'), ('descrip', 'S80'), ('aux_file', 'S24'), ('orient', 'S1'), ('origin', '<i2', (5,)), ('generated', 'S10'), ('scannum', 'S10'), ('patient_id', 'S10'), ('exp_date', 'S10'), ('exp_time', 'S10'), ('hist_un0', 'S3'), ('views', '<i4'), ('vols_added', '<i4'), ('start_field', '<i4'), ('field_skip', '<i4'), ('omax', '<i4'), ('omin', '<i4'), ('smax', '<i4'), ('smin', '<i4')])