Deprecate NDFrame.as_matrix

Author: tp

doc/source/whatsnew/v0.22.0.txt

@@ -82,7 +82,7 @@ Deprecations
 ~~~~~~~~~~~~
 
 - ``Series.from_array`` and ``SparseSeries.from_array`` are deprecated. Use the normal constructor ``Series(..)`` and ``SparseSeries(..)`` instead (:issue:`18213`).
--
+- ``NDFrame.as_matrix`` is deprecated. Use ``NDFrame.values`` instead (:issue:`18458`).
 -
 
 .. _whatsnew_0220.prior_deprecations:

pandas/core/generic.py

@@ -3735,6 +3735,9 @@ def _get_bool_data(self):
 
     def as_matrix(self, columns=None):
         """
+        DEPRECATED: This method will be removed in a future version.
+        Use :meth:`NDFrame.values` instead.
+
         Convert the frame to its Numpy-array representation.
 
         Parameters
@@ -3770,6 +3773,8 @@ def as_matrix(self, columns=None):
         --------
         pandas.DataFrame.values
         """
+        warnings.warn("This method will be removed in a future version. "
+                      "Use ``.values`` instead.")
         self._consolidate_inplace()
         if self._AXIS_REVERSED:
             return self._data.as_matrix(columns).T
@@ -3791,7 +3796,10 @@ def values(self):
         int32. By numpy.find_common_type convention, mixing int64 and uint64
         will result in a flot64 dtype.
         """
-        return self.as_matrix()
+        self._consolidate_inplace()
+        if self._AXIS_REVERSED:
+            return self._data.as_matrix().T
+        return self._data.as_matrix()
 
     @property
     def _values(self):
@@ -3801,11 +3809,11 @@ def _values(self):
     @property
     def _get_values(self):
         # compat
-        return self.as_matrix()
+        return self.values
 
     def get_values(self):
         """same as values (but handles sparseness conversions)"""
-        return self.as_matrix()
+        return self.values
 
     def get_dtype_counts(self):
         """Return the counts of dtypes in this object."""

pandas/tests/frame/test_api.py

@@ -243,9 +243,9 @@ def test_itertuples(self):
     def test_len(self):
         assert len(self.frame) == len(self.frame.index)
 
-    def test_as_matrix(self):
+    def test_values(self):
         frame = self.frame
-        mat = frame.as_matrix()
+        mat = frame.values
 
         frameCols = frame.columns
         for i, row in enumerate(mat):
@@ -261,11 +261,11 @@ def test_as_matrix(self):
         assert mat[0, 0] == 'bar'
 
         df = self.klass({'real': [1, 2, 3], 'complex': [1j, 2j, 3j]})
-        mat = df.as_matrix()
+        mat = df.values
         assert mat[0, 0] == 1j
 
         # single block corner case
-        mat = self.frame.as_matrix(['A', 'B'])
+        mat = self.frame[['A', 'B']].values
         expected = self.frame.reindex(columns=['A', 'B']).values
         assert_almost_equal(mat, expected)
 
@@ -311,8 +311,8 @@ def test_class_axis(self):
         DataFrame.index  # no exception!
         DataFrame.columns  # no exception!
 
-    def test_more_asMatrix(self):
-        values = self.mixed_frame.as_matrix()
+    def test_more_values(self):
+        values = self.mixed_frame.values
         assert values.shape[1] == len(self.mixed_frame.columns)
 
     def test_repr_with_mi_nat(self):

pandas/tests/frame/test_nonunique_indexes.py

@@ -439,7 +439,7 @@ def test_columns_with_dups(self):
         xp.columns = ['A', 'A', 'B']
         assert_frame_equal(rs, xp)
 
-    def test_as_matrix_duplicates(self):
+    def test_values_duplicates(self):
         df = DataFrame([[1, 2, 'a', 'b'],
                         [1, 2, 'a', 'b']],
                        columns=['one', 'one', 'two', 'two'])

pandas/tests/sparse/test_frame.py

@@ -78,16 +78,16 @@ def test_fill_value_when_combine_const(self):
         res = df.add(2, fill_value=0)
         tm.assert_sp_frame_equal(res, exp)
 
-    def test_as_matrix(self):
-        empty = self.empty.as_matrix()
+    def test_values(self):
+        empty = self.empty.values
         assert empty.shape == (0, 0)
 
         no_cols = SparseDataFrame(index=np.arange(10))
-        mat = no_cols.as_matrix()
+        mat = no_cols.values
         assert mat.shape == (10, 0)
 
         no_index = SparseDataFrame(columns=np.arange(10))
-        mat = no_index.as_matrix()
+        mat = no_index.values
         assert mat.shape == (0, 10)
 
     def test_copy(self):