From e7de401f5c9634a2a63eb8f44f2193be1a946191 Mon Sep 17 00:00:00 2001 From: Eren Sezener Date: Fri, 26 Feb 2016 13:24:49 +0100 Subject: [PATCH] ENH: Add generalized flip function and its tests --- doc/release/1.12.0-notes.rst | 6 ++ .../reference/routines.array-manipulation.rst | 1 + numpy/lib/function_base.py | 74 ++++++++++++++++- numpy/lib/tests/test_function_base.py | 83 +++++++++++++++++++ numpy/lib/twodim_base.py | 8 +- 5 files changed, 167 insertions(+), 5 deletions(-) diff --git a/doc/release/1.12.0-notes.rst b/doc/release/1.12.0-notes.rst index 85b10cd45553..073e3b1d68ad 100644 --- a/doc/release/1.12.0-notes.rst +++ b/doc/release/1.12.0-notes.rst @@ -99,6 +99,12 @@ keyword argument. It can be set to False when no write operation to the returned array is expected to avoid accidental unpredictable writes. +Generalized ``flip`` +~~~~~~~~~~~~~~~~~~~~ +``flipud`` and ``fliplr`` reverse the elements of an array along axis=0 and +axis=1 respectively. The newly added ``flip`` function reverses the elements of +an array along any given axis. + Improvements ============ diff --git a/doc/source/reference/routines.array-manipulation.rst b/doc/source/reference/routines.array-manipulation.rst index f3ce4889b8bf..b9cf6f448e1e 100644 --- a/doc/source/reference/routines.array-manipulation.rst +++ b/doc/source/reference/routines.array-manipulation.rst @@ -109,6 +109,7 @@ Rearranging elements .. autosummary:: :toctree: generated/ + flip fliplr flipud reshape diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py index 9341685baa6e..84690e4e3b53 100644 --- a/numpy/lib/function_base.py +++ b/numpy/lib/function_base.py @@ -36,7 +36,7 @@ __all__ = [ 'select', 'piecewise', 'trim_zeros', 'copy', 'iterable', 'percentile', - 'diff', 'gradient', 'angle', 'unwrap', 'sort_complex', 'disp', + 'diff', 'gradient', 'angle', 'unwrap', 'sort_complex', 'disp', 'flip', 'extract', 'place', 'vectorize', 'asarray_chkfinite', 'average', 'histogram', 'histogramdd', 'bincount', 'digitize', 'cov', 'corrcoef', 'msort', 'median', 'sinc', 'hamming', 'hanning', 'bartlett', @@ -45,6 +45,78 @@ ] +def flip(m, axis): + """ + Reverse the order of elements in an array along the given axis. + + The shape of the array is preserved, but the elements are reordered. + + .. versionadded:: 1.12.0 + + Parameters + ---------- + m : array_like + Input array. + axis: integer + Axis in array, which entries are reversed. + + + Returns + ------- + out : array_like + A view of `m` with the entries of axis reversed. Since a view is + returned, this operation is done in constant time. + + See Also + -------- + flipud : Flip an array vertically (axis=0). + fliplr : Flip an array horizontally (axis=1). + + Notes + ----- + flip(m, 0) is equivalent to flipud(m). + flip(m, 1) is equivalent to fliplr(m). + flip(m, n) corresponds to ``m[...,::-1,...]`` with ``::-1`` at position n. + + Examples + -------- + >>> A = np.arange(8).reshape((2,2,2)) + >>> A + array([[[0, 1], + [2, 3]], + + [[4, 5], + [6, 7]]]) + + >>> flip(A, 0) + array([[[4, 5], + [6, 7]], + + [[0, 1], + [2, 3]]]) + + >>> flip(A, 1) + array([[[2, 3], + [0, 1]], + + [[6, 7], + [4, 5]]]) + + >>> A = np.random.randn(3,4,5) + >>> np.all(flip(A,2) == A[:,:,::-1,...]) + True + """ + if not hasattr(m, 'ndim'): + m = asarray(m) + indexer = [slice(None)] * m.ndim + try: + indexer[axis] = slice(None, None, -1) + except IndexError: + raise ValueError("axis=%i is invalid for the %i-dimensional input array" + % (axis, m.ndim)) + return m[tuple(indexer)] + + def iterable(y): """ Check whether or not an object can be iterated over. diff --git a/numpy/lib/tests/test_function_base.py b/numpy/lib/tests/test_function_base.py index 235b7f2feb5c..061ba8742fa1 100644 --- a/numpy/lib/tests/test_function_base.py +++ b/numpy/lib/tests/test_function_base.py @@ -23,6 +23,89 @@ from numpy.compat import long +def get_mat(n): + data = np.arange(n) + data = np.add.outer(data, data) + return data + + +class TestFlip(TestCase): + def test_axes(self): + self.assertRaises(ValueError, np.flip, np.ones(4), axis=1) + self.assertRaises(ValueError, np.flip, np.ones((4, 4)), axis=2) + self.assertRaises(ValueError, np.flip, np.ones((4, 4)), axis=-3) + + def test_basic_lr(self): + a = get_mat(4) + b = a[:, ::-1] + assert_equal(np.flip(a, 1), b) + a = [[0, 1, 2], + [3, 4, 5]] + b = [[2, 1, 0], + [5, 4, 3]] + assert_equal(np.flip(a, 1), b) + + def test_basic_ud(self): + a = get_mat(4) + b = a[::-1, :] + assert_equal(np.flip(a, 0), b) + a = [[0, 1, 2], + [3, 4, 5]] + b = [[3, 4, 5], + [0, 1, 2]] + assert_equal(np.flip(a, 0), b) + + def test_3d_swap_axis0(self): + a = np.array([[[0, 1], + [2, 3]], + + [[4, 5], + [6, 7]]]) + + b = np.array([[[4, 5], + [6, 7]], + + [[0, 1], + [2, 3]]]) + + assert_equal(np.flip(a, 0), b) + + def test_3d_swap_axis1(self): + a = np.array([[[0, 1], + [2, 3]], + + [[4, 5], + [6, 7]]]) + + b = np.array([[[2, 3], + [0, 1]], + + [[6, 7], + [4, 5]]]) + + assert_equal(np.flip(a, 1), b) + + def test_3d_swap_axis2(self): + a = np.array([[[0, 1], + [2, 3]], + + [[4, 5], + [6, 7]]]) + + b = np.array([[[1, 0], + [3, 2]], + + [[5, 4], + [7, 6]]]) + + assert_equal(np.flip(a, 2), b) + + def test_4d(self): + a = np.arange(2 * 3 * 4 * 5).reshape(2, 3, 4, 5) + for i in range(a.ndim): + assert_equal(np.flip(a, i), np.flipud(a.swapaxes(0, i)).swapaxes(i, 0)) + + class TestAny(TestCase): def test_basic(self): diff --git a/numpy/lib/twodim_base.py b/numpy/lib/twodim_base.py index 6728ab7ecb07..aefe8d64b091 100644 --- a/numpy/lib/twodim_base.py +++ b/numpy/lib/twodim_base.py @@ -57,7 +57,7 @@ def fliplr(m): Notes ----- - Equivalent to A[:,::-1]. Requires the array to be at least 2-D. + Equivalent to m[:,::-1]. Requires the array to be at least 2-D. Examples -------- @@ -72,7 +72,7 @@ def fliplr(m): [ 3., 0., 0.]]) >>> A = np.random.randn(2,3,5) - >>> np.all(np.fliplr(A)==A[:,::-1,...]) + >>> np.all(np.fliplr(A) == A[:,::-1,...]) True """ @@ -107,7 +107,7 @@ def flipud(m): Notes ----- - Equivalent to ``A[::-1,...]``. + Equivalent to ``m[::-1,...]``. Does not require the array to be two-dimensional. Examples @@ -123,7 +123,7 @@ def flipud(m): [ 1., 0., 0.]]) >>> A = np.random.randn(2,3,5) - >>> np.all(np.flipud(A)==A[::-1,...]) + >>> np.all(np.flipud(A) == A[::-1,...]) True >>> np.flipud([1,2])