DOC: update the pandas.DataFrame.plot.box docstring #20373

4kxz · 2018-03-15T22:12:23Z

A bit late to the party, but I did it.

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

################################################################################
#################### Docstring (pandas.DataFrame.plot.box)  ####################
################################################################################

Make a box plot of the DataFrame columns.

A box plot is a method for graphically depicting
groups of numerical data through their quartiles.
The box extends from the Q1 to Q3 quartile values of the data,
with a line at the median (Q2). The whiskers extend from the edges
of box to show the range of the data. The position of the whiskers
is set by default to 1.5*IQR (IQR = Q3 - Q1) from the edges of the
box. Outlier points are those past the end of the whiskers.

For further details see Wikipedia's
entry for `boxplot <https://en.wikipedia.org/wiki/Box_plot>`_.

A consideration when using this chart is that the box and the whiskers
can overlap, which is very common when plotting small sets of data.

Parameters
----------
by : string or sequence
    Column in the DataFrame to group by.
**kwds : optional
    Additional keywords are documented in
    :meth:`pandas.DataFrame.plot`.

Returns
-------
axes : :class:`matplotlib.axes.Axes` or numpy.ndarray of them

See Also
--------
pandas.DataFrame.boxplot: Another method to draw a box plot.
pandas.Series.plot.box: Draw a box plot from a Series object.
matplotlib.pyplot.boxplot: Draw a box plot in matplotlib.

Examples
--------
Draw a box plot from a DataFrame with four columns of randomly
generated data.

.. plot::
    :context: close-figs

    >>> data = np.random.randn(25, 4)
    >>> df = pd.DataFrame(data, columns=list('ABCD'))
    >>> plot = df.plot.box()

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwds'} not documented
		Unknown parameters {'**kwds'}

Due to issue #15079 I wasn't sure how to document the by argument. I will follow up to add it later.

Changed kwds description according to #20348.

dukebody

Apart from the typo in the extended description, LGTM!

dukebody · 2018-03-16T08:14:33Z

pandas/plotting/_core.py

+
+        This method draws a box and whisker for each series in the DataFrame
+        in a single chart. The boxes share the vertical axis, which
+        makes makes it easier to compare if they are similar in scale.


"makes makes" → "makes"

codecov · 2018-03-16T09:06:13Z

Codecov Report

Merging #20373 into master will decrease coverage by 0.02%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master   #20373      +/-   ##
==========================================
- Coverage    91.8%   91.78%   -0.03%     
==========================================
  Files         152      152              
  Lines       49223    49223              
==========================================
- Hits        45191    45179      -12     
- Misses       4032     4044      +12

Flag	Coverage Δ
#multiple	`90.17% <100%> (-0.03%)`	⬇️
#single	`41.84% <50%> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/plotting/_core.py	`82.5% <100%> (ø)`	⬆️
pandas/plotting/_converter.py	`65.07% <0%> (-1.74%)`	⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 02477da...49fe6f8. Read the comment docs.

jorisvandenbossche

Thanks for the PR! Added some comments

jorisvandenbossche · 2018-03-16T09:10:34Z

pandas/plotting/_core.py

+        .. plot::
+            :context: close-figs
+
+            >>> data = np.random.randint(0, 10, size=(25, 4))


I think it is better to use normal distribution here (np.random.randn(25, 4)), it gives a bit more natural boxplots (eg with outliers) than a uniform distribution.

jorisvandenbossche · 2018-03-16T09:11:16Z

pandas/plotting/_core.py

+        --------
+        :meth:`pandas.DataFrame.boxplot` : Another method to draw a box plot.
+        :meth:`pandas.Series.plot.box` : Draw a box plot from a Series object.
+        :func:`matplotlib.pyplot.boxplot`: Draw a box plot in matplotlib.


The :meth:`.. part is not needed here, that is done automatically by sphinx.

jorisvandenbossche · 2018-03-16T09:19:59Z

pandas/plotting/_core.py

+        in a single chart. The boxes share the vertical axis, which
+        makes it easier to compare if they are similar in scale.
+        Box plots are useful because they clearly show the median,
+        quartiles and flier points in the data.


There is also the PR on the boxplot method: #20152. It has also extended the summary, you can check if there are some additions over there you could also use here (eg I think the wikipedia link is interesting)

(ideally we would re-use this extended summary for both, but that is something we can fix later)

I've tried to fix the issues that you commented.

The summary from #20152 is more explanatory so I've copied most of it here. I removed the mention to the by parameter which, unless I'm missing something, is not yet implemented for plot.box. Is someone working on that?

dukebody

IMO this is good enough. We can consider creating some shared doc parts for both DataFrame.plot.box and DataFrame.boxplot later.

jorisvandenbossche · 2018-03-23T09:04:46Z

@lkxz Thanks for the updates, and for the PR!

dukebody approved these changes Mar 16, 2018

View reviewed changes

jorisvandenbossche reviewed Mar 16, 2018

View reviewed changes

jorisvandenbossche added Docs Visualization plotting labels Mar 16, 2018

dukebody mentioned this pull request Mar 18, 2018

DOC: update pandas.DataFrame.boxplot docstring. Fixes #8847 #20152

Merged

5 tasks

Extended documentation for pandas.DataFrame.plot.box

89a7848

4kxz force-pushed the plotbox branch from 49b6b84 to 806b2af Compare March 22, 2018 14:58

Feedback corrections

3171a97

4kxz force-pushed the plotbox branch from 806b2af to 3171a97 Compare March 22, 2018 15:05

dukebody approved these changes Mar 22, 2018

View reviewed changes

jorisvandenbossche added 2 commits March 23, 2018 10:03

Update _core.py

49fe6f8

Update _core.py

649aa12

jorisvandenbossche approved these changes Mar 23, 2018

View reviewed changes

jorisvandenbossche merged commit 9093eaf into pandas-dev:master Mar 23, 2018

jorisvandenbossche added this to the 0.23.0 milestone Mar 23, 2018

javadnoorb pushed a commit to javadnoorb/pandas that referenced this pull request Mar 29, 2018

DOC: update the pandas.DataFrame.plot.box docstring (pandas-dev#20373)

e03b4b8

dworvos pushed a commit to dworvos/pandas that referenced this pull request Apr 2, 2018

DOC: update the pandas.DataFrame.plot.box docstring (pandas-dev#20373)

0920812

kornilova203 pushed a commit to kornilova203/pandas that referenced this pull request Apr 23, 2018

DOC: update the pandas.DataFrame.plot.box docstring (pandas-dev#20373)

0f4fccb

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: update the pandas.DataFrame.plot.box docstring #20373

DOC: update the pandas.DataFrame.plot.box docstring #20373

4kxz commented Mar 15, 2018 •

edited

Loading

dukebody left a comment

dukebody Mar 16, 2018

codecov bot commented Mar 16, 2018 •

edited

Loading

jorisvandenbossche left a comment

jorisvandenbossche Mar 16, 2018

jorisvandenbossche Mar 16, 2018

jorisvandenbossche Mar 16, 2018

4kxz Mar 22, 2018

dukebody left a comment

jorisvandenbossche commented Mar 23, 2018

DOC: update the pandas.DataFrame.plot.box docstring #20373

DOC: update the pandas.DataFrame.plot.box docstring #20373

Conversation

4kxz commented Mar 15, 2018 • edited Loading

dukebody left a comment

Choose a reason for hiding this comment

dukebody Mar 16, 2018

Choose a reason for hiding this comment

codecov bot commented Mar 16, 2018 • edited Loading

Codecov Report

jorisvandenbossche left a comment

Choose a reason for hiding this comment

jorisvandenbossche Mar 16, 2018

Choose a reason for hiding this comment

jorisvandenbossche Mar 16, 2018

Choose a reason for hiding this comment

jorisvandenbossche Mar 16, 2018

Choose a reason for hiding this comment

4kxz Mar 22, 2018

Choose a reason for hiding this comment

dukebody left a comment

Choose a reason for hiding this comment

jorisvandenbossche commented Mar 23, 2018

4kxz commented Mar 15, 2018 •

edited

Loading

codecov bot commented Mar 16, 2018 •

edited

Loading