arrayproxy
¶
Array proxy base class
The proxy API is - at minimum:
The object has a read-only attribute
shape
read only
is_proxy
attribute / property set to Truethe object returns the data array from
np.asarray(prox)
returns array slice from
prox[<slice_spec>]
where<slice_spec>
is any ndarray slice specification that does not use numpy ‘advanced indexing’.modifying no object outside
obj
will affect the result ofnp.asarray(obj)
. Specifically:Changes in position (
obj.tell()
) of passed file-like objects will not affect the output of fromnp.asarray(proxy)
.if you pass a header into the __init__, then modifying the original header will not affect the result of the array return.
See nibabel.tests.test_proxy_api
for proxy API conformance checks.
|
Protocol for numpy ndarray-like objects |
|
Class to act as proxy for the array that can be read from a file |
|
Get the effective dtype of an array-like object |
|
Return True if obj is an array proxy |
|
Use obj reshape method if possible, else numpy reshape function |
ArrayLike
¶
ArrayProxy
¶
- class nibabel.arrayproxy.ArrayProxy(file_like, spec, *, mmap=True, order=None, keep_file_open=None)¶
Bases:
ArrayLike
Class to act as proxy for the array that can be read from a file
The array proxy allows us to freeze the passed fileobj and header such that it returns the expected data array.
This implementation assumes a contiguous array in the file object, with one of the numpy dtypes, starting at a given file position
offset
with singleslope
andintercept
scaling to produce output values.The class
__init__
requires a spec which defines how the data will be read and rescaled. The spec may be a tuple of length 2 - 5, containing the shape, storage dtype, offset, slope and intercept, or aheader
object with methods:get_data_shape
get_data_dtype
get_data_offset
get_slope_inter
A header should also have a ‘copy’ method. This requirement will go away when the deprecated ‘header’ property goes away.
This implementation allows us to deal with Analyze and its variants, including Nifti1, and with the MGH format.
Other image types might need more specific classes to implement the API. See
nibabel.minc1
,nibabel.ecat
andnibabel.parrec
for examples.Initialize array proxy instance
- Parameters:
- file_likeobject
File-like object or filename. If file-like object, should implement at least
read
andseek
.- specobject or tuple
Tuple must have length 2-5, with the following values:
shape: tuple - tuple of ints describing shape of data;
storage_dtype: dtype specifier - dtype of array inside proxied file, or input to
numpy.dtype
to specify array dtype;offset: int - offset, in bytes, of data array from start of file (default: 0);
slope: float - scaling factor for resulting data (default: 1.0);
inter: float - intercept for rescaled data (default: 0.0).
OR
Header object implementing
get_data_shape
,get_data_dtype
,get_data_offset
,get_slope_inter
- mmap{True, False, ‘c’, ‘r’}, optional, keyword only
mmap controls the use of numpy memory mapping for reading data. If False, do not try numpy
memmap
for data array. If one of {‘c’, ‘r’}, try numpy memmap withmode=mmap
. A mmap value of True gives the same behavior asmmap='c'
. If file_like cannot be memory-mapped, ignore mmap value and read array from file.- order{None, ‘F’, ‘C’}, optional, keyword only
order controls the order of the data array layout. Fortran-style, column-major order may be indicated with ‘F’, and C-style, row-major order may be indicated with ‘C’. None gives the default order, that comes from the _default_order class variable.
- keep_file_open{ None, True, False }, optional, keyword only
keep_file_open controls whether a new file handle is created every time the image is accessed, or a single file handle is created and used for the lifetime of this
ArrayProxy
. IfTrue
, a single file handle is created and used. IfFalse
, a new file handle is created every time the image is accessed. Iffile_like
is an open file handle, this setting has no effect. The default value (None
) will result in the value ofKEEP_FILE_OPEN_DEFAULT
being used.
- __init__(file_like, spec, *, mmap=True, order=None, keep_file_open=None)¶
Initialize array proxy instance
- Parameters:
- file_likeobject
File-like object or filename. If file-like object, should implement at least
read
andseek
.- specobject or tuple
Tuple must have length 2-5, with the following values:
shape: tuple - tuple of ints describing shape of data;
storage_dtype: dtype specifier - dtype of array inside proxied file, or input to
numpy.dtype
to specify array dtype;offset: int - offset, in bytes, of data array from start of file (default: 0);
slope: float - scaling factor for resulting data (default: 1.0);
inter: float - intercept for rescaled data (default: 0.0).
OR
Header object implementing
get_data_shape
,get_data_dtype
,get_data_offset
,get_slope_inter
- mmap{True, False, ‘c’, ‘r’}, optional, keyword only
mmap controls the use of numpy memory mapping for reading data. If False, do not try numpy
memmap
for data array. If one of {‘c’, ‘r’}, try numpy memmap withmode=mmap
. A mmap value of True gives the same behavior asmmap='c'
. If file_like cannot be memory-mapped, ignore mmap value and read array from file.- order{None, ‘F’, ‘C’}, optional, keyword only
order controls the order of the data array layout. Fortran-style, column-major order may be indicated with ‘F’, and C-style, row-major order may be indicated with ‘C’. None gives the default order, that comes from the _default_order class variable.
- keep_file_open{ None, True, False }, optional, keyword only
keep_file_open controls whether a new file handle is created every time the image is accessed, or a single file handle is created and used for the lifetime of this
ArrayProxy
. IfTrue
, a single file handle is created and used. IfFalse
, a new file handle is created every time the image is accessed. Iffile_like
is an open file handle, this setting has no effect. The default value (None
) will result in the value ofKEEP_FILE_OPEN_DEFAULT
being used.
- property dtype¶
- get_unscaled()¶
Read data from file
This is an optional part of the proxy API
- property inter¶
- property is_proxy¶
- property ndim¶
- property offset¶
- reshape(shape)¶
Return an ArrayProxy with a new shape, without modifying data
- property shape¶
- property slope¶
get_obj_dtype¶
- nibabel.arrayproxy.get_obj_dtype(obj)¶
Get the effective dtype of an array-like object
is_proxy¶
- nibabel.arrayproxy.is_proxy(obj)¶
Return True if obj is an array proxy
reshape_dataobj¶
- nibabel.arrayproxy.reshape_dataobj(obj, shape)¶
Use obj reshape method if possible, else numpy reshape function