Merge branch 'orientation-codes' into main-master

* orientation-codes:
  BF - add future import to support python 2.5
  BF - py3k fixes for trackvis points changes
  RF+TST - add constructor args, fixes, tests for trackvis class interface
  RF - options to read / write voxel and mm points
  RF - new interface for get / set affine routines
  NF - orientations to labels routine with tests
  NF - check and ignore warnings context managers
  TST - add tests for version checks and endian writing

Author: matthew-brett

nibabel/__init__.py

@@ -49,10 +49,10 @@
 from .nifti1 import Nifti1Header, Nifti1Image, Nifti1Pair
 from .minc import MincImage
 from .funcs import (squeeze_image, concat_images, four_to_three,
-                           as_closest_canonical)
+                    as_closest_canonical)
 from .orientations import (io_orientation, orientation_affine,
-                                  flip_axis, OrientationError,
-                                  apply_orientation)
+                           flip_axis, OrientationError,
+                           apply_orientation, aff2axcodes)
 from .imageclasses import class_map, ext_map
 from . import trackvis
 

nibabel/checkwarns.py

@@ -0,0 +1,70 @@
+# emacs: -*- mode: python-mode; py-indent-offset: 4; indent-tabs-mode: nil -*-
+# vi: set ft=python sts=4 ts=4 sw=4 et:
+### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
+#
+#   See COPYING file distributed along with the NiBabel package for the
+#   copyright and license terms.
+#
+### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
+''' Contexts for *with* statement allowing checks for warnings
+
+When we give up 2.5 compatibility we can use python's own
+``tests.test_support.check_warnings``
+
+'''
+from __future__ import with_statement
+
+import warnings
+
+
+class ErrorWarnings(object):
+    """ Context manager to check for warnings as errors.  Usually used with
+    ``assert_raises`` in the with block
+
+    Examples
+    --------
+    >>> with ErrorWarnings():
+    ...     try:
+    ...         warnings.warn('Message', UserWarning)
+    ...     except UserWarning:
+    ...         print 'I consider myself warned'
+    I consider myself warned
+
+    Notes
+    -----
+    The manager will raise a RuntimeError if another warning filter gets put on
+    top of the one it has just added.
+    """
+    def __init__(self):
+        self.added = None
+
+    def __enter__(self):
+        warnings.simplefilter('error')
+        self.added = warnings.filters[0]
+
+    def __exit__(self, exc, value, tb):
+        if warnings.filters[0] != self.added:
+            raise RuntimeError('Somone has done something to the filters')
+        warnings.filters.pop(0)
+        return False # allow any exceptions to propagate
+
+
+class IgnoreWarnings(ErrorWarnings):
+    """ Context manager to ignore warnings
+
+    Examples
+    --------
+    >>> with IgnoreWarnings():
+    ...     warnings.warn('Message', UserWarning)
+
+    (and you get no warning)
+
+    Notes
+    -----
+    The manager will raise a RuntimeError if another warning filter gets put on
+    top of the one it has just added.
+    """
+
+    def __enter__(self):
+        warnings.simplefilter('ignore')
+        self.added = warnings.filters[0]

nibabel/orientations.py

@@ -260,3 +260,76 @@ def flip_axis(arr, axis=0):
     return arr.swapaxes(axis, 0)
 
 
+def ornt2axcodes(ornt, labels=None):
+    """ Convert orientation `ornt` to labels for axis directions
+
+    Parameters
+    ----------
+    ornt : (N,2) array-like
+        orientation array - see io_orientation docstring
+    labels : optional, None or sequence of (2,) sequences
+        (2,) sequences are labels for (beginning, end) of output axis.  That is,
+        if the first row in `ornt` is ``[1, 1]``, and the second (2,) sequence
+        in `labels` is ('back', 'front') then the first returned axis code will
+        be ``'front'``.  If the first row in `ornt` had been ``[1, -1]`` then
+        the first returned value would have been ``'back'``.  If None,
+        equivalent to ``(('L','R'),('P','A'),('I','S'))`` - that is - RAS axes.
+
+    Returns
+    -------
+    axcodes : (N,) tuple
+        labels for positive end of voxel axes.  Dropped axes get a label of
+        None.
+
+    Examples
+    --------
+    >>> ornt2axcodes([[1, 1],[0,-1],[2,1]], (('L','R'),('B','F'),('D','U')))
+    ('F', 'L', 'U')
+    """
+    if labels is None:
+        labels = zip('LPI', 'RAS')
+    axcodes = []
+    for axno, direction in np.asarray(ornt):
+        if np.isnan(axno):
+            axcodes.append(None)
+            continue
+        axint = int(np.round(axno))
+        if axint != axno:
+            raise ValueError('Non integer axis number %f' % axno)
+        elif direction == 1:
+            axcode = labels[axint][1]
+        elif direction == -1:
+            axcode = labels[axint][0]
+        else:
+            raise ValueError('Direction should be -1 or 1')
+        axcodes.append(axcode)
+    return tuple(axcodes)
+
+
+def aff2axcodes(aff, labels=None, tol=None):
+    """ axis direction codes for affine `aff`
+
+    Parameters
+    ----------
+    aff : (N,M) array-like
+        affine transformation matrix
+    labels : optional, None or sequence of (2,) sequences
+        Labels for negative and positive ends of output axes of `aff`.  See
+        docstring for ``ornt2axcodes`` for more detail
+    tol : None or float
+        Tolerance for SVD of affine - see ``io_orientation`` for more detail.
+
+    Returns
+    -------
+    axcodes : (N,) tuple
+        labels for positive end of voxel axes.  Dropped axes get a label of
+        None.
+
+    Examples
+    --------
+    >>> aff = [[0,1,0,10],[-1,0,0,20],[0,0,1,30],[0,0,0,1]]
+    >>> aff2axcodes(aff, (('L','R'),('B','F'),('D','U')))
+    ('B', 'R', 'U')
+    """
+    ornt = io_orientation(aff, tol)
+    return ornt2axcodes(ornt, labels)

nibabel/tests/test_checkwarns.py

@@ -0,0 +1,55 @@
+""" Tests for warnings context managers
+"""
+
+from __future__ import with_statement
+
+from warnings import warn, simplefilter, filters
+
+from ..checkwarns import ErrorWarnings, IgnoreWarnings
+
+from nose.tools import assert_true, assert_equal, assert_raises
+
+
+def test_warn_error():
+    # Check warning error context manager
+    n_warns = len(filters)
+    with ErrorWarnings():
+        assert_raises(UserWarning, warn, 'A test')
+    assert_equal(n_warns, len(filters))
+    def f():
+        with ErrorWarnings():
+            simplefilter('ignore')
+    try:
+        assert_raises(RuntimeError, f)
+        assert_equal(n_warns+2, len(filters))
+    finally:
+        filters.pop(0)
+        filters.pop(0)
+    # Check other errors are propagated
+    def f():
+        with ErrorWarnings():
+            raise ValueError('An error')
+    assert_raises(ValueError, f)
+
+
+def test_warn_ignore():
+    # Check warning ignore context manager
+    n_warns = len(filters)
+    with IgnoreWarnings():
+        warn('Here is a warning, you will not see it')
+        warn('Nor this one', DeprecationWarning)
+    assert_equal(n_warns, len(filters))
+    def f():
+        with IgnoreWarnings():
+            simplefilter('error')
+    try:
+        assert_raises(RuntimeError, f)
+        assert_equal(n_warns+2, len(filters))
+    finally:
+        filters.pop(0)
+        filters.pop(0)
+    # Check other errors are propagated
+    def f():
+        with IgnoreWarnings():
+            raise ValueError('An error')
+    assert_raises(ValueError, f)

nibabel/tests/test_orientations.py

@@ -16,7 +16,8 @@
 
 from ..orientations import (io_orientation, orientation_affine,
                             flip_axis, _ornt_to_affine,
-                            apply_orientation, OrientationError)
+                            apply_orientation, OrientationError,
+                            ornt2axcodes, aff2axcodes)
 
 
 IN_ARRS = [np.eye(4),
@@ -165,6 +166,45 @@ def test_io_orientation():
             assert_true(same_transform(taff, ornt, shape))
 
 
+def test_ornt2axcodes():
+    # Recoding orientation to axis codes
+    labels = (('left', 'right'),('back', 'front'), ('down', 'up'))
+    assert_equal(ornt2axcodes([[0,1],
+                               [1,1],
+                               [2,1]], labels), ('right', 'front', 'up'))
+    assert_equal(ornt2axcodes([[0,-1],
+                               [1,-1],
+                               [2,-1]], labels), ('left', 'back', 'down'))
+    assert_equal(ornt2axcodes([[2,-1],
+                               [1,-1],
+                               [0,-1]], labels), ('down', 'back', 'left'))
+    assert_equal(ornt2axcodes([[1,1],
+                               [2,-1],
+                               [0,1]], labels), ('front', 'down', 'right'))
+    # default is RAS output directions
+    assert_equal(ornt2axcodes([[0,1],
+                               [1,1],
+                               [2,1]]), ('R', 'A', 'S'))
+    # dropped axes produce None
+    assert_equal(ornt2axcodes([[0,1],
+                               [np.nan,np.nan],
+                               [2,1]]), ('R', None, 'S'))
+    # Non integer axes raises error
+    assert_raises(ValueError, ornt2axcodes, [[0.1,1]])
+    # As do directions not in range
+    assert_raises(ValueError, ornt2axcodes, [[0,0]])
+
+
+def test_aff2axcodes():
+    labels = (('left', 'right'),('back', 'front'), ('down', 'up'))
+    assert_equal(aff2axcodes(np.eye(4)), tuple('RAS'))
+    aff = [[0,1,0,10],[-1,0,0,20],[0,0,1,30],[0,0,0,1]]
+    assert_equal(aff2axcodes(aff, (('L','R'),('B','F'),('D','U'))),
+                 ('B', 'R', 'U'))
+    assert_equal(aff2axcodes(aff, (('L','R'),('B','F'),('D','U'))),
+                 ('B', 'R', 'U'))
+
+
 def test_drop_coord():
     # given a 5x4 affine from slicing an fmri,
     # the orientations code should easily reorder and drop the t