Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

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

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9042526
DOC Use plot.<kind> instead of plot(kind=<kind>) GH11043
Moisan Oct 12, 2015
8d96ed2
Fix the indentations and keep an example with plot(kind=<kind>)
Moisan Oct 13, 2015
e08d4fc
Fix the scatter plot description
Moisan Oct 26, 2015
1f75ee7
Remove the unneeded version tags
Moisan Dec 18, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 71 additions & 36 deletions doc/source/visualization.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,16 @@ These include:
* :ref:`'hexbin' <visualization.hexbin>` for hexagonal bin plots
* :ref:`'pie' <visualization.pie>` for pie plots

.. versionadded:: 0.17
For example, a bar plot can be created the following way:

.. ipython:: python

plt.figure();

@savefig bar_plot_ex.png
df.ix[5].plot(kind='bar'); plt.axhline(0, color='k')
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you changed there rest, might as well change this one too (to use .plot.bar())

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably good to keep this one, since right after we say you can alternatively use the new .plot.<kind> method.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok sure


.. versionadded:: 0.17.0

You can also create these other plots using the methods ``DataFrame.plot.<kind>`` instead of providing the ``kind`` keyword argument. This makes it easier to discover plot methods and the specific arguments they use:

Expand Down Expand Up @@ -178,9 +187,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
Expand All @@ -195,7 +204,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``:

Expand All @@ -208,9 +217,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:
Expand All @@ -221,16 +230,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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

plot.hist ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

plot(kind='hist') has been added in version 0.15.0 but not plot.hist. I kept the previous method to point what was new with that version. With new the general description at the top of the document, I felt that plot(kind='hist') was clearer than kind='hist'.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i would remove the 0.15.0 comment as you have the 0.17.0 tag here with the new way


.. ipython:: python

Expand All @@ -240,7 +253,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
Expand All @@ -255,7 +268,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:
Expand All @@ -269,7 +282,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:
Expand Down Expand Up @@ -329,8 +342,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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here, you can remove the original tag


Expand All @@ -350,7 +367,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``.
Expand All @@ -371,7 +388,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:
Expand All @@ -385,7 +402,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
Expand Down Expand Up @@ -464,7 +481,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
Expand Down Expand Up @@ -514,6 +531,10 @@ Compare to:
Area Plot
~~~~~~~~~

.. versionadded:: 0.17
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might as well use 0.17.0 consistently for versionadded?


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.
Expand All @@ -531,7 +552,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:

Expand All @@ -544,13 +565,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

Scatter plot can be drawn by using the :meth:`DataFrame.plot.scatter` method.

.. versionadded:: 0.13

You can create scatter plots with ``DataFrame.plot`` by passing ``kind='scatter'``.
Expand All @@ -569,18 +594,16 @@ 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',
color='DarkBlue', label='Group 1');
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',
color='DarkGreen', label='Group 2', ax=ax);
df.plot.scatter(x='c', y='d', color='DarkGreen', label='Group 2', ax=ax);

.. ipython:: python
:suppress:
Expand All @@ -593,7 +616,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
Expand All @@ -607,7 +630,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:
Expand All @@ -622,6 +645,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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line overlaps with the above?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah other plots section also have duplicated descriptions. Maybe for versionadded?

Personally, I think versionadded for .plot.<> accessor are not needed in each plot kind, because this is described in the top of this document. @jorisvandenbossche ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes I did duplicate the descriptions for versionadded. I'm open to suggestions to rewrite it in a simpler manner.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here, I would remove the older versionsadded

Expand All @@ -641,7 +668,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
Expand Down Expand Up @@ -670,7 +697,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
Expand All @@ -686,6 +713,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'``.
Expand All @@ -703,7 +734,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:
Expand All @@ -730,7 +761,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:
Expand All @@ -757,8 +788,8 @@ 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'],
autopct='%.2f', fontsize=20, figsize=(6, 6))
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.

Expand All @@ -773,7 +804,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.

Expand Down Expand Up @@ -861,6 +892,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
Expand All @@ -877,7 +912,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:
Expand Down Expand Up @@ -1392,7 +1427,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:
Expand Down Expand Up @@ -1532,7 +1567,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:
Expand Down