ENH: Define Cifti2 Axes describing the rows/columns of the Cifti2 data

.travis.yml

@@ -33,11 +33,11 @@ matrix:
     # Absolute minimum dependencies
     - python: 2.7
       env:
-        - DEPENDS="numpy==1.7.1"
+        - DEPENDS="numpy==1.8"
     # Absolute minimum dependencies
     - python: 2.7
       env:
-        - DEPENDS="numpy==1.7.1"
+        - DEPENDS="numpy==1.8"
         - CHECK_TYPE="import"
     # Absolute minimum dependencies plus oldest MPL
     # Check these against:
@@ -46,11 +46,11 @@ matrix:
     # requirements.txt
     - python: 2.7
       env:
-        - DEPENDS="numpy==1.7.1 matplotlib==1.3.1"
+        - DEPENDS="numpy==1.8 matplotlib==1.3.1"
     # Minimum pydicom dependency
     - python: 2.7
       env:
-        - DEPENDS="numpy==1.7.1 pydicom==0.9.9 pillow==2.6"
+        - DEPENDS="numpy==1.8 pydicom==0.9.9 pillow==2.6"
     # pydicom master branch
     - python: 3.5
       env:

doc/source/api.rst

@@ -23,6 +23,7 @@ File Formats
    analyze
    spm2analyze
    spm99analyze
+   cifti2
    gifti
    freesurfer
    minc1

doc/source/installation.rst

@@ -87,7 +87,7 @@ Requirements
     .travis.yml
 
 *  Python_ 2.7, or >= 3.4
-*  NumPy_ 1.7.1 or greater
+*  NumPy_ 1.8 or greater
 *  Six_ 1.3 or greater
 *  SciPy_ (optional, for full SPM-ANALYZE support)
 *  PyDICOM_ 0.9.9 or greater (optional, for DICOM support)

nibabel/cifti2/__init__.py

@@ -6,14 +6,15 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-"""CIfTI format IO
+"""CIfTI2 format IO
 
 .. currentmodule:: nibabel.cifti2
 
 .. autosummary::
    :toctree: ../generated
 
    cifti2
+   cifti2_axes
 """
 
 from .parse_cifti2 import Cifti2Extension
@@ -25,3 +26,4 @@
                      Cifti2TransformationMatrixVoxelIndicesIJKtoXYZ,
                      Cifti2Vertices, Cifti2Volume, CIFTI_BRAIN_STRUCTURES,
                      Cifti2HeaderError, CIFTI_MODEL_TYPES, load, save)
+from .cifti2_axes import (Axis, BrainModel, Parcels, Series, Label, Scalar)

nibabel/cifti2/cifti2.py

@@ -12,12 +12,9 @@
 
     http://www.nitrc.org/forum/message.php?msg_id=3738
 
-Definition of the CIFTI2 header format and file extensions attached to this
-email:
+Definition of the CIFTI2 header format and file extensions can be found at:
 
-    http://www.nitrc.org/forum/forum.php?thread_id=4380&forum_id=1955
-
-Filename is ``CIFTI-2_Main_FINAL_1March2014.pdf``.
+    http://www.nitrc.org/projects/cifti
 '''
 from __future__ import division, print_function, absolute_import
 import re
@@ -1268,6 +1265,40 @@ def get_index_map(self, index):
         '''
         return self.matrix.get_index_map(index)
 
+    def get_axis(self, index):
+        '''
+        Generates the Cifti2 axis for a given dimension
+
+        Parameters
+        ----------
+        index : int
+            Dimension for which we want to obtain the mapping.
+
+        Returns
+        -------
+        axis : cifti2_axes.Axis
+        '''
+        from . import cifti2_axes
+        return cifti2_axes.from_index_mapping(self.matrix.get_index_map(index))
+
+    @classmethod
+    def from_axes(cls, axes):
+        '''
+        Creates a new Cifti2 header based on the Cifti2 axes
+
+        Parameters
+        ----------
+        axes : Tuple[cifti2_axes.Axis]
+            sequence of Cifti2 axes describing each row/column of the matrix to be stored
+
+        Returns
+        -------
+        header : Cifti2Header
+            new header describing the rows/columns in a format consistent with Cifti2
+        '''
+        from . import cifti2_axes
+        return cifti2_axes.to_header(axes)
+
 
 class Cifti2Image(DataobjImage):
     """ Class for single file CIFTI2 format image
@@ -1297,15 +1328,19 @@ def __init__(self,
             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 : Cifti2Header instance or Sequence[cifti2_axes.Axis]
             Header with data for / from XML part of CIFTI2 format.
+            Alternatively a sequence of cifti2_axes.Axis objects can be provided
+            describing each dimension of the array.
         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.
         '''
+        if not isinstance(header, Cifti2Header) and header:
+            header = Cifti2Header.from_axes(header)
         super(Cifti2Image, self).__init__(dataobj, header=header,
                                           extra=extra, file_map=file_map)
         self._nifti_header = Nifti2Header.from_header(nifti_header)