# NiBabel

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

# `arraywriters`

Array writer objects

Array writers have init signature:

    def __init__(self, array, out_dtype=None)

and methods

- scaling_needed() - returns True if array requires scaling for write

- finite_range() - returns min, max of self.array

- to_fileobj(fileobj, offset=None, order=’F’)

They must have attributes / properties of:

- array

- out_dtype

- has_nan

They may have attributes:

- slope

- inter

They are designed to write arrays to a fileobj with reasonable memory efficiency.

Array writers may be able to scale the array or apply an intercept, or do something else to make sense of conversions between float and int, or between larger ints and smaller.

`ArrayWriter`(array[, out_dtype]) | Initialize array writer
`ScalingError` |
`SlopeArrayWriter`(array[, out_dtype, ...]) | ArrayWriter that can use scalefactor for writing arrays
`SlopeInterArrayWriter`(array[, out_dtype, ...]) | Array writer that can use slope and intercept to scale array
`WriterError` |
`get_slope_inter`(writer) | Return slope, intercept from array writer object
`make_array_writer`(data, out_type[, ...]) | Make array writer instance for array data and output type out_type

## `ArrayWriter`

class nibabel.arraywriters.ArrayWriter(array, out_dtype=None, **kwargs)

  Bases: `object`

  Initialize array writer

  Parameters:
    array array-like

      array-like object

    out_dtype None or dtype

      dtype with which array will be written. For this class, out_dtype` needs to be the same as the dtype of the input array or a swapped version of the same.

    **kwargs keyword arguments

      This class processes only:

      - nan2zero : bool, optional Whether to set NaN values to 0 when writing integer output. Defaults to True. If False, NaNs get converted with numpy `astype`, and the behavior is undefined. Ignored for floating point output.

      - check_scaling : bool, optional If True, check if scaling needed and raise error if so. Default is True

  Examples

      >>> arr = np.array([0, 255], np.uint8)
      >>> aw = ArrayWriter(arr)
      >>> aw = ArrayWriter(arr, np.int8)
      Traceback (most recent call last):
          ...
      WriterError: Scaling needed but cannot scale
      >>> aw = ArrayWriter(arr, np.int8, check_scaling=False)

  __init__(array, out_dtype=None, **kwargs)

    Initialize array writer

    Parameters:
      array array-like

        array-like object

      out_dtype None or dtype

        dtype with which array will be written. For this class, out_dtype` needs to be the same as the dtype of the input array or a swapped version of the same.

      **kwargs keyword arguments

        This class processes only:

        - nan2zero : bool, optional Whether to set NaN values to 0 when writing integer output. Defaults to True. If False, NaNs get converted with numpy `astype`, and the behavior is undefined. Ignored for floating point output.

        - check_scaling : bool, optional If True, check if scaling needed and raise error if so. Default is True

    Examples

        >>> arr = np.array([0, 255], np.uint8)
        >>> aw = ArrayWriter(arr)
        >>> aw = ArrayWriter(arr, np.int8)
        Traceback (most recent call last):
            ...
        WriterError: Scaling needed but cannot scale
        >>> aw = ArrayWriter(arr, np.int8, check_scaling=False)

  property array

    Return array from arraywriter

  finite_range()

    Return (maybe cached) finite range of data array

  property has_nan

    True if array has NaNs

  property out_dtype

    Return out_dtype from arraywriter

  scaling_needed()

    Checks if scaling is needed for input array

    Raises WriterError if no scaling possible.

    The rules are in the code, but:

    - If numpy will cast, return False (no scaling needed)

    - If input or output is an object or structured type, raise

    - If input is complex, raise

    - If the output is float, return False

    - If the input array is all zero, return False

    - By now we are casting to (u)int. If the input type is a float, return True (we do need scaling)

    - Now input and output types are (u)ints. If the min and max in the data are within range of the output type, return False

    - Otherwise return True

  to_fileobj(fileobj, order='F')

    Write array into fileobj

    Parameters:
      fileobj file-like object
      order{‘F’, ‘C’}

        order (Fortran or C) to which to write array

## `ScalingError`

class nibabel.arraywriters.ScalingError

  Bases: `WriterError`

  __init__(*args, **kwargs)

## `SlopeArrayWriter`

class nibabel.arraywriters.SlopeArrayWriter(array, out_dtype=None, calc_scale=True, scaler_dtype=<class 'numpy.float32'>, **kwargs)

  Bases: `ArrayWriter`

  ArrayWriter that can use scalefactor for writing arrays

  The scalefactor allows the array writer to write floats to int output types, and rescale larger ints to smaller. It can therefore lose precision.

  It extends the ArrayWriter class with attribute:

  - slope

  and methods:

  - reset() - reset slope to default (not adapted to self.array)

  - calc_scale() - calculate slope to best write self.array

  Initialize array writer

  Parameters:
    array array-like

      array-like object

    out_dtype None or dtype

      dtype with which array will be written. For this class, out_dtype` needs to be the same as the dtype of the input array or a swapped version of the same.

    calc_scale{True, False}, optional

      Whether to calculate scaling for writing array on initialization. If False, then you can calculate this scaling with `obj.calc_scale()` - see examples

    scaler_dtype dtype-like, optional

      specifier for numpy dtype for scaling

    **kwargs keyword arguments

      This class processes only:

      - nan2zero : bool, optional Whether to set NaN values to 0 when writing integer output. Defaults to True. If False, NaNs get converted with numpy `astype`, and the behavior is undefined. Ignored for floating point output.

  Examples

      >>> arr = np.array([0, 254], np.uint8)
      >>> aw = SlopeArrayWriter(arr)
      >>> aw.slope
      1.0
      >>> aw = SlopeArrayWriter(arr, np.int8)
      >>> aw.slope
      2.0
      >>> aw = SlopeArrayWriter(arr, np.int8, calc_scale=False)
      >>> aw.slope
      1.0
      >>> aw.calc_scale()
      >>> aw.slope
      2.0

  __init__(array, out_dtype=None, calc_scale=True, scaler_dtype=<class 'numpy.float32'>, **kwargs)

    Initialize array writer

    Parameters:
      array array-like

        array-like object

      out_dtype None or dtype

        dtype with which array will be written. For this class, out_dtype` needs to be the same as the dtype of the input array or a swapped version of the same.

      calc_scale{True, False}, optional

        Whether to calculate scaling for writing array on initialization. If False, then you can calculate this scaling with `obj.calc_scale()` - see examples

      scaler_dtype dtype-like, optional

        specifier for numpy dtype for scaling

      **kwargs keyword arguments

        This class processes only:

        - nan2zero : bool, optional Whether to set NaN values to 0 when writing integer output. Defaults to True. If False, NaNs get converted with numpy `astype`, and the behavior is undefined. Ignored for floating point output.

    Examples

        >>> arr = np.array([0, 254], np.uint8)
        >>> aw = SlopeArrayWriter(arr)
        >>> aw.slope
        1.0
        >>> aw = SlopeArrayWriter(arr, np.int8)
        >>> aw.slope
        2.0
        >>> aw = SlopeArrayWriter(arr, np.int8, calc_scale=False)
        >>> aw.slope
        1.0
        >>> aw.calc_scale()
        >>> aw.slope
        2.0

  calc_scale(force=False)

    Calculate / set scaling for floats/(u)ints to (u)ints

  reset()

    Set object to values before any scaling calculation

  scaling_needed()

    Checks if scaling is needed for input array

    Raises WriterError if no scaling possible.

    The rules are in the code, but:

    - If numpy will cast, return False (no scaling needed)

    - If input or output is an object or structured type, raise

    - If input is complex, raise

    - If the output is float, return False

    - If the input array is all zero, return False

    - If there is no finite value, return False (the writer will strip the non-finite values)

    - By now we are casting to (u)int. If the input type is a float, return True (we do need scaling)

    - Now input and output types are (u)ints. If the min and max in the data are within range of the output type, return False

    - Otherwise return True

  property slope

    get/set slope

  to_fileobj(fileobj, order='F')

    Write array into fileobj

    Parameters:
      fileobj file-like object
      order{‘F’, ‘C’}

        order (Fortran or C) to which to write array

## `SlopeInterArrayWriter`

class nibabel.arraywriters.SlopeInterArrayWriter(array, out_dtype=None, calc_scale=True, scaler_dtype=<class 'numpy.float32'>, **kwargs)

  Bases: `SlopeArrayWriter`

  Array writer that can use slope and intercept to scale array

  The writer can subtract an intercept, and divided by a slope, in order to be able to convert floating point values into a (u)int range, or to convert larger (u)ints to smaller.

  It extends the ArrayWriter class with attributes:

  - inter

  - slope

  and methods:

  - reset() - reset inter, slope to default (not adapted to self.array)

  - calc_scale() - calculate inter, slope to best write self.array

  Initialize array writer

  Parameters:
    array array-like

      array-like object

    out_dtype None or dtype

      dtype with which array will be written. For this class, out_dtype` needs to be the same as the dtype of the input array or a swapped version of the same.

    calc_scale{True, False}, optional

      Whether to calculate scaling for writing array on initialization. If False, then you can calculate this scaling with `obj.calc_scale()` - see examples

    scaler_dtype dtype-like, optional

      specifier for numpy dtype for slope, intercept

    **kwargs keyword arguments

      This class processes only:

      - nan2zero : bool, optional Whether to set NaN values to 0 when writing integer output. Defaults to True. If False, NaNs get converted with numpy `astype`, and the behavior is undefined. Ignored for floating point output.

  Examples

      >>> arr = np.array([0, 255], np.uint8)
      >>> aw = SlopeInterArrayWriter(arr)
      >>> aw.slope, aw.inter
      (1.0, 0.0)
      >>> aw = SlopeInterArrayWriter(arr, np.int8)
      >>> (aw.slope, aw.inter) == (1.0, 128)
      True
      >>> aw = SlopeInterArrayWriter(arr, np.int8, calc_scale=False)
      >>> aw.slope, aw.inter
      (1.0, 0.0)
      >>> aw.calc_scale()
      >>> (aw.slope, aw.inter) == (1.0, 128)
      True

  __init__(array, out_dtype=None, calc_scale=True, scaler_dtype=<class 'numpy.float32'>, **kwargs)

    Initialize array writer

    Parameters:
      array array-like

        array-like object

      out_dtype None or dtype

        dtype with which array will be written. For this class, out_dtype` needs to be the same as the dtype of the input array or a swapped version of the same.

      calc_scale{True, False}, optional

        Whether to calculate scaling for writing array on initialization. If False, then you can calculate this scaling with `obj.calc_scale()` - see examples

      scaler_dtype dtype-like, optional

        specifier for numpy dtype for slope, intercept

      **kwargs keyword arguments

        This class processes only:

        - nan2zero : bool, optional Whether to set NaN values to 0 when writing integer output. Defaults to True. If False, NaNs get converted with numpy `astype`, and the behavior is undefined. Ignored for floating point output.

    Examples

        >>> arr = np.array([0, 255], np.uint8)
        >>> aw = SlopeInterArrayWriter(arr)
        >>> aw.slope, aw.inter
        (1.0, 0.0)
        >>> aw = SlopeInterArrayWriter(arr, np.int8)
        >>> (aw.slope, aw.inter) == (1.0, 128)
        True
        >>> aw = SlopeInterArrayWriter(arr, np.int8, calc_scale=False)
        >>> aw.slope, aw.inter
        (1.0, 0.0)
        >>> aw.calc_scale()
        >>> (aw.slope, aw.inter) == (1.0, 128)
        True

  property inter

    get/set inter

  reset()

    Set object to values before any scaling calculation

  to_fileobj(fileobj, order='F')

    Write array into fileobj

    Parameters:
      fileobj file-like object
      order{‘F’, ‘C’}

        order (Fortran or C) to which to write array

## `WriterError`

class nibabel.arraywriters.WriterError

  Bases: `Exception`

  __init__(*args, **kwargs)

## get_slope_inter

nibabel.arraywriters.get_slope_inter(writer)

  Return slope, intercept from array writer object

  Parameters:
    writer ArrayWriter instance
  Returns:
    slope scalar

      slope in writer or 1.0 if not present

    inter scalar

      intercept in writer or 0.0 if not present

  Examples

      >>> arr = np.arange(10)
      >>> get_slope_inter(ArrayWriter(arr))
      (1.0, 0.0)
      >>> get_slope_inter(SlopeArrayWriter(arr))
      (1.0, 0.0)
      >>> get_slope_inter(SlopeInterArrayWriter(arr))
      (1.0, 0.0)

## make_array_writer

nibabel.arraywriters.make_array_writer(data, out_type, has_slope=True, has_intercept=True, **kwargs)

  Make array writer instance for array data and output type out_type

  Parameters:
    data array-like

      array for which to create array writer

    out_type dtype-like

      input to numpy dtype to specify array writer output type

    has_slope{True, False}

      If True, array write can use scaling to adapt the array to out_type

    has_intercept{True, False}

      If True, array write can use intercept to adapt the array to out_type

    **kwargs other keyword arguments

      to pass to the arraywriter class

  Returns:
    writer arraywriter instance

      Instance of array writer, with class adapted to has_intercept and has_slope.

  Examples

      >>> aw = make_array_writer(np.arange(10), np.uint8, True, True)
      >>> type(aw) == SlopeInterArrayWriter
      True
      >>> aw = make_array_writer(np.arange(10), np.uint8, True, False)
      >>> type(aw) == SlopeArrayWriter
      True
      >>> aw = make_array_writer(np.arange(10), np.uint8, False, False)
      >>> type(aw) == ArrayWriter
      True