Deprecating the trellis rplot module (GH3445)

Author: jorisvandenbossche

doc/source/visualization.rst

@@ -1607,6 +1607,16 @@ when plotting a large number of points.
 Trellis plotting interface
 --------------------------
 
+.. warning::
+
+    The ``rplot`` trellis plotting interface is deprecated and will be removed
+    in a future version. We refer to external packages like
+    `seaborn <https://github.com/mwaskom/seaborn>`_ for similar but more
+    refined functionality.
+
+    The docs below include some example on how to convert your existing code to
+    these packages.
+
 .. ipython:: python
    :suppress:
 
@@ -1622,7 +1632,6 @@ Trellis plotting interface
    iris_data = read_csv('data/iris.data')
    from pandas import read_csv
    from pandas.tools.plotting import radviz
-   import pandas.tools.rplot as rplot
    plt.close('all')
 
 
@@ -1641,6 +1650,7 @@ Trellis plotting interface
 We import the rplot API:
 
 .. ipython:: python
+   :okwarning:
 
    import pandas.tools.rplot as rplot
 

doc/source/whatsnew/v0.16.0.txt

@@ -365,10 +365,25 @@ The behavior of a small sub-set of edge cases for using ``.loc`` have changed (:
      In [4]: df.loc[2:3]
      TypeError: Cannot do slice indexing on <class 'pandas.tseries.index.DatetimeIndex'> with <type 'int'> keys
 
+
+.. _whatsnew_0160.deprecations:
+
 Deprecations
 ~~~~~~~~~~~~
 
-.. _whatsnew_0160.deprecations:
+- The ``rplot`` trellis plotting interface is deprecated and will be removed
+  in a future version. We refer to external packages like
+  `seaborn <http://stanford.edu/~mwaskom/software/seaborn/>`_ for similar
+  but more refined functionality (:issue:`3445`).
+
+  The documentation includes some examples how to convert your existing code
+  using ``rplot`` to seaborn: - :ref:`rplot docs <rplot>`
+
+
+.. _whatsnew_0160.prior_deprecations:
+
+Removal of prior version deprecations/changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - ``DataFrame.pivot_table`` and ``crosstab``'s ``rows`` and ``cols`` keyword arguments were removed in favor
   of ``index`` and ``columns`` (:issue:`6581`)

pandas/tools/rplot.py

@@ -1,4 +1,5 @@
 import random
+import warnings
 from copy import deepcopy
 from pandas.core.common import _values_from_object
 
@@ -9,6 +10,16 @@
 # * Make sure legends work properly
 #
 
+
+warnings.warn("\n"
+              "The rplot trellis plotting interface is deprecated and will be "
+              "removed in a future version. We refer to external packages "
+              "like seaborn for similar but more refined functionality. \n\n"
+              "See our docs http://pandas.pydata.org/pandas-docs/stable/visualization.html#rplot "
+              "for some example how to convert your existing code to these "
+              "packages.", FutureWarning)
+
+
 class Scale:
     """
     Base class for mapping between graphical and data attributes.