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.
|
Initialize array writer |
|
ArrayWriter that can use scalefactor for writing arrays |
|
Array writer that can use slope and intercept to scale array |
|
Return slope, intercept from array writer object |
|
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
¶
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