RF: refactor Cifti2Image API

Refactor Cifti2Image API to use dataobj convention.  This allows the
image to use array proxies, when we have learned to reshape array
proxies, which should not take long.

Make explicit the distinction between `nifti_header` and `extra`.  Add
`file_map` as an input argument.

Author: matthew-brett

nibabel/cifti2/cifti2.py

@@ -21,11 +21,11 @@
 import re
 import collections
 
-import numpy as np
-
 from .. import xmlutils as xml
-from ..filebasedimages import FileBasedHeader, FileBasedImage
-from ..nifti2 import Nifti2Image
+from ..filebasedimages import FileBasedHeader
+from ..dataobj_images import DataobjImage
+from ..nifti2 import Nifti2Image, Nifti2Header
+from ..arrayproxy import reshape_dataobj
 
 
 def _float_01(val):
@@ -939,62 +939,63 @@ def _to_xml_element(self):
             cifti.append(mat_xml)
         return cifti
 
-    @classmethod
-    def from_header(klass, header=None):
-        if header is None:
-            return klass()
-        if type(header) == klass:
-            return header.copy()
-        raise ValueError('header is not a Cifti2Header')
-
     @classmethod
     def may_contain_header(klass, binaryblock):
         from .parse_cifti2 import _Cifti2AsNiftiHeader
         return _Cifti2AsNiftiHeader.may_contain_header(binaryblock)
 
 
-class Cifti2Image(FileBasedImage):
-    """ Class for single file CIfTI2 format image
+class Cifti2Image(DataobjImage):
+    """ Class for single file CIFTI2 format image
     """
     header_class = Cifti2Header
     valid_exts = Nifti2Image.valid_exts
     files_types = Nifti2Image.files_types
     makeable = False
     rw = True
 
-    def __init__(self, data=None, header=None, nifti_header=None):
+    def __init__(self,
+                 dataobj=None,
+                 header=None,
+                 nifti_header=None,
+                 extra=None,
+                 file_map=None):
         ''' Initialize image
 
-        The image is a combination of (array, affine matrix, header, nifti_header),
-        with optional metadata in `extra`, and filename / file-like objects
-        contained in the `file_map` mapping.
+        The image is a combination of (dataobj, header), with optional metadata
+        in `nifti_header` (a NIfTI2 header).  There may be more metadata in the
+        mapping `extra`. Filename / file-like objects can also go in the
+        `file_map` mapping.
 
         Parameters
         ----------
         dataobj : object
-           Object containg image data.  It should be some object that retuns an
-           array from ``np.asanyarray``.  It should have a ``shape`` attribute
-           or property
-        header : Cifti2Header object
-        nifti_header : None or mapping or nifti2 header instance, optional
-           metadata for this image format
+            Object containing image data.  It should be some object that returns
+            an array from ``np.asanyarray``.  It should have a ``shape``
+            attribute or property.
+        header : Cifti2Header instance
+            Header with data for / from XML part of CIFTI2 format.
+        nifti_header : None or mapping or NIfTI2 header instance, optional
+            Metadata for NIfTI2 component of this format.
+        extra : None or mapping
+            Extra metadata not captured by `header` or `nifti_header`.
+        file_map : mapping, optional
+            Mapping giving file information for this image format.
         '''
-        self._header = header if header is not None else Cifti2Header()
-        self.data = data
-        self.extra = nifti_header
-
-    def get_data(self):
-        return self.data
+        super(Cifti2Image, self).__init__(dataobj, header=header,
+                                          extra=extra, file_map=file_map)
+        self._nifti_header = Nifti2Header.from_header(nifti_header)
 
     @property
-    def shape(self):
-        return self.data.shape
+    def nifti_header(self):
+        return self._nifti_header
 
     @classmethod
     def from_file_map(klass, file_map):
         """ Load a Cifti2 image from a file_map
 
         Parameters
+        ----------
         file_map : file_map
 
         Returns
@@ -1011,51 +1012,54 @@ def from_file_map(klass, file_map):
                 cifti_header = item.get_content()
                 break
         else:
-            raise ValueError('Nifti2 header does not contain a CIFTI2 '
+            raise ValueError('NIfTI2 header does not contain a CIFTI2 '
                              'extension')
 
-        # Construct cifti image
-        cifti_img = Cifti2Image(data=nifti_img.dataobj[0, 0, 0, 0],
-                                header=cifti_header,
-                                nifti_header=nifti_img.header)
-        cifti_img.file_map = nifti_img.file_map
-        return cifti_img
+        # Construct cifti image.
+        # User array proxy object where possible
+        dataobj = nifti_img.dataobj
+        return Cifti2Image(reshape_dataobj(dataobj, dataobj.shape[4:]),
+                           header=cifti_header,
+                           nifti_header=nifti_img.header,
+                           file_map=file_map)
 
     @classmethod
     def from_image(klass, img):
         ''' Class method to create new instance of own class from `img`
 
         Parameters
         ----------
-        img : ``spatialimage`` instance
-           In fact, an object with the API of ``FileBasedImage``.
+        img : instance
+            In fact, an object with the API of :class:`DataobjImage`.
 
         Returns
         -------
-        cimg : ``spatialimage`` instance
-           Image, of our own class
+        cimg : instance
+            Image, of our own class
         '''
         if isinstance(img, klass):
             return img
-        else:
-            raise NotImplementedError
+        raise NotImplementedError
 
     def to_file_map(self, file_map=None):
-        """ Save the current image to the specified file_map
+        """ Write image to `file_map` or contained ``self.file_map``
 
         Parameters
         ----------
-        file_map : string
+        file_map : None or mapping, optional
+           files mapping.  If None (default) use object's ``file_map``
+           attribute instead.
 
         Returns
         -------
         None
         """
         from .parse_cifti2 import Cifti2Extension
-        header = self.extra
+        header = self._nifti_header
         extension = Cifti2Extension(content=self.header.to_xml())
         header.extensions.append(extension)
-        data = np.reshape(self.data, (1, 1, 1, 1) + self.data.shape)
+        data = reshape_dataobj(self.dataobj,
+                               (1, 1, 1, 1) + self.dataobj.shape)
         # If qform not set, reset pixdim values so Nifti2 does not complain
         if header['qform_code'] == 0:
             header['pixdim'][:4] = 1

nibabel/cifti2/tests/test_cifti2.py

@@ -10,6 +10,8 @@
 
 from nose.tools import assert_true, assert_equal, assert_raises, assert_is_none
 
+from nibabel.tests.test_dataobj_images import TestDataobjAPI as _TDA
+
 
 def compare_xml_leaf(str1, str2):
     x1 = ElementTree.fromstring(str1)
@@ -107,6 +109,7 @@ def test_cifti2_labeltable():
     assert_raises(ValueError, lt.__setitem__, 0, ('foo', 1.0, -1, 0, 1))
     assert_raises(ValueError, lt.__setitem__, 0, ('foo', 1.0, 0, -0.1, 1))
 
+
 def test_cifti2_label():
     lb = ci.Cifti2Label()
     lb.label = 'Test'

nibabel/cifti2/tests/test_cifti2io.py

@@ -58,10 +58,17 @@ def test_read_internal():
 
 
 @needs_nibabel_data('nitest-cifti2')
-def test_read():
+def test_read_and_proxies():
     img2 = nib.load(DATA_FILE6)
     assert_true(isinstance(img2.header, ci.Cifti2Header))
     assert_equal(img2.shape, (1, 91282))
+    # While we cannot reshape arrayproxies, all images are in-memory
+    assert_true(img2.in_memory)
+    data = img2.get_data()
+    assert_true(data is img2.dataobj)
+    # Uncaching has no effect, images are always array images
+    img2.uncache()
+    assert_true(data is img2.get_data())
 
 
 @needs_nibabel_data('nitest-cifti2')
@@ -95,7 +102,7 @@ def test_readwritedata():
                     else:
                         assert_equal(len(map1.label_table),
                                      len(map2.label_table))
-            assert_array_almost_equal(img.data, img2.data)
+            assert_array_almost_equal(img.dataobj, img2.dataobj)
 
 
 @needs_nibabel_data('nitest-cifti2')
@@ -122,7 +129,7 @@ def test_nibabel_readwritedata():
                     else:
                         assert_equal(len(map1.label_table),
                                      len(map2.label_table))
-            assert_array_almost_equal(img.data, img2.data)
+            assert_array_almost_equal(img.dataobj, img2.dataobj)
 
 
 @needs_nibabel_data('nitest-cifti2')