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:
arrayarray-like

array-like object

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

**kwargskeyword 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:
arrayarray-like

array-like object

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

**kwargskeyword 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:
fileobjfile-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:
arrayarray-like

array-like object

out_dtypeNone 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_dtypedtype-like, optional

specifier for numpy dtype for scaling

**kwargskeyword 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:
arrayarray-like

array-like object

out_dtypeNone 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_dtypedtype-like, optional

specifier for numpy dtype for scaling

**kwargskeyword 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:
fileobjfile-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:
arrayarray-like

array-like object

out_dtypeNone 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_dtypedtype-like, optional

specifier for numpy dtype for slope, intercept

**kwargskeyword 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:
arrayarray-like

array-like object

out_dtypeNone 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_dtypedtype-like, optional

specifier for numpy dtype for slope, intercept

**kwargskeyword 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:
fileobjfile-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:
writerArrayWriter instance
Returns:
slopescalar

slope in writer or 1.0 if not present

interscalar

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:
dataarray-like

array for which to create array writer

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

**kwargsother keyword arguments

to pass to the arraywriter class

Returns:
writerarraywriter 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