DOC Use plot.<kind> instead of plot(kind=<kind>) GH11043

Author: Moisan

doc/source/visualization.rst

@@ -178,9 +178,9 @@ For labeled, non-time series data, you may wish to produce a bar plot:
    plt.figure();
 
    @savefig bar_plot_ex.png
-   df.ix[5].plot(kind='bar'); plt.axhline(0, color='k')
+   df.ix[5].plot.bar(); plt.axhline(0, color='k')
 
-Calling a DataFrame's :meth:`~DataFrame.plot` method with ``kind='bar'`` produces a multiple
+Calling a DataFrame's :meth:`~DataFrame.plot.bar` method produces a multiple
 bar plot:
 
 .. ipython:: python
@@ -195,7 +195,7 @@ bar plot:
    df2 = pd.DataFrame(np.random.rand(10, 4), columns=['a', 'b', 'c', 'd'])
 
    @savefig bar_plot_multi_ex.png
-   df2.plot(kind='bar');
+   df2.plot.bar();
 
 To produce a stacked bar plot, pass ``stacked=True``:
 
@@ -208,9 +208,9 @@ To produce a stacked bar plot, pass ``stacked=True``:
 .. ipython:: python
 
    @savefig bar_plot_stacked_ex.png
-   df2.plot(kind='bar', stacked=True);
+   df2.plot.bar(stacked=True);
 
-To get horizontal bar plots, pass ``kind='barh'``:
+To get horizontal bar plots, use the ``barh`` method:
 
 .. ipython:: python
    :suppress:
@@ -221,16 +221,20 @@ To get horizontal bar plots, pass ``kind='barh'``:
 .. ipython:: python
 
    @savefig barh_plot_stacked_ex.png
-   df2.plot(kind='barh', stacked=True);
+   df2.plot.barh(stacked=True);
 
 .. _visualization.hist:
 
 Histograms
 ~~~~~~~~~~
 
+.. versionadded:: 0.17.0
+
+Histogram can be drawn by using the :meth:`DataFrame.plot.hist` and :meth:`Series.plot.hist` methods.
+
 .. versionadded:: 0.15.0
 
-Histogram can be drawn specifying ``kind='hist'``.
+Histogram can be drawn by using the ``plot(kind='hist')`` method.
 
 .. ipython:: python
 
@@ -240,7 +244,7 @@ Histogram can be drawn specifying ``kind='hist'``.
    plt.figure();
 
    @savefig hist_new.png
-   df4.plot(kind='hist', alpha=0.5)
+   df4.plot.hist(alpha=0.5)
 
 
 .. ipython:: python
@@ -255,7 +259,7 @@ Histogram can be stacked by ``stacked=True``. Bin size can be changed by ``bins`
    plt.figure();
 
    @savefig hist_new_stacked.png
-   df4.plot(kind='hist', stacked=True, bins=20)
+   df4.plot.hist(stacked=True, bins=20)
 
 .. ipython:: python
    :suppress:
@@ -269,7 +273,7 @@ You can pass other keywords supported by matplotlib ``hist``. For example, horiz
    plt.figure();
 
    @savefig hist_new_kwargs.png
-   df4['a'].plot(kind='hist', orientation='horizontal', cumulative=True)
+   df4['a'].plot.hist(orientation='horizontal', cumulative=True)
 
 .. ipython:: python
    :suppress:
@@ -329,8 +333,12 @@ The ``by`` keyword can be specified to plot grouped histograms:
 Box Plots
 ~~~~~~~~~
 
-Boxplot can be drawn calling a ``Series`` and ``DataFrame.plot`` with ``kind='box'``,
-or ``DataFrame.boxplot`` to visualize the distribution of values within each column.
+Boxplot can be drawn calling :meth:`Series.plot.box` and :meth:`DataFrame.plot.box`,
+or :meth:`DataFrame.boxplot` to visualize the distribution of values within each column.
+
+.. versionadded:: 0.17.0
+
+:meth:`DataFrame.plot.box` and :meth:`Series.plot.box` can now be used to draw boxplot.
 
 .. versionadded:: 0.15.0
 
@@ -350,7 +358,7 @@ a uniform random variable on [0,1).
    df = pd.DataFrame(np.random.rand(10, 5), columns=['A', 'B', 'C', 'D', 'E'])
 
    @savefig box_plot_new.png
-   df.plot(kind='box')
+   df.plot.box()
 
 Boxplot can be colorized by passing ``color`` keyword. You can pass a ``dict``
 whose keys are ``boxes``, ``whiskers``, ``medians`` and ``caps``.
@@ -371,7 +379,7 @@ more complicated colorization, you can get each drawn artists by passing
                 medians='DarkBlue', caps='Gray')
 
    @savefig box_new_colorize.png
-   df.plot(kind='box', color=color, sym='r+')
+   df.plot.box(color=color, sym='r+')
 
 .. ipython:: python
    :suppress:
@@ -385,7 +393,7 @@ For example, horizontal and custom-positioned boxplot can be drawn by
 .. ipython:: python
 
    @savefig box_new_kwargs.png
-   df.plot(kind='box', vert=False, positions=[1, 4, 5, 6, 8])
+   df.plot.box(vert=False, positions=[1, 4, 5, 6, 8])
 
 
 See the :meth:`boxplot <matplotlib.axes.Axes.boxplot>` method and the
@@ -464,7 +472,7 @@ When ``subplots=False`` / ``by`` is ``None``:
 
 * if ``return_type`` is ``'dict'``, a dictionary containing the :class:`matplotlib Lines <matplotlib.lines.Line2D>` is returned. The keys are "boxes", "caps", "fliers", "medians", and "whiskers".
    This is the default of ``boxplot`` in historical reason.
-   Note that ``plot(kind='box')`` returns ``Axes`` as default as the same as other plots.
+   Note that both ``plot.box()`` and ``plot(kind'box')`` return ``Axes`` as default as the same as other plots.
 * if ``return_type`` is ``'axes'``, a :class:`matplotlib Axes <matplotlib.axes.Axes>` containing the boxplot is returned.
 * if ``return_type`` is ``'both'`` a namedtuple containging the :class:`matplotlib Axes <matplotlib.axes.Axes>`
    and :class:`matplotlib Lines <matplotlib.lines.Line2D>` is returned
@@ -514,6 +522,10 @@ Compare to:
 Area Plot
 ~~~~~~~~~
 
+.. versionadded:: 0.17
+
+You can create area plots with :meth:`Series.plot.area` and :meth:`DataFrame.plot.area`.
+
 .. versionadded:: 0.14
 
 You can create area plots with ``Series.plot`` and ``DataFrame.plot`` by passing ``kind='area'``. Area plots are stacked by default. To produce stacked area plot, each column must be either all positive or all negative values.
@@ -531,7 +543,7 @@ When input data contains `NaN`, it will be automatically filled by 0. If you wan
    df = pd.DataFrame(np.random.rand(10, 4), columns=['a', 'b', 'c', 'd'])
 
    @savefig area_plot_stacked.png
-   df.plot(kind='area');
+   df.plot.area();
 
 To produce an unstacked plot, pass ``stacked=False``. Alpha value is set to 0.5 unless otherwise specified:
 
@@ -544,13 +556,17 @@ To produce an unstacked plot, pass ``stacked=False``. Alpha value is set to 0.5
 .. ipython:: python
 
    @savefig area_plot_unstacked.png
-   df.plot(kind='area', stacked=False);
+   df.plot.area(stacked=False);
 
 .. _visualization.scatter:
 
 Scatter Plot
 ~~~~~~~~~~~~
 
+.. versionadded:: 0.17.0
+
+Histogram can be drawn by using the :meth:`DataFrame.plot.scatter` and :meth:`Series.plot.scatter` methods.
+
 .. versionadded:: 0.13
 
 You can create scatter plots with ``DataFrame.plot`` by passing ``kind='scatter'``.
@@ -569,17 +585,17 @@ These can be specified by ``x`` and ``y`` keywords each.
    df = pd.DataFrame(np.random.rand(50, 4), columns=['a', 'b', 'c', 'd'])
 
    @savefig scatter_plot.png
-   df.plot(kind='scatter', x='a', y='b');
+   df.plot.scatter(x='a', y='b');
 
 To plot multiple column groups in a single axes, repeat ``plot`` method specifying target ``ax``.
 It is recommended to specify ``color`` and ``label`` keywords to distinguish each groups.
 
 .. ipython:: python
 
-   ax = df.plot(kind='scatter', x='a', y='b',
+   ax = df.plot.scatter(x='a', y='b',
                 color='DarkBlue', label='Group 1');
    @savefig scatter_plot_repeated.png
-   df.plot(kind='scatter', x='c', y='d',
+   df.plot.scatter(x='c', y='d',
            color='DarkGreen', label='Group 2', ax=ax);
 
 .. ipython:: python
@@ -593,7 +609,7 @@ each point:
 .. ipython:: python
 
    @savefig scatter_plot_colored.png
-   df.plot(kind='scatter', x='a', y='b', c='c', s=50);
+   df.plot.scatter(x='a', y='b', c='c', s=50);
 
 
 .. ipython:: python
@@ -607,7 +623,7 @@ Below example shows a bubble chart using a dataframe column values as bubble siz
 .. ipython:: python
 
    @savefig scatter_plot_bubble.png
-   df.plot(kind='scatter', x='a', y='b', s=df['c']*200);
+   df.plot.scatter(x='a', y='b', s=df['c']*200);
 
 .. ipython:: python
    :suppress:
@@ -622,6 +638,10 @@ See the :meth:`scatter <matplotlib.axes.Axes.scatter>` method and the
 Hexagonal Bin Plot
 ~~~~~~~~~~~~~~~~~~
 
+.. versionadded:: 0.17.0
+
+You can create hexagonal bin plots with :meth:`DataFrame.plot.hexbin`.
+
 .. versionadded:: 0.14
 
 You can create hexagonal bin plots with :meth:`DataFrame.plot` and
@@ -641,7 +661,7 @@ too dense to plot each point individually.
    df['b'] = df['b'] + np.arange(1000)
 
    @savefig hexbin_plot.png
-   df.plot(kind='hexbin', x='a', y='b', gridsize=25)
+   df.plot.hexbin(x='a', y='b', gridsize=25)
 
 
 A useful keyword argument is ``gridsize``; it controls the number of hexagons
@@ -670,7 +690,7 @@ given by column ``z``. The bins are aggregated with numpy's ``max`` function.
    df['z'] = np.random.uniform(0, 3, 1000)
 
    @savefig hexbin_plot_agg.png
-   df.plot(kind='hexbin', x='a', y='b', C='z', reduce_C_function=np.max,
+   df.plot.hexbin(x='a', y='b', C='z', reduce_C_function=np.max,
            gridsize=25)
 
 .. ipython:: python
@@ -686,6 +706,10 @@ See the :meth:`hexbin <matplotlib.axes.Axes.hexbin>` method and the
 Pie plot
 ~~~~~~~~
 
+.. versionadded:: 0.17
+
+You can create a pie plot with :meth:`DataFrame.plot.pie` or :meth:`Series.plot.pie`.
+
 .. versionadded:: 0.14
 
 You can create a pie plot with :meth:`DataFrame.plot` or :meth:`Series.plot` with ``kind='pie'``.
@@ -703,7 +727,7 @@ A ``ValueError`` will be raised if there are any negative values in your data.
    series = pd.Series(3 * np.random.rand(4), index=['a', 'b', 'c', 'd'], name='series')
 
    @savefig series_pie_plot.png
-   series.plot(kind='pie', figsize=(6, 6))
+   series.plot.pie(figsize=(6, 6))
 
 .. ipython:: python
    :suppress:
@@ -730,7 +754,7 @@ A legend will be drawn in each pie plots by default; specify ``legend=False`` to
    df = pd.DataFrame(3 * np.random.rand(4, 2), index=['a', 'b', 'c', 'd'], columns=['x', 'y'])
 
    @savefig df_pie_plot.png
-   df.plot(kind='pie', subplots=True, figsize=(8, 4))
+   df.plot.pie(subplots=True, figsize=(8, 4))
 
 .. ipython:: python
    :suppress:
@@ -757,7 +781,7 @@ Also, other keywords supported by :func:`matplotlib.pyplot.pie` can be used.
 .. ipython:: python
 
    @savefig series_pie_plot_options.png
-   series.plot(kind='pie', labels=['AA', 'BB', 'CC', 'DD'], colors=['r', 'g', 'b', 'c'],
+   series.plot.pie(labels=['AA', 'BB', 'CC', 'DD'], colors=['r', 'g', 'b', 'c'],
                autopct='%.2f', fontsize=20, figsize=(6, 6))
 
 If you pass values whose sum total is less than 1.0, matplotlib draws a semicircle.
@@ -773,7 +797,7 @@ If you pass values whose sum total is less than 1.0, matplotlib draws a semicirc
    series = pd.Series([0.1] * 4, index=['a', 'b', 'c', 'd'], name='series2')
 
    @savefig series_pie_plot_semi.png
-   series.plot(kind='pie', figsize=(6, 6))
+   series.plot.pie(figsize=(6, 6))
 
 See the `matplotlib pie documentation <http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.pie>`__ for more.
 
@@ -861,6 +885,10 @@ You can create a scatter plot matrix using the
 Density Plot
 ~~~~~~~~~~~~
 
+.. versionadded:: 0.17.0
+
+You can create density plots using the :meth:`Series.plot.kde` and :meth:`DataFrame.plot.kde` methods.
+
 .. versionadded:: 0.8.0
 
 You can create density plots using the Series/DataFrame.plot and
@@ -877,7 +905,7 @@ setting ``kind='kde'``:
    ser = pd.Series(np.random.randn(1000))
 
    @savefig kde_plot.png
-   ser.plot(kind='kde')
+   ser.plot.kde()
 
 .. ipython:: python
    :suppress:
@@ -1392,7 +1420,7 @@ Here is an example of one way to easily plot group means with standard deviation
    # Plot
    fig, ax = plt.subplots()
    @savefig errorbar_example.png
-   means.plot(yerr=errors, ax=ax, kind='bar')
+   means.plot.bar(yerr=errors, ax=ax)
 
 .. ipython:: python
    :suppress:
@@ -1532,7 +1560,7 @@ Colormaps can also be used other plot types, like bar charts:
    plt.figure()
 
    @savefig greens.png
-   dd.plot(kind='bar', colormap='Greens')
+   dd.plot.bar(colormap='Greens')
 
 .. ipython:: python
    :suppress: