CLN/API: move plotting funcs to pandas.plotting (#16005)

closes #12548

Author: jorisvandenbossche

doc/source/visualization.rst

@@ -152,7 +152,7 @@ You can also create these other plots using the methods ``DataFrame.plot.<kind>`
 In addition to these ``kind`` s, there are  the :ref:`DataFrame.hist() <visualization.hist>`,
 and :ref:`DataFrame.boxplot() <visualization.box>` methods, which use a separate interface.
 
-Finally, there are several :ref:`plotting functions <visualization.tools>` in ``pandas.tools.plotting``
+Finally, there are several :ref:`plotting functions <visualization.tools>` in ``pandas.plotting``
 that take a :class:`Series` or :class:`DataFrame` as an argument. These
 include
 
@@ -823,7 +823,7 @@ before plotting.
 Plotting Tools
 --------------
 
-These functions can be imported from ``pandas.tools.plotting``
+These functions can be imported from ``pandas.plotting``
 and take a :class:`Series` or :class:`DataFrame` as an argument.
 
 .. _visualization.scatter_matrix:
@@ -834,7 +834,7 @@ Scatter Matrix Plot
 .. versionadded:: 0.7.3
 
 You can create a scatter plot matrix using the
-``scatter_matrix`` method in ``pandas.tools.plotting``:
+``scatter_matrix`` method in ``pandas.plotting``:
 
 .. ipython:: python
    :suppress:
@@ -843,7 +843,7 @@ You can create a scatter plot matrix using the
 
 .. ipython:: python
 
-   from pandas.tools.plotting import scatter_matrix
+   from pandas.plotting import scatter_matrix
    df = pd.DataFrame(np.random.randn(1000, 4), columns=['a', 'b', 'c', 'd'])
 
    @savefig scatter_matrix_kde.png
@@ -896,7 +896,7 @@ of the same class will usually be closer together and form larger structures.
 
 .. ipython:: python
 
-   from pandas.tools.plotting import andrews_curves
+   from pandas.plotting import andrews_curves
 
    data = pd.read_csv('data/iris.data')
 
@@ -918,7 +918,7 @@ represents one data point. Points that tend to cluster will appear closer togeth
 
 .. ipython:: python
 
-   from pandas.tools.plotting import parallel_coordinates
+   from pandas.plotting import parallel_coordinates
 
    data = pd.read_csv('data/iris.data')
 
@@ -948,7 +948,7 @@ implies that the underlying data are not random.
 
 .. ipython:: python
 
-   from pandas.tools.plotting import lag_plot
+   from pandas.plotting import lag_plot
 
    plt.figure()
 
@@ -983,7 +983,7 @@ confidence band.
 
 .. ipython:: python
 
-   from pandas.tools.plotting import autocorrelation_plot
+   from pandas.plotting import autocorrelation_plot
 
    plt.figure()
 
@@ -1016,7 +1016,7 @@ are what constitutes the bootstrap plot.
 
 .. ipython:: python
 
-   from pandas.tools.plotting import bootstrap_plot
+   from pandas.plotting import bootstrap_plot
 
    data = pd.Series(np.random.rand(1000))
 
@@ -1048,7 +1048,7 @@ be colored differently.
 
 .. ipython:: python
 
-   from pandas.tools.plotting import radviz
+   from pandas.plotting import radviz
 
    data = pd.read_csv('data/iris.data')
 
@@ -1228,14 +1228,14 @@ Using the ``x_compat`` parameter, you can suppress this behavior:
    plt.close('all')
 
 If you have more than one plot that needs to be suppressed, the ``use`` method
-in ``pandas.plot_params`` can be used in a `with statement`:
+in ``pandas.plotting.plot_params`` can be used in a `with statement`:
 
 .. ipython:: python
 
    plt.figure()
 
    @savefig ser_plot_suppress_context.png
-   with pd.plot_params.use('x_compat', True):
+   with pd.plotting.plot_params.use('x_compat', True):
        df.A.plot(color='r')
        df.B.plot(color='g')
        df.C.plot(color='b')
@@ -1450,11 +1450,11 @@ Also, you can pass different :class:`DataFrame` or :class:`Series` for ``table``
 
    plt.close('all')
 
-Finally, there is a helper function ``pandas.tools.plotting.table`` to create a table from :class:`DataFrame` and :class:`Series`, and add it to an ``matplotlib.Axes``. This function can accept keywords which matplotlib table has.
+Finally, there is a helper function ``pandas.plotting.table`` to create a table from :class:`DataFrame` and :class:`Series`, and add it to an ``matplotlib.Axes``. This function can accept keywords which matplotlib table has.
 
 .. ipython:: python
 
-   from pandas.tools.plotting import table
+   from pandas.plotting import table
    fig, ax = plt.subplots(1, 1)
 
    table(ax, np.round(df.describe(), 2),

doc/source/whatsnew/v0.20.0.txt

@@ -21,6 +21,7 @@ Highlights include:
 - Support for S3 handling now uses ``s3fs``, see :ref:`here <whatsnew_0200.api_breaking.s3>`
 - Google BigQuery support now uses the ``pandas-gbq`` library, see :ref:`here <whatsnew_0200.api_breaking.gbq>`
 - Switched the test framework to use `pytest <http://doc.pytest.org/en/latest>`__ (:issue:`13097`)
+- The ``pandas.tools.plotting`` module has been deprecated, moved to ``pandas.plotting``. See :ref:`here <whatsnew_0200.api_breaking.plotting>`
 
 
 Check the :ref:`API Changes <whatsnew_0200.api_breaking>` and :ref:`deprecations <whatsnew_0200.deprecations>` before updating.
@@ -557,6 +558,31 @@ Using ``.iloc``. Here we will get the location of the 'A' column, then use *posi
   df.iloc[[0, 2], df.columns.get_loc('A')]
 
 
+.. _whatsnew_0200.api_breaking.deprecate_plotting
+
+Deprecate .plotting
+^^^^^^^^^^^^^^^^^^^
+
+The ``pandas.tools.plotting`` module has been deprecated,  in favor of the top level ``pandas.plotting`` module. All the public plotting functions are now available
+from ``pandas.plotting`` (:issue:`12548`).
+
+Furthermore, the top-level ``pandas.scatter_matrix`` and ``pandas.plot_params`` are deprecated.
+Users can import these from ``pandas.plotting`` as well.
+
+Previous script:
+
+.. code-block:: python
+
+   pd.tools.plotting.scatter_matrix(df)
+   pd.scatter_matrix(df)
+
+Should be changed to:
+
+.. code-block:: python
+
+    pd.plotting.scatter_matrix(df)
+
+
 .. _whatsnew_0200.api_breaking.deprecate_panel:
 
 Deprecate Panel

pandas/__init__.py

@@ -49,7 +49,15 @@
 from pandas.tools.merge import (merge, ordered_merge,
                                 merge_ordered, merge_asof)
 from pandas.tools.pivot import pivot_table, crosstab
-from pandas.tools.plotting import scatter_matrix, plot_params
+
+# deprecate tools.plotting, plot_params and scatter_matrix on the top namespace
+import pandas.tools.plotting
+plot_params = pandas.plotting._style._Options(deprecated=True)
+# do not import deprecate to top namespace
+scatter_matrix = pandas.util.decorators.deprecate(
+    'pandas.scatter_matrix', pandas.plotting.scatter_matrix,
+    'pandas.plotting.scatter_matrix')
+
 from pandas.tools.tile import cut, qcut
 from pandas.tools.util import to_numeric
 from pandas.core.reshape import melt

pandas/core/config_init.py

@@ -285,7 +285,7 @@ def mpl_style_cb(key):
                   stacklevel=5)
 
     import sys
-    from pandas.tools.plotting import mpl_stylesheet
+    from pandas.plotting._style import mpl_stylesheet
     global style_backup
 
     val = cf.get_option(key)

pandas/core/frame.py

@@ -90,7 +90,7 @@
 import pandas.core.ops as ops
 import pandas.formats.format as fmt
 from pandas.formats.printing import pprint_thing
-import pandas.tools.plotting as gfx
+import pandas.plotting._core as gfx
 
 from pandas._libs import lib, algos as libalgos
 
@@ -5909,11 +5909,11 @@ def _put_str(s, space):
 @Appender(_shared_docs['boxplot'] % _shared_doc_kwargs)
 def boxplot(self, column=None, by=None, ax=None, fontsize=None, rot=0,
             grid=True, figsize=None, layout=None, return_type=None, **kwds):
-    import pandas.tools.plotting as plots
+    from pandas.plotting._core import boxplot
     import matplotlib.pyplot as plt
-    ax = plots.boxplot(self, column=column, by=by, ax=ax, fontsize=fontsize,
-                       grid=grid, rot=rot, figsize=figsize, layout=layout,
-                       return_type=return_type, **kwds)
+    ax = boxplot(self, column=column, by=by, ax=ax, fontsize=fontsize,
+                 grid=grid, rot=rot, figsize=figsize, layout=layout,
+                 return_type=return_type, **kwds)
     plt.draw_if_interactive()
     return ax
 

pandas/core/groupby.py

@@ -4159,7 +4159,7 @@ def groupby_series(obj, col=None):
         return results
 
 
-from pandas.tools.plotting import boxplot_frame_groupby  # noqa
+from pandas.plotting._core import boxplot_frame_groupby  # noqa
 DataFrameGroupBy.boxplot = boxplot_frame_groupby
 
 

pandas/core/series.py

@@ -3026,7 +3026,7 @@ def create_from_value(value, index, dtype):
 # ----------------------------------------------------------------------
 # Add plotting methods to Series
 
-import pandas.tools.plotting as _gfx  # noqa
+import pandas.plotting._core as _gfx  # noqa
 
 Series.plot = base.AccessorProperty(_gfx.SeriesPlotMethods,
                                     _gfx.SeriesPlotMethods)

pandas/plotting/__init__.py

@@ -0,0 +1,19 @@
+"""
+Plotting api
+"""
+
+# flake8: noqa
+
+try:  # mpl optional
+    from pandas.plotting import _converter
+    _converter.register()  # needs to override so set_xlim works with str/number
+except ImportError:
+    pass
+
+from pandas.plotting._misc import (scatter_matrix, radviz,
+                                   andrews_curves, bootstrap_plot,
+                                   parallel_coordinates, lag_plot,
+                                   autocorrelation_plot)
+from pandas.plotting._core import boxplot
+from pandas.plotting._style import plot_params
+from pandas.plotting._tools import table

pandas/plotting/_compat.py

@@ -0,0 +1,67 @@
+# being a bit too dynamic
+# pylint: disable=E1101
+from __future__ import division
+
+from distutils.version import LooseVersion
+
+
+def _mpl_le_1_2_1():
+    try:
+        import matplotlib as mpl
+        return (str(mpl.__version__) <= LooseVersion('1.2.1') and
+                str(mpl.__version__)[0] != '0')
+    except ImportError:
+        return False
+
+
+def _mpl_ge_1_3_1():
+    try:
+        import matplotlib
+        # The or v[0] == '0' is because their versioneer is
+        # messed up on dev
+        return (matplotlib.__version__ >= LooseVersion('1.3.1') or
+                matplotlib.__version__[0] == '0')
+    except ImportError:
+        return False
+
+
+def _mpl_ge_1_4_0():
+    try:
+        import matplotlib
+        return (matplotlib.__version__ >= LooseVersion('1.4') or
+                matplotlib.__version__[0] == '0')
+    except ImportError:
+        return False
+
+
+def _mpl_ge_1_5_0():
+    try:
+        import matplotlib
+        return (matplotlib.__version__ >= LooseVersion('1.5') or
+                matplotlib.__version__[0] == '0')
+    except ImportError:
+        return False
+
+
+def _mpl_ge_2_0_0():
+    try:
+        import matplotlib
+        return matplotlib.__version__ >= LooseVersion('2.0')
+    except ImportError:
+        return False
+
+
+def _mpl_le_2_0_0():
+    try:
+        import matplotlib
+        return matplotlib.compare_versions('2.0.0', matplotlib.__version__)
+    except ImportError:
+        return False
+
+
+def _mpl_ge_2_0_1():
+    try:
+        import matplotlib
+        return matplotlib.__version__ >= LooseVersion('2.0.1')
+    except ImportError:
+        return False