DEP: Deprecate numpy.rank

This function is commonly confused with numpy.linalg.matrix_rank
and exists itself only for history reasons.

Closes gh-4616

2 files changed, 20 insertions, 0 deletions

diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index 575df9628..a2d2f3100 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -4,7 +4,9 @@
 from __future__ import division, absolute_import, print_function
 
 import types
+import warnings
 
+from .. import VisibleDeprecationWarning
 from . import multiarray as mu
 from . import umath as um
 from . import numerictypes as nt
@@ -2453,6 +2455,11 @@ def rank(a):
     If `a` is not already an array, a conversion is attempted.
     Scalars are zero dimensional.
 
+    .. note::
+        This function is deprecated in NumPy 1.9 to avoid confusion with
+        `numpy.linalg.matrix_rank`. The ``ndim`` attribute or function
+        should be used instead.
+
     Parameters
     ----------
     a : array_like
@@ -2486,6 +2493,10 @@ def rank(a):
     0
 
     """
+    warnings.warn(
+        "`rank` is deprecated; use the `ndim` attribute or function instead. "
+        "To find the rank of a matrix see `numpy.linalg.matrix_rank`.",
+        VisibleDeprecationWarning)
     try:
         return a.ndim
     except AttributeError:
diff --git a/numpy/core/tests/test_deprecations.py b/numpy/core/tests/test_deprecations.py
index f7fbb94e5..6e559ab26 100644
--- a/numpy/core/tests/test_deprecations.py
+++ b/numpy/core/tests/test_deprecations.py
@@ -366,5 +366,14 @@ class TestBooleanSubtractDeprecations(_DeprecationTestCase):
         self.assert_deprecated(operator.neg, args=(generic,))
 
 
+class TestRankDeprecation(_DeprecationTestCase):
+    """Test that np.rank is deprecated. The function should simply be
+    removed. The VisibleDeprecationWarning may become unnecessary.
+    """
+    def test(self):
+        a = np.arange(10)
+        assert_warns(np.VisibleDeprecationWarning, np.rank, a)
+
+
 if __name__ == "__main__":
     run_module_suite()