Merge pull request #203 from matthew-brett/proxy-validators

MRG: array proxy API validation; proxy refactor

Add ArrayProxy API validation. Extends tests a little for array proxies,
prepares for extending the API for array proxies.

Refactor ArrayProxy to copy out fields it needs from the header, but deprecate
the header copy (it can be large), so we can just keep the fields from the
header that we need.

Author: matthew-brett

nibabel/analyze.py

@@ -25,6 +25,7 @@
     .get/set_data_shape
     .get/set_data_dtype
     .get/set_zooms
+    .get/set_data_offset
     .get_base_affine()
     .get_best_affine()
     .data_to_fileobj
@@ -682,6 +683,11 @@ def set_zooms(self, zooms):
     def as_analyze_map(self):
         return self
 
+    def set_data_offset(self, offset):
+        """ Set offset into data file to read data
+        """
+        self._structarr['vox_offset'] = offset
+
     def get_data_offset(self):
         ''' Return offset into data file to read data
 

nibabel/arrayproxy.py

@@ -10,15 +10,19 @@
 
 The API is - at minimum:
 
-* The object has an attribute ``shape``
-* that the object returns the data array from ``np.asarray(obj)``
+* The object has a read-only attribute ``shape``
+* read only ``is_proxy`` attribute / property
+* the object returns the data array from ``np.asarray(obj)``
 * that modifying no object outside ``obj`` will affect the result of
-  ``np.asarray(obj)``.  Specifically, if you pass a header into the the
-  __init__, then modifying the original header will not affect the result of the
-  array return.
+  ``np.asarray(obj)``.  Specifically:
+  * Changes in position (``obj.tell()``) of passed file-like objects will
+    not affect the output of from ``np.asarray(proxy)``.
+  * if you pass a header into the __init__, then modifying the original
+    header will not affect the result of the array return.
 """
+import warnings
 
-from .volumeutils import BinOpener
+from .volumeutils import BinOpener, array_from_file, apply_read_scaling
 
 
 class ArrayProxy(object):
@@ -30,24 +34,62 @@ class ArrayProxy(object):
     variants, including Nifti1, and with the MGH format, apparently.
 
     It requires a ``header`` object with methods:
-    * copy
     * get_data_shape
-    * data_from_fileobj
+    * get_data_dtype
+    * get_data_offset
+    * get_slope_inter
+
+    The header should also have a 'copy' method.  This requirement will go away
+    when the deprecated 'header' propoerty goes away.
 
     Other image types might need to implement their own implementation of this
     API.  See :mod:`minc` for an example.
     """
     def __init__(self, file_like, header):
         self.file_like = file_like
-        self.header = header.copy()
+        # Copies of values needed to read array
         self._shape = header.get_data_shape()
+        self._dtype = header.get_data_dtype()
+        self._offset = header.get_data_offset()
+        self._slope, self._inter = header.get_slope_inter()
+        self._slope = 1.0 if self._slope is None else self._slope
+        self._inter = 0.0 if self._inter is None else self._inter
+        # Reference to original header; we will remove this soon
+        self._header = header.copy()
+
+    @property
+    def header(self):
+        warnings.warn('We will remove the header property from proxies soon',
+                      FutureWarning,
+                      stacklevel=2)
+        return self._header
 
     @property
     def shape(self):
         return self._shape
 
+    @property
+    def is_proxy(self):
+        return True
+
+    @property
+    def slope(self):
+        return self._slope
+
+    @property
+    def inter(self):
+        return self._inter
+
+    @property
+    def offset(self):
+        return self._offset
+
     def __array__(self):
         ''' Read of data from file '''
         with BinOpener(self.file_like) as fileobj:
-            data = self.header.data_from_fileobj(fileobj)
-        return data
+            raw_data = array_from_file(self._shape,
+                                       self._dtype,
+                                       fileobj,
+                                       self._offset)
+        # Upcast as necessary for big slopes, intercepts
+        return apply_read_scaling(raw_data, self._slope, self._inter)

nibabel/ecat.py

@@ -660,7 +660,15 @@ def __init__(self, subheader):
         self._data = None
         x, y, z = subheader.get_shape()
         nframes = subheader.get_nframes()
-        self.shape = (x, y, z, nframes)
+        self._shape = (x, y, z, nframes)
+
+    @property
+    def shape(self):
+        return self._shape
+
+    @property
+    def is_proxy(self):
+        return True
 
     def __array__(self):
         ''' Read of data from file

nibabel/minc1.py

@@ -204,7 +204,15 @@ class MincImageArrayProxy(object):
     '''
     def __init__(self, minc_file):
         self.minc_file = minc_file
-        self.shape = minc_file.get_data_shape()
+        self._shape = minc_file.get_data_shape()
+
+    @property
+    def shape(self):
+        return self._shape
+
+    @property
+    def is_proxy(self):
+        return True
 
     def __array__(self):
         ''' Read of data from file '''

nibabel/tests/test_analyze.py

@@ -337,6 +337,13 @@ def test_datatype(self):
             ehdr.set_data_dtype(dt)
             assert_true(ehdr['datatype'] == code)
 
+    def test_offset(self):
+        # Test get / set offset
+        hdr = self.header_class()
+        offset = hdr.get_data_offset()
+        hdr.set_data_offset(offset + 16)
+        assert_equal(hdr.get_data_offset(), offset + 16)
+
     def test_data_shape_zooms_affine(self):
         hdr = self.header_class()
         for shape in ((1,2,3),(0,),(1,),(1,2),(1,2,3,4)):

nibabel/tests/test_arrayproxy.py

@@ -10,6 +10,8 @@
 """
 from __future__ import division, print_function, absolute_import
 
+import warnings
+
 from ..externals.six import BytesIO
 from ..tmpdirs import InTemporaryDirectory
 
@@ -27,32 +29,43 @@ class FunkyHeader(object):
     def __init__(self, shape):
         self.shape = shape
 
-    def copy(self):
-        return self.__class__(self.shape[:])
-
     def get_data_shape(self):
         return self.shape[:]
 
-    def data_from_fileobj(self, fileobj):
-        return np.arange(np.prod(self.shape)).reshape(self.shape)
+    def get_data_dtype(self):
+        return np.int32
+
+    def get_data_offset(self):
+        return 16
+
+    def get_slope_inter(self):
+        return 1.0, 0.0
+
+    def copy(self):
+        # Not needed when we remove header property
+        return FunkyHeader(self.shape)
 
 
 def test_init():
     bio = BytesIO()
     shape = [2,3,4]
+    dtype = np.int32
+    arr = np.arange(24, dtype=dtype).reshape(shape)
+    bio.seek(16)
+    bio.write(arr.tostring(order='F'))
     hdr = FunkyHeader(shape)
     ap = ArrayProxy(bio, hdr)
     assert_true(ap.file_like is bio)
     assert_equal(ap.shape, shape)
     # shape should be read only
     assert_raises(AttributeError, setattr, ap, 'shape', shape)
-    # Check there has been a copy of the header
-    assert_false(ap.header is hdr)
+    # Get the data
+    assert_array_equal(np.asarray(ap), arr)
     # Check we can modify the original header without changing the ap version
     hdr.shape[0] = 6
     assert_not_equal(ap.shape, shape)
-    # Get the data
-    assert_array_equal(np.asarray(ap), np.arange(24).reshape((2,3,4)))
+    # Data stays the same, also
+    assert_array_equal(np.asarray(ap), arr)
 
 
 def write_raw_data(arr, hdr, fileobj):
@@ -73,7 +86,9 @@ def test_nifti1_init():
     assert_true(ap.file_like == bio)
     assert_equal(ap.shape, shape)
     # Check there has been a copy of the header
-    assert_false(ap.header is hdr)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        assert_false(ap.header is hdr)
     # Get the data
     assert_array_equal(np.asarray(ap), arr * 2.0 + 10)
     with InTemporaryDirectory():

nibabel/tests/test_helpers.py

@@ -14,7 +14,7 @@ def bytesio_filemap(klass):
 
 
 def bytesio_round_trip(img):
-    """ Save then load from bytesio
+    """ Save then load image from bytesio
     """
     klass = img.__class__
     bytes_map = bytesio_filemap(klass)

nibabel/tests/test_minc2.py

@@ -22,7 +22,7 @@
 
 
 if have_h5py:
-    class TestMinc1File(tm2._TestMincFile):
+    class TestMinc2File(tm2._TestMincFile):
         module = minc2
         file_class = Minc2File
         opener = h5py.File