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

Moisan · 2015-10-12T20:11:24Z

I modified the visualization documentation to use plot. instead of plot(kind=) in the examples as explained by issue 11043.

shoyer · 2015-10-12T20:18:31Z

doc/source/visualization.rst


 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');


fix the indentation to align with ( on the line above

shoyer · 2015-10-12T21:20:49Z

Thanks for putting this together! Looks pretty good to me, modulo a few nit-picks.

jreback · 2015-10-12T21:22:54Z

can we leave a small example that uses the old syntax (and maybe a note about the usefulness of having the accessor).

jreback · 2015-10-25T15:30:20Z

any comments @jorisvandenbossche @shoyer @sinhrks

sinhrks · 2015-10-25T15:44:38Z

doc/source/visualization.rst

 .. versionadded:: 0.15.0

-Histogram can be drawn specifying ``kind='hist'``.
+Histogram can be drawn by using the ``plot(kind='hist')`` method.


plot.hist ?

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'.

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

jreback · 2015-11-13T15:17:26Z

@Moisan can you squash

jreback · 2015-11-13T15:19:37Z

doc/source/visualization.rst

+
+.. versionadded:: 0.17.0
+
+:meth:`DataFrame.plot.box` and :meth:`Series.plot.box` can now be used to draw boxplot.

 .. versionadded:: 0.15.0


same here, you can remove the original tag

jreback · 2015-11-13T15:23:01Z

ok I see that we are adding versionadded tags for the API change in 0.17.0, but IIRC that is at the top of the docs?

but its nice to see when the method is added, so reversing some of my comments from above :)

let's leave the original version added tags (but show them with .plot.* rather than .plot(kind=....)

I know a bit of a a misnomer here, but it is overall much cleaner i think.

jorisvandenbossche · 2015-11-13T15:31:35Z

I am personally a bit hesitant to change this in the full plotting docs, because it is a reality that a lot of people are not using the latest pandas. Seeing these docs will lead to errors for them and potential confusion.
(this is of course also true for other new things in the docs, but most of the time it are not full pages)
Keeping the original syntax (kind='') in the main examples on this pages would ensure the docs pages it more cross-version compatible.

jreback · 2015-11-13T15:37:53Z

How about change the actual examples and put a ::note right above (each one)? , this encourages change, but provides the original in an easy way?

Moisan · 2015-11-17T15:47:32Z

So we would let the original examples in a ::note or would we add a few sentences about the fact that before 0.17.0 one should use kind=''?

In short, what do I need to do exactly to make it in the release?

jreback · 2015-11-17T16:16:30Z

@jorisvandenbossche @shoyer what are thoughts here?

jreback · 2015-12-11T01:12:51Z

@shoyer thoughts here

shoyer · 2015-12-11T01:17:09Z

I think we should update the docs to use the new syntax. It's not hard to find old versions of docs on Google, and this really is a cleaner way to do things.

jreback · 2015-12-11T01:20:28Z

sounds good to me. @Moisan let's do that (you can still leave the versionadded tags for when that actual graphing feature came into pandas I guess).

but don't add tags for the overall syntax change. I think their is already a note about that at the top anyhow.

jreback · 2016-01-06T17:19:42Z

@Moisan can you update

Moisan · 2016-01-06T19:21:55Z

I thought my last commit fixed these points. Is there something I missed?

jreback · 2016-01-06T19:23:29Z

@shoyer can you review

jreback · 2016-01-30T15:46:44Z

doc/source/visualization.rst

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


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

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

jreback · 2016-01-30T15:47:16Z

@jorisvandenbossche @shoyer @TomAugspurger

lgtm

TomAugspurger · 2016-01-31T15:08:59Z

@jorisvandenbossche are you OK with this? We have the old version of the docs linked on the main page, and the error should be pretty discoverable since we have the versionadded tag right before discussing the .plot.kind way. I'm +1

jreback · 2016-02-09T23:40:11Z

@jorisvandenbossche ?

jreback · 2016-02-12T03:11:33Z

thanks @Moisan

docs will be built in a few hours, pls review: http://pandas-docs.github.io/pandas-docs-travis/

and if necessary issue a follow up

Moisan · 2016-02-12T21:47:10Z

I reviewed the updated docs and everything seems fine. 👍

jorisvandenbossche · 2016-02-14T12:17:45Z

I also looked at the docs, and I think there is one minor thing that can be improved: the refs to the plotting methods.
To illustrate, the docs say now in the bar plots section: "Calling a DataFrame’s bar() method produces a multiple bar plot:" (from the code Calling a DataFrame's :meth:~DataFrame.plot.bar method produces a multiple). So the rendered version implies that there is a bar() method on DataFrame (because the DataFrame.plot part is left out by sphinx), which is of course not the case.

Possible solution is to leave out the ~: Calling a DataFrame's :meth:DataFrame.plot.bar method ... would give "Calling a DataFrame’s DataFrame.plot.bar() method" (but it can then be rephrased a bit to not have the double DataFrame).
Alternative solution is to provide the text that sphinx should display: Calling a DataFrame's :meth:plot.bar() <DataFrame.plot.bar> method ... would give "Calling a DataFrame’s plot.bar() method"

@Moisan Would you be interested in a follow-up PR?

jorisvandenbossche · 2016-02-14T12:27:26Z

On a closer look, the example I gave is actually the only occurence of that problem :-)
For all the rest you already used the 'absolute' reference without ~!

I changed this one occurence in another PR: #12326

Moisan · 2016-02-15T19:22:24Z

Thanks for the feedback!

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

9042526

shoyer reviewed Oct 12, 2015
View reviewed changes

jreback added Docs Visualization plotting labels Oct 12, 2015

jreback added this to the 0.17.1 milestone Oct 12, 2015

Fix the indentations and keep an example with plot(kind=<kind>)

8d96ed2

sinhrks reviewed Oct 25, 2015
View reviewed changes

Fix the scatter plot description

e08d4fc

jreback reviewed Nov 13, 2015
View reviewed changes

jreback modified the milestones: Next Major Release, 0.17.1 Nov 18, 2015

Remove the unneeded version tags

1f75ee7

jreback reviewed Jan 30, 2016
View reviewed changes

jreback modified the milestones: 0.18.0, Next Major Release Jan 30, 2016

jreback closed this in 2ce897f Feb 12, 2016

Moisan deleted the remove_plot_kind branch February 15, 2016 19:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

Moisan commented Oct 12, 2015

shoyer Oct 12, 2015

shoyer commented Oct 12, 2015

jreback commented Oct 12, 2015

jreback commented Oct 25, 2015

sinhrks Oct 25, 2015

Moisan Oct 26, 2015

jreback Nov 13, 2015

jreback commented Nov 13, 2015

jreback Nov 13, 2015

jreback commented Nov 13, 2015

jorisvandenbossche commented Nov 13, 2015

jreback commented Nov 13, 2015

Moisan commented Nov 17, 2015

jreback commented Nov 17, 2015

jreback commented Dec 11, 2015

shoyer commented Dec 11, 2015

jreback commented Dec 11, 2015

jreback commented Jan 6, 2016

Moisan commented Jan 6, 2016

jreback commented Jan 6, 2016

jreback Jan 30, 2016

TomAugspurger Jan 31, 2016

jreback Jan 31, 2016

jreback commented Jan 30, 2016

TomAugspurger commented Jan 31, 2016

jreback commented Feb 9, 2016

jreback commented Feb 12, 2016

Moisan commented Feb 12, 2016

jorisvandenbossche commented Feb 14, 2016

jorisvandenbossche commented Feb 14, 2016

Moisan commented Feb 15, 2016

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

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

Conversation

Moisan commented Oct 12, 2015

Choose a reason for hiding this comment

shoyer commented Oct 12, 2015

jreback commented Oct 12, 2015

jreback commented Oct 25, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jreback commented Nov 13, 2015

Choose a reason for hiding this comment

jreback commented Nov 13, 2015

jorisvandenbossche commented Nov 13, 2015

jreback commented Nov 13, 2015

Moisan commented Nov 17, 2015

jreback commented Nov 17, 2015

jreback commented Dec 11, 2015

shoyer commented Dec 11, 2015

jreback commented Dec 11, 2015

jreback commented Jan 6, 2016

Moisan commented Jan 6, 2016

jreback commented Jan 6, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jreback commented Jan 30, 2016

TomAugspurger commented Jan 31, 2016

jreback commented Feb 9, 2016

jreback commented Feb 12, 2016

Moisan commented Feb 12, 2016

jorisvandenbossche commented Feb 14, 2016

jorisvandenbossche commented Feb 14, 2016

Moisan commented Feb 15, 2016