RF: rename orientation_affine to inv_ornt_aff

The original name was very confusing. Add deprecation warning attached
to old name.

Author: matthew-brett

nibabel/funcs.py

@@ -10,7 +10,7 @@
 ''' Processor functions for images '''
 import numpy as np
 
-from .orientations import (io_orientation, orientation_affine, flip_axis,
+from .orientations import (io_orientation, inv_ornt_aff, flip_axis,
                            apply_orientation, OrientationError)
 from .loadsave import load
 
@@ -189,7 +189,7 @@ def as_closest_canonical(img, enforce_diag=False):
             raise OrientationError('Transformed affine is not diagonal')
         return img
     shape = img.shape
-    t_aff = orientation_affine(ornt, shape)
+    t_aff = inv_ornt_aff(ornt, shape)
     out_aff = np.dot(aff, t_aff)
     # check if we are going to end up with something diagonal
     if enforce_diag and not _aff_is_diag(aff):

nibabel/orientations.py

@@ -131,7 +131,7 @@ def apply_orientation(arr, ornt):
     return t_arr
 
 
-def orientation_affine(ornt, shape):
+def inv_ornt_aff(ornt, shape):
     ''' Affine transform reversing transforms implied in `ornt`
 
     Imagine you have an array ``arr`` of shape `shape`, and you apply the
@@ -155,7 +155,7 @@ def orientation_affine(ornt, shape):
 
     Returns
     -------
-    transformed_affine : (p + 1, p + 1) ndarray
+    transform_affine : (p + 1, p + 1) ndarray
        An array ``arr`` (shape `shape`) might be transformed according to
        `ornt`, resulting in a transformed array ``tarr``.  `transformed_affine`
        is the transform that takes you from array coordinates in ``tarr`` to
@@ -186,6 +186,11 @@ def orientation_affine(ornt, shape):
     return np.dot(undo_flip, undo_reorder)
 
 
+@np.deprecate_with_doc("Please use inv_ornt_aff instead")
+def orientation_affine(ornt, shape):
+    return inv_ornt_aff(ornt, shape)
+
+
 def flip_axis(arr, axis=0):
     ''' Flip contents of `axis` in array `arr`
 

nibabel/tests/test_orientations.py

@@ -14,7 +14,7 @@
 
 from numpy.testing import assert_array_equal, assert_array_almost_equal
 
-from ..orientations import (io_orientation, orientation_affine, flip_axis,
+from ..orientations import (io_orientation, inv_ornt_aff, flip_axis,
                             apply_orientation, OrientationError, ornt2axcodes,
                             aff2axcodes)
 
@@ -152,7 +152,7 @@ def test_io_orientation():
         for in_arr, out_ornt in zip(IN_ARRS, OUT_ORNTS):
             ornt = io_orientation(in_arr)
             assert_array_equal(ornt, out_ornt)
-            taff = orientation_affine(ornt, shape)
+            taff = inv_ornt_aff(ornt, shape)
             assert_true(same_transform(taff, ornt, shape))
             for axno in range(3):
                 arr = in_arr.copy()
@@ -163,7 +163,7 @@ def test_io_orientation():
                 ex_ornt[axno, 1] *= -1
                 ornt = io_orientation(arr)
                 assert_array_equal(ornt, ex_ornt)
-                taff = orientation_affine(ornt, shape)
+                taff = inv_ornt_aff(ornt, shape)
                 assert_true(same_transform(taff, ornt, shape))
     # Test nasty hang for zero columns
     rzs = np.c_[np.diag([2, 3, 4, 5]), np.zeros((4,3))]
@@ -217,8 +217,8 @@ def test_aff2axcodes():
                  ('B', 'R', 'U'))
 
 
-def test_orientation_affine():
-    # Extra tests for orientation_affine routines (also tested in
+def test_inv_ornt_aff():
+    # Extra tests for inv_ornt_aff routines (also tested in
     # io_orientations test)
-    assert_raises(OrientationError, orientation_affine,
+    assert_raises(OrientationError, inv_ornt_aff,
                   [[0, 1], [1, -1], [np.nan, np.nan]], (3, 4, 5))