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)
- nan2zero : bool, optional
Whether to set NaN values to 0 when writing integer output.
Defaults to True. If False, NaNs get converted with numpy
-
array
¶ Return array from arraywriter
-
finite_range
()¶ Return (maybe cached) finite range of data array
-
has_nan
¶ True if array has NaNs
-
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', nan2zero=None)¶ Write array into fileobj
Parameters: fileobj : file-like object
order : {‘F’, ‘C’}
order (Fortran or C) to which to write array
nan2zero : {None, True, False}, optional, deprecated
Deprecated version of argument to __init__ with same name
- nan2zero : bool, optional
Whether to set NaN values to 0 when writing integer output.
Defaults to True. If False, NaNs get converted with numpy
ScalingError
¶
-
class
nibabel.arraywriters.
ScalingError
¶ Bases:
nibabel.arraywriters.WriterError
-
__init__
()¶ x.__init__(...) initializes x; see help(type(x)) for signature
-
SlopeArrayWriter
¶
-
class
nibabel.arraywriters.
SlopeArrayWriter
(array, out_dtype=None, calc_scale=True, scaler_dtype=<type 'numpy.float32'>, **kwargs)¶ Bases:
nibabel.arraywriters.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 examplesscaler_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=<type '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 examplesscaler_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
- nan2zero : bool, optional
Whether to set NaN values to 0 when writing integer output.
Defaults to True. If False, NaNs get converted with numpy
-
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
-
slope
¶ get/set slope
-
to_fileobj
(fileobj, order='F', nan2zero=None)¶ Write array into fileobj
Parameters: fileobj : file-like object
order : {‘F’, ‘C’}
order (Fortran or C) to which to write array
nan2zero : {None, True, False}, optional, deprecated
Deprecated version of argument to __init__ with same name
SlopeInterArrayWriter
¶
-
class
nibabel.arraywriters.
SlopeInterArrayWriter
(array, out_dtype=None, calc_scale=True, scaler_dtype=<type 'numpy.float32'>, **kwargs)¶ Bases:
nibabel.arraywriters.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 examplesscaler_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=<type '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 examplesscaler_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
- nan2zero : bool, optional
Whether to set NaN values to 0 when writing integer output.
Defaults to True. If False, NaNs get converted with numpy
-
inter
¶ get/set inter
-
reset
()¶ Set object to values before any scaling calculation
-
to_fileobj
(fileobj, order='F', nan2zero=None)¶ Write array into fileobj
Parameters: fileobj : file-like object
order : {‘F’, ‘C’}
order (Fortran or C) to which to write array
nan2zero : {None, True, False}, optional, deprecated
Deprecated version of argument to __init__ with same name
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