DEP: Deprecate nibabel.trackvis, effect old FutureWarning threats

Author: effigies

nibabel/__init__.py

@@ -76,7 +76,7 @@ def setup_test():
                            flip_axis, OrientationError,
                            apply_orientation, aff2axcodes)
 from .imageclasses import class_map, ext_map, all_image_classes
-from . import trackvis
+trackvis = _ModuleProxy('nibabel.trackvis')
 from . import mriutils
 from . import streamlines
 from . import viewers

nibabel/tests/test_trackvis.py

@@ -10,9 +10,9 @@
 from ..orientations import aff2axcodes
 from ..volumeutils import native_code, swapped_code
 
-from nose.tools import assert_true, assert_false, assert_equal, assert_raises
-from numpy.testing import assert_array_equal, assert_array_almost_equal
-from ..testing import error_warnings, suppress_warnings
+from numpy.testing import assert_array_almost_equal
+from ..testing import (assert_true, assert_false, assert_equal, assert_raises, assert_warns,
+                       assert_array_equal, suppress_warnings)
 
 
 def test_write():
@@ -217,8 +217,7 @@ def _rt(streams, hdr, points_space):
             assert_raises(tv.HeaderError, tv.read, out_f, False, 'voxel')
         # There's a warning for any voxel sizes == 0
         hdr = {'voxel_size': [2, 3, 0]}
-        with error_warnings():
-            assert_raises(UserWarning, _rt, vx_streams, hdr, 'voxel')
+        assert_warns(UserWarning, _rt, vx_streams, hdr, 'voxel')
         # This should be OK
         hdr = {'voxel_size': [2, 3, 4]}
         (raw_streams, hdr), (proc_streams, _) = _rt(vx_streams, hdr, 'voxel')
@@ -305,9 +304,8 @@ def test__check_hdr_points_space():
                   tv._check_hdr_points_space, hdr, 'voxel')
     # Warning here only
     hdr['voxel_size'] = [2, 3, 0]
-    with error_warnings():
-        assert_raises(UserWarning,
-                      tv._check_hdr_points_space, hdr, 'voxel')
+    assert_warns(UserWarning,
+                 tv._check_hdr_points_space, hdr, 'voxel')
     # This is OK
     hdr['voxel_size'] = [2, 3, 4]
     assert_equal(tv._check_hdr_points_space(hdr, 'voxel'), None)
@@ -370,10 +368,6 @@ def test_empty_header():
 def test_get_affine():
     # Test get affine behavior, including pending deprecation
     hdr = tv.empty_header()
-    # Using version 1 affine is not a good idea because is fragile and not
-    # very useful. The default atleast_v2=None mode raises a FutureWarning
-    with error_warnings():
-        assert_raises(FutureWarning, tv.aff_from_hdr, hdr)
     # testing the old behavior
     old_afh = partial(tv.aff_from_hdr, atleast_v2=False)
     # default header gives useless affine
@@ -421,9 +415,8 @@ def test_get_affine():
         assert_equal(hdr['voxel_order'], o_codes)
         # Check it came back the way we wanted
         assert_array_equal(old_afh(hdr), in_aff)
-    # Check that the default case matches atleast_v2=False case
-    with suppress_warnings():
-        assert_array_equal(tv.aff_from_hdr(hdr), flipped_aff)
+    # Check that v1 header raises error
+    assert_raises(tv.HeaderError, tv.aff_from_hdr, hdr)
     # now use the easier vox_to_ras field
     hdr = tv.empty_header()
     aff = np.eye(4)
@@ -455,15 +448,7 @@ def test_aff_to_hdr():
     # Historically we flip the first axis if there is a negative determinant
     assert_array_almost_equal(hdr['voxel_size'], [-1, 2, 3])
     assert_array_almost_equal(tv.aff_from_hdr(hdr, atleast_v2=False), aff2)
-    # Test that default mode raises DeprecationWarning
-    with error_warnings():
-        assert_raises(FutureWarning, tv.aff_to_hdr, affine, hdr)
-        assert_raises(FutureWarning, tv.aff_to_hdr, affine, hdr, None, None)
-        assert_raises(FutureWarning, tv.aff_to_hdr, affine, hdr, False, None)
-        assert_raises(FutureWarning, tv.aff_to_hdr, affine, hdr, None, False)
-    # And has same effect as above
-    with suppress_warnings():
-        tv.aff_to_hdr(affine, hdr)
+    tv.aff_to_hdr(affine, hdr, pos_vox=False, set_order=False)
     assert_array_almost_equal(tv.aff_from_hdr(hdr, atleast_v2=False), affine)
     # Check pos_vox and order flags
     for hdr in ({}, {'version': 2}, {'version': 1}):
@@ -515,13 +500,6 @@ def test_tv_class():
     affine = np.diag([1, 2, 3, 1])
     affine[:3, 3] = [10, 11, 12]
     # affine methods will raise same warnings and errors as function
-    with error_warnings():
-        assert_raises(FutureWarning, tvf.set_affine, affine)
-        assert_raises(FutureWarning, tvf.set_affine, affine, None, None)
-        assert_raises(FutureWarning, tvf.set_affine, affine, False, None)
-        assert_raises(FutureWarning, tvf.set_affine, affine, None, False)
-        assert_raises(FutureWarning, tvf.get_affine)
-        assert_raises(FutureWarning, tvf.get_affine, None)
     tvf.set_affine(affine, pos_vox=True, set_order=True)
     aff = tvf.get_affine(atleast_v2=True)
     assert_array_almost_equal(aff, affine)

nibabel/trackvis.py

@@ -17,12 +17,18 @@
 from .openers import ImageOpener
 from .orientations import aff2axcodes
 from .affines import apply_affine
+from .deprecated import deprecate_with_version
 
 try:
     basestring
 except NameError:  # python 3
     basestring = str
 
+warnings.warn("The trackvis interface has been deprecated and will be removed "
+              "in v4.0; please use the 'nibabel.streamlines' interface.",
+              DeprecationWarning,
+              stacklevel=2)
+
 # Definition of trackvis header structure.
 # See http://www.trackvis.org/docs/?subsect=fileformat
 # See https://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html
@@ -99,6 +105,9 @@ class DataError(Exception):
     """
 
 
+@deprecate_with_version('trackvis.read is deprecated; please use '
+                        'nibabel.streamlines.load, instead.',
+                        since='2.5.0', until='4.0.0')
 def read(fileobj, as_generator=False, points_space=None, strict=True):
     ''' Read trackvis file from `fileobj`, return `streamlines`, `header`
 
@@ -254,6 +263,9 @@ def track_gen():
     return streamlines, hdr
 
 
+@deprecate_with_version('trackvis.write is deprecated; please use '
+                        'nibabel.streamlines.save, instead.',
+                        since='2.5.0', until='4.0.0')
 def write(fileobj, streamlines, hdr_mapping=None, endianness=None,
           points_space=None):
     ''' Write header and `streamlines` to trackvis file `fileobj`
@@ -536,6 +548,9 @@ def _hdr_from_mapping(hdr=None, mapping=None, endianness=native_code):
     return hdr
 
 
+@deprecate_with_version('empty_header is deprecated; please use '
+                        'nibabel.streamlines.TrkFile.create_empty_header, instead.',
+                        since='2.5.0', until='4.0.0')
 def empty_header(endianness=None, version=2):
     ''' Empty trackvis header
 
@@ -590,7 +605,10 @@ def empty_header(endianness=None, version=2):
     return hdr
 
 
-def aff_from_hdr(trk_hdr, atleast_v2=None):
+@deprecate_with_version('aff_from_hdr is deprecated; please use '
+                        'nibabel.streamlines.trk.get_affine_trackvis_to_rasmm, instead.',
+                        since='2.5.0', until='4.0.0')
+def aff_from_hdr(trk_hdr, atleast_v2=True):
     ''' Return voxel to mm affine from trackvis header
 
     Affine is mapping from voxel space to Nifti (RAS) output coordinate
@@ -625,12 +643,6 @@ def aff_from_hdr(trk_hdr, atleast_v2=None):
     origin field to 0. In future, we'll raise an error rather than try and
     estimate the affine from version 1 fields
     '''
-    if atleast_v2 is None:
-        warnings.warn('Defaulting to `atleast_v2` of False.  Future versions '
-                      'will default to True',
-                      FutureWarning,
-                      stacklevel=2)
-        atleast_v2 = False
     if trk_hdr['version'] == 2:
         aff = trk_hdr['vox_to_ras']
         if aff[3, 3] != 0:
@@ -673,7 +685,10 @@ def aff_from_hdr(trk_hdr, atleast_v2=None):
     return aff
 
 
-def aff_to_hdr(affine, trk_hdr, pos_vox=None, set_order=None):
+@deprecate_with_version('aff_to_hdr is deprecated; please use the '
+                        'nibabel.streamlines.TrkFile.affine_to_rasmm property, instead.',
+                        since='2.5.0', until='4.0.0')
+def aff_to_hdr(affine, trk_hdr, pos_vox=True, set_order=True):
     ''' Set affine `affine` into trackvis header `trk_hdr`
 
     Affine is mapping from voxel space to Nifti RAS) output coordinate
@@ -715,18 +730,6 @@ def aff_to_hdr(affine, trk_hdr, pos_vox=None, set_order=None):
     application).  The application also ignores the origin field, and may not
     use the 'image_orientation_patient' field.
     '''
-    if pos_vox is None:
-        warnings.warn('Default for ``pos_vox`` will change to True in '
-                      'future versions of nibabel',
-                      FutureWarning,
-                      stacklevel=2)
-        pos_vox = False
-    if set_order is None:
-        warnings.warn('Default for ``set_order`` will change to True in '
-                      'future versions of nibabel',
-                      FutureWarning,
-                      stacklevel=2)
-        set_order = False
     try:
         version = trk_hdr['version']
     except (KeyError, ValueError):  # dict or structured array
@@ -797,6 +800,9 @@ class TrackvisFile(object):
         relationship between voxels, rasmm and voxmm space (above).
     '''
 
+    @deprecate_with_version('TrackvisFile is deprecated; please use '
+                            'nibabel.streamlines.TrkFile, instead.',
+                            since='2.5.0', until='4.0.0')
     def __init__(self,
                  streamlines,
                  mapping=None,
@@ -836,7 +842,7 @@ def to_file(self, file_like):
         self.filename = (file_like if isinstance(file_like, basestring)
                          else None)
 
-    def get_affine(self, atleast_v2=None):
+    def get_affine(self, atleast_v2=True):
         """ Get affine from header in object
 
         Returns
@@ -853,15 +859,9 @@ def get_affine(self, atleast_v2=None):
         consider it unsafe for version 1 headers, and in future versions of
         nibabel we will raise an error for trackvis headers < version 2.
         """
-        if atleast_v2 is None:
-            warnings.warn('Defaulting to `atleast_v2` of False.  Future '
-                          'versions will default to True',
-                          FutureWarning,
-                          stacklevel=2)
-            atleast_v2 = False
         return aff_from_hdr(self.header, atleast_v2)
 
-    def set_affine(self, affine, pos_vox=None, set_order=None):
+    def set_affine(self, affine, pos_vox=True, set_order=True):
         """ Set affine `affine` into trackvis header
 
         Affine is mapping from voxel space to Nifti RAS) output coordinate
@@ -888,16 +888,4 @@ def set_affine(self, affine, pos_vox=None, set_order=None):
         -------
         None
         """
-        if pos_vox is None:
-            warnings.warn('Default for ``pos_vox`` will change to True in '
-                          'future versions of nibabel',
-                          FutureWarning,
-                          stacklevel=2)
-            pos_vox = False
-        if set_order is None:
-            warnings.warn('Default for ``set_order`` will change to True in '
-                          'future versions of nibabel',
-                          FutureWarning,
-                          stacklevel=2)
-            set_order = False
         return aff_to_hdr(affine, self.header, pos_vox, set_order)