Neuroimaging in Python — NiBabel 5.4.0.dev1+g3b1c7b37 documentation (original) (raw)

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¶

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 arrayor 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 numpyastype, 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 arrayor 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 numpyastype, 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 arrayor 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 withobj.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 numpyastype, 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 arrayor 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 withobj.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 numpyastype, 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 arrayor 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 withobj.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 numpyastype, 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 arrayor 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 withobj.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 numpyastype, 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 andhas_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