Update docstring and addressed @matthew-brett's last comments

MarcCote · MarcCote · commit bac044b13e89 · 2017-04-07T18:28:20.000-04:00
diff --git a/nibabel/streamlines/tck.py b/nibabel/streamlines/tck.py
@@ -23,35 +23,28 @@
 MEGABYTE = 1024 * 1024
 
 
-def create_empty_header():
-    ''' Return an empty compliant TCK header. '''
-    header = {}
-
-    # Default values
-    header[Field.MAGIC_NUMBER] = TckFile.MAGIC_NUMBER
-    header[Field.NB_STREAMLINES] = 0
-    header['datatype'] = "Float32LE"
-    return header
-
-
 class TckFile(TractogramFile):
     """ Convenience class to encapsulate TCK file format.
 
     Notes
     -----
-    MRtrix (so its file format: TCK) considers the streamline coordinate
-    (0,0,0) to be in the center of the voxel which is also the case for
-    NiBabel's streamlines internal representation.
-
-    Moreover, streamlines coordinates coming from a TCK file are considered
+    MRtrix (so its file format: TCK) considers streamlines coordinates
     to be in world space (RAS+ and mm space). MRtrix refers to that space
     as the "real" or "scanner" space [1]_.
 
+    Moreover, when streamlines are mapped back to voxel space [2]_, a
+    streamline point located at an integer coordinate (i,j,k) is considered
+    to be at the center of the corresponding voxel. This is in contrast with
+    TRK's internal convention where it would have referred to a corner.
+
+    NiBabel's streamlines internal representation follows the same
+    convention as MRtrix.
+
     References
     ----------
     [1] http://www.nitrc.org/pipermail/mrtrix-discussion/2014-January/000859.html
+    [2] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
     """
-
     # Constants
     MAGIC_NUMBER = "mrtrix tracks"
     SUPPORTS_DATA_PER_POINT = False  # Not yet
@@ -72,12 +65,15 @@ def __init__(self, tractogram, header=None):
 
         Notes
         -----
-        Streamlines of the tractogram are assumed to be in *RAS+*
-        and *mm* space where coordinate (0,0,0) refers to the center
-        of the voxel.
+        Streamlines of the tractogram are assumed to be in *RAS+* and *mm*
+        space. It is also assumed that when streamlines are mapped back to
+        voxel space, a streamline point located at an integer coordinate
+        (i,j,k) is considered to be at the center of the corresponding voxel.
+        This is in contrast with TRK's internal convention where it would
+        have referred to a corner.
         """
         if header is None:
-            header = create_empty_header()
+            header = self.create_empty_header()
 
         super(TckFile, self).__init__(tractogram, header)
 
@@ -105,6 +101,17 @@ def is_correct_format(cls, fileobj):
 
         return magic_number.strip() == cls.MAGIC_NUMBER
 
+    @classmethod
+    def create_empty_header(cls):
+        """ Return an empty compliant TCK header. """
+        header = {}
+
+        # Default values
+        header[Field.MAGIC_NUMBER] = cls.MAGIC_NUMBER
+        header[Field.NB_STREAMLINES] = 0
+        header['datatype'] = "Float32LE"
+        return header
+
     @classmethod
     def load(cls, fileobj, lazy_load=False):
         """ Loads streamlines from a filename or file-like object.
@@ -128,9 +135,12 @@ def load(cls, fileobj, lazy_load=False):
 
         Notes
         -----
-        Streamlines of the tractogram are assumed to be in *RAS+*
-        and *mm* space where coordinate (0,0,0) refers to the center
-        of the voxel.
+        Streamlines of the tractogram are assumed to be in *RAS+* and *mm*
+        space. It is also assumed that when streamlines are mapped back to
+        voxel space, a streamline point located at an integer coordinate
+        (i,j,k) is considered to be at the center of the corresponding voxel.
+        This is in contrast with TRK's internal convention where it would
+        have referred to a corner.
         """
         hdr = cls._read_header(fileobj)
 
@@ -169,7 +179,7 @@ def save(self, fileobj):
         """
         # Enforce float32 in little-endian byte order for data.
         dtype = np.dtype('<f4')
-        header = create_empty_header()
+        header = self.create_empty_header()
 
         # Override hdr's fields by those contained in `header`.
         header.update(self.header)
@@ -437,13 +447,13 @@ def _read(cls, fileobj, header, buffer_size=4):
             f.seek(start_position, os.SEEK_CUR)
 
     def __str__(self):
-        ''' Gets a formatted string of the header of a TCK file.
+        """ Gets a formatted string of the header of a TCK file.
 
         Returns
         -------
         info : string
             Header information relevant to the TCK format.
-        '''
+        """
         hdr = self.header
 
         info = ""
diff --git a/nibabel/streamlines/tests/test_tractogram_file.py b/nibabel/streamlines/tests/test_tractogram_file.py
@@ -16,6 +16,10 @@ def is_correct_format(cls, fileobj):
         def load(cls, fileobj, lazy_load=True):
             return None
 
+        @classmethod
+        def create_empty_header(cls):
+            return None
+
     assert_raises(TypeError, DummyTractogramFile, Tractogram())
 
     # Missing 'load' method
@@ -27,12 +31,32 @@ def is_correct_format(cls, fileobj):
         def save(self, fileobj):
             pass
 
+        @classmethod
+        def create_empty_header(cls):
+            return None
+
+    assert_raises(TypeError, DummyTractogramFile, Tractogram())
+
+    # Missing 'create_empty_header' method
+    class DummyTractogramFile(TractogramFile):
+        @classmethod
+        def is_correct_format(cls, fileobj):
+            return False
+
+        @classmethod
+        def load(cls, fileobj, lazy_load=True):
+            return None
+
+        def save(self, fileobj):
+            pass
+
     assert_raises(TypeError, DummyTractogramFile, Tractogram())
 
 
 def test_tractogram_file():
     assert_raises(NotImplementedError, TractogramFile.is_correct_format, "")
     assert_raises(NotImplementedError, TractogramFile.load, "")
+    assert_raises(NotImplementedError, TractogramFile.create_empty_header)
 
     # Testing calling the 'save' method of `TractogramFile` object.
     class DummyTractogramFile(TractogramFile):
@@ -48,6 +72,10 @@ def load(cls, fileobj, lazy_load=True):
         def save(self, fileobj):
             pass
 
+        @classmethod
+        def create_empty_header(cls):
+            return None
+
     assert_raises(NotImplementedError,
                   super(DummyTractogramFile,
                         DummyTractogramFile(Tractogram)).save, "")
diff --git a/nibabel/streamlines/tractogram.py b/nibabel/streamlines/tractogram.py
@@ -261,9 +261,14 @@ class Tractogram(object):
 
     Streamlines of a tractogram can be in any coordinate system of your
     choice as long as you provide the correct `affine_to_rasmm` matrix, at
-    construction time, that brings the streamlines back to *RAS+*, *mm* space,
-    where the coordinates (0,0,0) corresponds to the center of the voxel
-    (as opposed to the corner of the voxel).
+    construction time. When applied to streamlines coordinates, that
+    transformation matrix should bring the streamlines back to world space
+    (RAS+ and mm space) [1]_.
+
+    Moreover, when streamlines are mapped back to voxel space [2]_, a
+    streamline point located at an integer coordinate (i,j,k) is considered
+    to be at the center of the corresponding voxel. This is in contrast with
+    other conventions where it might have referred to a corner.
 
     Attributes
     ----------
@@ -284,6 +289,11 @@ class Tractogram(object):
         ndarrays of shape ($N_t$, $M_i$) where $N_t$ is the number of points
         for a particular streamline $t$ and $M_i$ is the number values to store
         for that particular piece of information $i$.
+
+    References
+    ----------
+    [1] http://nipy.org/nibabel/coordinate_systems.html#naming-reference-spaces
+    [2] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
     """
     def __init__(self, streamlines=None,
                  data_per_streamline=None,
@@ -504,11 +514,16 @@ class LazyTractogram(Tractogram):
     streamlines and their data information. This container is thus memory
     friendly since it doesn't require having all this data loaded in memory.
 
-    Streamlines of a lazy tractogram can be in any coordinate system of your
+    Streamlines of a tractogram can be in any coordinate system of your
     choice as long as you provide the correct `affine_to_rasmm` matrix, at
-    construction time, that brings the streamlines back to *RAS+*, *mm* space,
-    where the coordinates (0,0,0) corresponds to the center of the voxel
-    (as opposed to the corner of the voxel).
+    construction time. When applied to streamlines coordinates, that
+    transformation matrix should bring the streamlines back to world space
+    (RAS+ and mm space) [1]_.
+
+    Moreover, when streamlines are mapped back to voxel space [2]_, a
+    streamline point located at an integer coordinate (i,j,k) is considered
+    to be at the center of the corresponding voxel. This is in contrast with
+    other conventions where it might have referred to a corner.
 
     Attributes
     ----------
@@ -538,6 +553,11 @@ class LazyTractogram(Tractogram):
     LazyTractogram objects are suited for operations that can be linearized
     such as applying an affine transformation or converting streamlines from
     one file format to another.
+
+    References
+    ----------
+    [1] http://nipy.org/nibabel/coordinate_systems.html#naming-reference-spaces
+    [2] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
     """
     def __init__(self, streamlines=None,
                  data_per_streamline=None,
diff --git a/nibabel/streamlines/tractogram_file.py b/nibabel/streamlines/tractogram_file.py
@@ -77,6 +77,11 @@ def is_correct_format(cls, fileobj):
         """
         raise NotImplementedError()
 
+    @abstractclassmethod
+    def create_empty_header(cls):
+        """ Returns an empty header for this streamlines file format. """
+        raise NotImplementedError()
+
     @abstractclassmethod
     def load(cls, fileobj, lazy_load=True):
         """ Loads streamlines from a filename or file-like object.
diff --git a/nibabel/streamlines/trk.py b/nibabel/streamlines/trk.py
@@ -199,22 +199,6 @@ def decode_value_from_name(encoded_name):
     return name, value
 
 
-def create_empty_header():
-    """ Return an empty compliant TRK header. """
-    header = np.zeros(1, dtype=header_2_dtype)
-
-    # Default values
-    header[Field.MAGIC_NUMBER] = TrkFile.MAGIC_NUMBER
-    header[Field.VOXEL_SIZES] = np.array((1, 1, 1), dtype="f4")
-    header[Field.DIMENSIONS] = np.array((1, 1, 1), dtype="h")
-    header[Field.VOXEL_TO_RASMM] = np.eye(4, dtype="f4")
-    header[Field.VOXEL_ORDER] = b"RAS"
-    header['version'] = 2
-    header['hdr_size'] = TrkFile.HEADER_SIZE
-
-    return header
-
-
 class TrkFile(TractogramFile):
     """ Convenience class to encapsulate TRK file format.
 
@@ -252,7 +236,7 @@ def __init__(self, tractogram, header=None):
         of the voxel.
         """
         if header is None:
-            header_rec = create_empty_header()
+            header_rec = self.create_empty_header()
             header = dict(zip(header_rec.dtype.names, header_rec[0]))
 
         super(TrkFile, self).__init__(tractogram, header)
@@ -281,6 +265,22 @@ def is_correct_format(cls, fileobj):
             f.seek(-magic_len, os.SEEK_CUR)
             return magic_number == cls.MAGIC_NUMBER
 
+    @classmethod
+    def create_empty_header(cls):
+        """ Return an empty compliant TRK header. """
+        header = np.zeros(1, dtype=header_2_dtype)
+
+        # Default values
+        header[Field.MAGIC_NUMBER] = cls.MAGIC_NUMBER
+        header[Field.VOXEL_SIZES] = np.array((1, 1, 1), dtype="f4")
+        header[Field.DIMENSIONS] = np.array((1, 1, 1), dtype="h")
+        header[Field.VOXEL_TO_RASMM] = np.eye(4, dtype="f4")
+        header[Field.VOXEL_ORDER] = b"RAS"
+        header['version'] = 2
+        header['hdr_size'] = cls.HEADER_SIZE
+
+        return header
+
     @classmethod
     def load(cls, fileobj, lazy_load=False):
         """ Loads streamlines from a filename or file-like object.
@@ -388,7 +388,7 @@ def save(self, fileobj):
             of the TRK header data).
         """
         # Enforce little-endian byte order for header
-        header = create_empty_header().newbyteorder('<')
+        header = self.create_empty_header().newbyteorder('<')
 
         # Override hdr's fields by those contained in `header`.
         for k, v in self.header.items():
