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

mabelvj · 2018-03-10T14:26:46Z

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

################################################################################
##################### Docstring (pandas.DataFrame.boxplot) #####################
################################################################################

Make a box plot from DataFrame columns.

Make a box-and-whisker plot from DataFrame columns optionally grouped
by some other 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>`_.

Parameters
----------
column : str or list of str, optional
    Column name or list of names, or vector.
    Can be any valid input to groupby.
by : str or array-like
    Column in the DataFrame to groupby.
ax : object of class matplotlib.axes.Axes, default `None`
    The matplotlib axes to be used by boxplot.
fontsize : float or str
    Tick label font size in points or as a string (e.g., ‘large’)
    (see `matplotlib.axes.Axes.tick_params
    <https://matplotlib.org/api/_as_gen/
    matplotlib.axes.Axes.tick_params.html>`_).
rot : int or float, default 0
    The rotation angle of labels (in degrees)
    with respect to the screen coordinate sytem.
grid : boolean, default `True`
    Setting this to True will show the grid.
figsize : A tuple (width, height) in inches
    The size of the figure to create in matplotlib.
layout : tuple (rows, columns) (optional)
    For example, (3, 5) will display the subplots
    using 3 columns and 5 rows, starting from the top-left.
return_type : {None, 'axes', 'dict', 'both'}, default 'axes'
    The kind of object to return. The default is ``axes``.

    * 'axes' returns the matplotlib axes the boxplot is drawn on.
    * 'dict' returns a dictionary whose values are the matplotlib
      Lines of the boxplot.
    * 'both' returns a namedtuple with the axes and dict.
    * when grouping with ``by``, a Series mapping columns to
      ``return_type`` is returned (i.e.
      ``df.boxplot(column=['Col1','Col2'], by='var',return_type='axes')``
      may return ``Series([AxesSubplot(..),AxesSubplot(..)],
      index=['Col1','Col2'])``).

      If ``return_type`` is `None`, a NumPy array
      of axes with the same shape as ``layout`` is returned
      (i.e. ``df.boxplot(column=['Col1','Col2'],
      by='var',return_type=None)`` may return a
      ``array([<matplotlib.axes._subplots.AxesSubplot object at ..>,
      <matplotlib.axes._subplots.AxesSubplot object at ..>],
      dtype=object)``).
**kwds : Keyword Arguments (optional)
    All other plotting keyword arguments to be passed to
    `matplotlib.pyplot.boxplot <https://matplotlib.org/api/_as_gen/
    matplotlib.pyplot.boxplot.html#matplotlib.pyplot.boxplot>`_.

Returns
-------
result:
    Options:

    * ax : object of class
      matplotlib.axes.Axes (for ``return_type='axes'``)
    * lines : dict (for ``return_type='dict'``)
    * (ax, lines): namedtuple (for ``return_type='both'``)
    * :class:`~pandas.Series` (for ``return_type != None``
      and data grouped with ``by``)
    * :class:`~numpy.array` (for ``return_type=None``
      and data grouped with ``by``)

See Also
--------
matplotlib.pyplot.boxplot: Make a box and whisker plot.
matplotlib.pyplot.hist: Make a hsitogram.

Notes
-----
Use ``return_type='dict'`` when you want to tweak the appearance
of the lines after plotting. In this case a dict containing the Lines
making up the boxes, caps, fliers, medians, and whiskers is returned.

Examples
--------

Boxplots can be created for every column in the dataframe
by ``df.boxplot()`` or indicating the columns to be used:

.. plot::
    :context: close-figs

    >>> np.random.seed(1234)
    >>> df = pd.DataFrame(np.random.rand(10,4),
    ...                   columns=['Col1', 'Col2', 'Col3', 'Col4'])
    >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3'])

Boxplots of variables distributions grouped by a third variable values
can be created using the option ``by``. For instance:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.rand(10,2), columns=['Col1', 'Col2'] )
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> boxplot = df.boxplot(by='X')

A list of strings (i.e. ``['X','Y']``) containing can be passed to boxplot
in order to group the data by combination of the variables in the x-axis:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.rand(10,3),
    ...                   columns=['Col1', 'Col2', 'Col3'])
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> df['Y'] = pd.Series(['A','B','A','B','A','B','A','B','A','B'])
    >>> boxplot = df.boxplot(column=['Col1','Col2'], by=['X','Y'])

The layout of boxplot can be adjusted giving a tuple to ``layout``:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.rand(10,2), columns=['Col1', 'Col2'])
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> boxplot = df.boxplot(by='X', layout=(2,1))

Additional formatting can be done to the boxplot, like suppressing the grid
(``grid=False``), rotating the labels in the x-axis (i.e. ``rot=45``)
or changing the fontsize (i.e. ``fontsize=15``):

.. plot::
    :context: close-figs

    >>> boxplot = df.boxplot(grid=False, rot=45, fontsize=15)

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

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

@EliosMolina

cmdelatorre · 2018-03-10T15:15:23Z

pandas/plotting/_core.py


    Parameters
    ----------
-    data : the pandas object holding the data
    column : column name or list of names, or vector


The Parameter types do not follow the docstring guide.

For example, I suggest that column should be something like:

column : str or list of str, optional Column name or list of names, or vector. Can be any valid input to groupby.

An it applies to the other params as well.

Thanks for the suggestion!

dukebody

There are some important things about explaining arguments and format that should be worked on.

dukebody · 2018-03-10T17:20:11Z

pandas/plotting/_core.py

@@ -1935,52 +1935,134 @@ def plot_series(data, kind='line', ax=None,                    # Series unique


 _shared_docs['boxplot'] = """
-    Make a box plot from DataFrame column optionally grouped by some columns or


The first line should be a short summary not including any details. See https://python-sprints.github.io/pandas/guide/pandas_docstring.html#section-1-short-summary.

dukebody · 2018-03-10T17:25:17Z

pandas/plotting/_core.py

@@ -1935,52 +1935,134 @@ def plot_series(data, kind='line', ax=None,                    # Series unique


 _shared_docs['boxplot'] = """
-    Make a box plot from DataFrame column optionally grouped by some columns or
-    other inputs
+    Make a box-and-whisker plot from DataFrame column optionally grouped


Perhaps you are focusing too much on the shape of a boxplot and how to interpret it. According to the guide:

The extended summary should provide details on why the function is useful and their use cases, if it is not too generic

So I believe it would be better to put more focus on this.

Sorry, now I read #8447 and I see we wanted to add more context about the components of a boxplot and what they mean. So it's OK to leave this.

Maybe add something about the use case for this graph:

A box plot shows the distribution of data with respect to a given variable.

Before the explanatin of the figure.

dukebody · 2018-03-10T17:27:12Z

pandas/plotting/_core.py

+    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.
+    Flier points (outliers) are those past the end of the whiskers.
+    The position of the whiskers is set by default to 1.5 IQR (`whis=1.5``)


"`whis=1.5``" is not formatted correctly, you should have double backquotes also at the start.

Anyhow I think the meaning of whis and its default should be explained in the Parameters section.

ok, I will leave it because it is not defined in the pandas function, but as a matplotlib parameter.

OK, then as you say it's probably not good to write about this parameter here, since it will be confusing for the reader.

dukebody · 2018-03-10T17:38:22Z

pandas/plotting/_core.py


    Parameters
    ----------
-    data : the pandas object holding the data


You are probably right about removing this argument, because even if it's present in the original function, this function is never used alone, but always inside a Series of DataFrame, where data is self

ok, we thought the same, that it is always called from a pandas' object instantiating matplotlib. We checked with other functions (like pandas.plot.line) and data it is not included as parameter in the documentation. Maybe this explains why the validation test failed.

No problem, the validation script is a linter, but we humans are more intelligent than linters and know when to not take into account their output. :)

dukebody · 2018-03-10T17:40:14Z

pandas/plotting/_core.py

-        Column in the DataFrame to group by
-    ax : Matplotlib axes object, optional
+        Column in the DataFrame to groupby.
+    ax :  Matplotlib axes object, (default `None`)


According to the guide, you should not use parenthesis around default values. Use Matplotlib axes object, default None. Also it would be nice to explain what None means here - create a new plot.

I think it'd be better that the type is the Python type (meaning matplotlib.pyplot.axis if that's the right one).

It's the axes returned by gca, matplotlib.axes.Axes.

It comes from matplotlib.figure.Figure.gca(), so probably matplotlib.axes.Axes, right?

dukebody · 2018-03-10T18:07:19Z

pandas/plotting/_core.py

+        >>> np.random.seed(1234)
+
+        >>> df = pd.DataFrame({
+        ...     u'stratifying_var': np.random.uniform(0, 100, 20),


The docs guide advises to try avoid using random data. In this case I believe it's justifiable because there is a relation between random distributions and boxplots and this can be shown in examples.

However please explain in plain English that you are creating a dataframe with points following a uniform and a normal distribution, respectively, in the different columns. You can also probably find two variables that are naturally uniform and normal, respectively.

@lkxz See this ^^ . @datapythonista what do you think? Is it OK to use random data with a seed sometimes in examples if it makes sense?

I agree, feel free to update the documentation too.

BTW do we want to use the unicode mark u'' at all in documentation examples? I believe we should always write strings without u or b unless necessary. This way it will be a bytestring in Python 2 and a text (unicode) in Python 3.

dukebody · 2018-03-10T18:08:36Z

pandas/plotting/_core.py

+        ...     u'price': np.random.normal(100, 5, 20),
+        ...     u'demand': np.random.normal(100, 10, 20)})
+
+        >>> df[u'quartiles'] = pd.qcut(


I believe this is making the example more complicated than needed. The user needs to understand what the qcut method does to understand this example. Can you change the example to not use this additional function?

dukebody · 2018-03-10T18:12:28Z

pandas/plotting/_core.py

+        18        77.282662  100.623565  103.540203    50-75%%
+        19        88.264119   98.386026   99.644870   75-100%%
+
+    To plot the boxplot of the ``demand`` just put:


Better create a boxplot. Repeating plot here is a bit redundant with boxplot. :)

Avoid words as just, simply, etc.

Here you are creating a boxplot of a column grouped by another one. Probably you want to create a boxplot without any grouping first to show the basic functionality.

We found the example in the pandas' cookbook. We also thought it was complicated. Found another example easier in pandas' visualization guide. We're working on changing it.

Yep, perhaps boxplot = df.boxplot(column='demand') is good enough.

dukebody · 2018-03-10T18:14:14Z

pandas/plotting/_core.py

+
+        >>> boxplot = df.boxplot(column=u'demand', by=u'quartiles')
+
+    Use ``grid=False`` to hide the grid:


Just changing this argument doesn't look like a lot of changes to justify an example. Perhaps we can change multiple parameters at the same time to show a more interesting example.

dukebody · 2018-03-10T18:15:08Z

pandas/plotting/_core.py

+
+        >>> boxplot = df.boxplot(column=u'demand', by=u'quartiles', grid=False)
+
+    Optionally, the layout can be changed by setting ``layout=(rows, cols)``:


Yep but here you are playing with figsize as well, it's better if we mention that.

datapythonista

Looks pretty cool, nice work.

Added some extra comments.

datapythonista · 2018-03-11T13:18:30Z

pandas/plotting/_core.py

+
+    See Also
+    --------
+    matplotlib.pyplot.boxplot: Make a box and whisker plot.


I think hist is a good candidate to be listed here. As they somehow represent the same.

datapythonista · 2018-03-11T13:19:20Z

pandas/plotting/_core.py

+        >>> df
+            stratifying_var       price      demand quartiles
+        0         19.151945  106.605791  108.416747     0-25%%
+        1         62.210877   92.265472  123.909605    50-75%%


Does it make sense to use df.head() and avoid having this long output? Or is it relevant?

I agree this is probably too long.

Removed it in the new version.

datapythonista · 2018-03-11T13:20:28Z

pandas/plotting/_core.py

@@ -1935,52 +1935,134 @@ def plot_series(data, kind='line', ax=None,                    # Series unique


 _shared_docs['boxplot'] = """
-    Make a box plot from DataFrame column optionally grouped by some columns or
-    other inputs
+    Make a box-and-whisker plot from DataFrame column optionally grouped


I think the one liner summary is missing, isn't it?

Already added it to the next commit.

datapythonista · 2018-03-11T13:22:06Z

pandas/plotting/_core.py

    column : column name or list of names, or vector
-        Can be any valid input to groupby
+        Can be any valid input to groupby.
    by : string or sequence


should be str instead of string. Also, I think we usually use array-like instead of sequence. I guess they mean the same in this case.

datapythonista · 2018-03-11T13:23:39Z

pandas/plotting/_core.py

-        Column in the DataFrame to group by
-    ax : Matplotlib axes object, optional
+        Column in the DataFrame to groupby.
+    ax :  Matplotlib axes object, (default `None`)


I think it'd be better that the type is the Python type (meaning matplotlib.pyplot.axis if that's the right one).

datapythonista · 2018-03-11T13:23:58Z

pandas/plotting/_core.py

-    ax : Matplotlib axes object, optional
+        Column in the DataFrame to groupby.
+    ax :  Matplotlib axes object, (default `None`)
+        The matplotlib axes to be used by boxplot.
    fontsize : int or string


str instead of string

codecov · 2018-03-11T23:49:55Z

Codecov Report

Merging #20152 into master will increase coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #20152      +/-   ##
==========================================
+ Coverage   91.82%   91.84%   +0.02%     
==========================================
  Files         152      152              
  Lines       49255    49255              
==========================================
+ Hits        45226    45240      +14     
+ Misses       4029     4015      -14

Flag	Coverage Δ
#multiple	`90.23% <ø> (+0.02%)`	⬆️
#single	`41.9% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/plotting/_core.py	`82.5% <ø> (ø)`	⬆️
pandas/util/testing.py	`84.73% <0%> (+0.2%)`	⬆️
pandas/plotting/_converter.py	`66.81% <0%> (+1.73%)`	⬆️

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 4efb39f...39bb166. Read the comment docs.

mabelvj · 2018-03-11T23:54:25Z

Updated the documentation and the first comment of the PR with the new screenshots and output of the validation test.

jorisvandenbossche

Nice docstring! Added a bunch of comments

jorisvandenbossche · 2018-03-12T08:03:34Z

pandas/plotting/_core.py

        All other plotting keyword arguments to be passed to
-        matplotlib's boxplot function
+        `matplotlib.pyplot.boxplot <https://matplotlib.org/api/_as_gen/


You can use :func:`matplotlib.pyplot.boxplot` instead of the full link

jorisvandenbossche · 2018-03-12T08:04:08Z

pandas/plotting/_core.py

-    rot : label rotation angle
+    column : str or list of str, optional
+        Column name or list of names, or vector.
+        Can be any valid input to groupby.


Is this related to groupby? I think it selects which columns to plot?

Yest, the function _grouped_plot_by_column plots the columns performing a groupby.

Added :meth:pandas.DataFrame.groupby.

jorisvandenbossche · 2018-03-12T08:04:27Z

pandas/plotting/_core.py

+        Column name or list of names, or vector.
+        Can be any valid input to groupby.
+    by : str or array-like
+        Column in the DataFrame to groupby.


Can you say something about what the effect is for the plot?

jorisvandenbossche · 2018-03-12T08:05:05Z

pandas/plotting/_core.py

+        Can be any valid input to groupby.
+    by : str or array-like
+        Column in the DataFrame to groupby.
+    ax : object of class matplotlib.axes.Axes, default `None`


keeping it as optional is fine. In the explanation below, I would add that if not passed, a new instance is created.

Ok, thought the same. Will add it.

jorisvandenbossche · 2018-03-12T08:07:50Z

pandas/plotting/_core.py

+        Tick label font size in points or as a string (e.g., ‘large’)
+        (see `matplotlib.axes.Axes.tick_params
+        <https://matplotlib.org/api/_as_gen/
+        matplotlib.axes.Axes.tick_params.html>`_).


I don't see more information about fontsize on that page?

jorisvandenbossche · 2018-03-12T08:08:20Z

pandas/plotting/_core.py

+    column : str or list of str, optional
+        Column name or list of names, or vector.
+        Can be any valid input to groupby.
+    by : str or array-like


add ", optional"

To be fixed.

jorisvandenbossche · 2018-03-12T08:08:52Z

pandas/plotting/_core.py

+    rot : int or float, default 0
+        The rotation angle of labels (in degrees)
+        with respect to the screen coordinate sytem.
+    grid : boolean, default `True`


It's not needed to use backticks in the type description

jorisvandenbossche · 2018-03-12T08:09:31Z

pandas/plotting/_core.py

-
-    `**kwds` : Keyword Arguments
+        The size of the figure to create in matplotlib.
+    layout : tuple (rows, columns) (optional)


(optional) -> , optional

Had the doubt how to format it. Changed all to just optional.

jorisvandenbossche · 2018-03-12T08:13:50Z

pandas/plotting/_core.py

+          ``return_type`` is returned (i.e.
+          ``df.boxplot(column=['Col1','Col2'], by='var',return_type='axes')``
+          may return ``Series([AxesSubplot(..),AxesSubplot(..)],
+          index=['Col1','Col2'])``).


I would rather add an example in the "Examples" section. As putting it here inline will always be limited

jorisvandenbossche · 2018-03-12T08:16:52Z

pandas/plotting/_core.py

+        :context: close-figs
+
+        >>> df = pd.DataFrame(np.random.rand(10,3),
+        ...                   columns=['Col1', 'Col2', 'Col3'])


You can re-use the df from the previous code-block, so maybe not needed to re-define here again

I can remove all and use just the first dataframe, but wouldn't it be clearer to define a new dataframe in each code-block so the user has a clear image of the structure and can reproduce the example just by copy-pasting it, without having to look for the origin of the dataframe?

I guess it depends, because also it can help to see plots of the exact same data with different variations, to see how the different arguments affect the output plot. Also, reusing the same dataframe can help making the examples section a bit shorter and less verbose.

Your call :)

dukebody · 2018-03-18T13:13:48Z

pandas/plotting/_core.py

+
+    See Also
+    --------
+    matplotlib.pyplot.boxplot: Make a box and whisker plot.


I think we need to put a space before the colons here as well.

dukebody · 2018-03-18T13:13:58Z

pandas/plotting/_core.py

+    See Also
+    --------
+    matplotlib.pyplot.boxplot: Make a box and whisker plot.
+    matplotlib.pyplot.hist: Make a hsitogram.


hsitogram → histogram

dukebody · 2018-03-18T13:16:17Z

pandas/plotting/_core.py

+    .. plot::
+        :context: close-figs
+
+        >>> df = pd.DataFrame(np.random.rand(10,3),


As @jorisvandenbossche comments in #20373 (comment), I agree it's better to draw from a normal distribution here to get more natural boxplots.

dukebody · 2018-03-18T13:22:27Z

pandas/plotting/_core.py

+        >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
+        >>> boxplot = df.boxplot(by='X')
+
+    A list of strings (i.e. ``['X','Y']``) containing can be passed to boxplot


This sentence doesn't sound correct, it's missing some noun at "a list of strings containing (what?) can be passed to boxplot".

dukebody · 2018-03-18T13:23:25Z

pandas/plotting/_core.py

+        ...                   columns=['Col1', 'Col2', 'Col3', 'Col4'])
+        >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3'])
+
+    Boxplots of variables distributions grouped by a third variable values


"grouped by the values of a third variable" sounds more natual to me, but I'm not a native English speaker.

dukebody · 2018-03-18T13:29:10Z

@mabelvj can you go over the comments in the review? There are some of them that need to be addressed before we can merge this.

mabelvj · 2018-03-18T13:31:16Z

Yes, I was reviewing them all before making a commit. Had some doubts with the examples for return_type part.

dukebody · 2018-03-18T13:52:20Z

You accidentally added some binary files to your last commit.

dukebody · 2018-03-18T13:55:41Z

pandas/plotting/_core.py

@@ -2078,27 +2067,27 @@ def plot_series(data, kind='line', ax=None,                    # Series unique
        :context: close-figs

        >>> np.random.seed(1234)
-        >>> df = pd.DataFrame(np.random.rand(10,4),
+        >>> df = pd.DataFrame(np.random.randn(10,4),


flake8 will demand a space after the comma, so np.random.randn(10, 4)

It accepts it, no error popped out!

dukebody · 2018-03-18T14:00:58Z

pandas/plotting/_core.py

+    returned by `boxplot`.  When ``return_type='axes'`` is selected,
+    the matplotlib axes on which the boxplot is drawn are returned:
+
+        >>> df.boxplot(column=['Col1','Col2'], return_type='axes')


IMHO it might be enough with a couple of examples for the return types, perhaps being so exhaustive is too verbose and a bit overkill, since one has to care about the ellipsis and all... The different possibilities are already explained at the parameters section.

OK. I'll keep just the most complicated case that needed explanation from the parameters definition.

FYI, you can do axes = df.boxplot(...). Then the return isn't printed out and the test will pass.

If you want to make a point about the return type, you can do

>>> result = df.boxplot(...) >>> type(result) <class pandas.Series>

or something like that.

Great tip! Didn't know how to do it. The internal structure is not shown but it's enough. Thanks @TomAugspurger!

TomAugspurger · 2018-03-22T11:56:48Z

Just to verify, the validate_docstring script passes with your latest (aside from **kwargs)?

TomAugspurger · 2018-03-22T12:04:12Z

pandas/plotting/_core.py

-    lines : dict
-    ax : matplotlib Axes
-    (ax, lines): namedtuple
+    result:


This is the one section I'm unsure about. I would maybe reformat it as

keyord : type

so

The return type depends on the `return_type` parameter * 'axes': a matplotlib.axes.Axes * 'dict' : a dictionary of ... * 'both': namedtuple of ... When grouping the data by `by`, a Series of `return_type` is returned.

And then whatever is going on with return_type=None and by. Sorry this is such a mess, I think it's my fault :)

What about this?:

result: type The return type depends on the `return_type` parameter: * 'axes' : object of class matplotlib.axes.Axes * 'dict' : dict of matplotlib.lines.Line2D objects * 'both': a nametuple with strucure (ax, lines) For data grouped with ``by``: * :class:`~pandas.Series` * :class:`~numpy.array` (for ``return_type = None``)

LGTM! However I wouldn't write the "type" part after result :, since it doesn't add anything in this case, everything is explained later.

datapythonista

Amazing job, added comments about few minor things.

datapythonista · 2018-03-24T16:50:42Z

pandas/plotting/_core.py

-    other inputs
+    Make a box plot from DataFrame columns.
+
+    Make a box-and-whisker plot from DataFrame columns optionally grouped


May be a comma after "columns"?

But the first line should be like a short description and then a whole paragraph going into detail, or not?

Yes, the comma not in the short summary instead of the period. The comma in the whole paragraph Make a box-and-whisker plot from DataFrame columns, optionally grouped :)

Great! I'll add that.

datapythonista · 2018-03-24T16:52:21Z

pandas/plotting/_core.py

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


I'd use backticks for the formula, and use spaces as in Python, so `1.5 * IQR (IQR = Q3 - Q1)`. I think the render in html should look more clear.

Backticks as code or cursive?

Good point, not sure if it's code. It's your call, I think having a different format from the rest would help understand. May be ``IQR * 1.5`` where ``IQR = Q3 - Q1``? ;) That seems like kind of Python propoer code. :)

But whatever you like, it was just an idea that I think would make it a bit easier to read.

datapythonista · 2018-03-24T16:52:44Z

pandas/plotting/_core.py

+    by some other 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


Missing space after the period.

datapythonista · 2018-03-24T16:53:53Z

pandas/plotting/_core.py

+    layout : tuple (rows, columns), optional
+        For example, (3, 5) will display the subplots
+        using 3 columns and 5 rows, starting from the top-left.
+    return_type : {None, 'axes', 'dict', 'both'}, default 'axes'


I think the convention would be {'axes', 'dict', 'both'} or None, default 'axes'.

Changed it, but isn't it more confusing with one of the possible values outside the dict?

It's a good point, I didn't see it this way. But I think the idea is that None is seen more as a type than as a value in this case. The format would be: {'small', 'large'} or int. So, may be the "right" way would be {'axes', 'dict', 'both'} or NoneType or the one you had with the None inside. But if I'm not mistaken everywhere else te None is outside as None. And to me it's probably a bit clearer.

datapythonista · 2018-03-24T16:57:55Z

pandas/plotting/_core.py

+    See Also
+    --------
+    matplotlib.pyplot.boxplot : Make a box and whisker plot.
+    matplotlib.pyplot.hist : Make a histogram.


If we consider hist a related method, and I agree it is, I'd also add here the pandas version (Series.plot.hist).

For the matplotlib ones, I'd use something like "Matplotlib equivalent boxplot", or something like that. I find it slightly confusing that the description is kind of the same as this method, and not explain why.

If we add the pandas hist, may be we can leave the matplotlib out, as it should be linked from its page.

datapythonista · 2018-03-24T17:01:53Z

pandas/plotting/_core.py

+
+        >>> np.random.seed(1234)
+        >>> df = pd.DataFrame(np.random.randn(10,4),
+        ...                   columns=['Col1', 'Col2', 'Col3', 'Col4'])


Is it a problem with the .. plot:: directive to create df in a previous block? If it's not, in most documentation pages what I've seen is:

>>> df = ...

>>> df or >>> df.head() if it's long

Some explanation of the function, boxplot in this case

df.boxplot()

I think it's a bit more clear that the user first sees the data for the example, and then the explanations and the function usage is shown.

If that's a problem with .. plot:: just leave it as it is, is not a big deal.

It's been discussed before. I think that it is clearer for the user to know what dataframe is using since many types of grouping can be done and it is more explicit this way. For consistency, I took the examples from Pandas Documentation: Plotting with matplotlib: Box-plotting where a new dataframe is created for each example.

Fair enough, I missed that discussion, sorry.

…eturn_type

… of examples for return_type

…eturn_type values

…st and corrected format issues

mabelvj · 2018-04-02T13:33:16Z

@TomAugspurger, no errors aside from **kwds

################################################################################
##################### Docstring (pandas.DataFrame.boxplot) #####################
################################################################################

Make a box plot from DataFrame columns.

Make a box-and-whisker plot from DataFrame columns, optionally grouped
by some other 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>`_.

Parameters
----------
column : str or list of str, optional
    Column name or list of names, or vector.
    Can be any valid input to :meth:`pandas.DataFrame.groupby`.
by : str or array-like, optional
    Column in the DataFrame to :meth:`pandas.DataFrame.groupby`.
    One box-plot will be done per value of columns in `by`.
ax : object of class matplotlib.axes.Axes, optional
    The matplotlib axes to be used by boxplot.
fontsize : float or str
    Tick label font size in points or as a string (e.g., `large`).
rot : int or float, default 0
    The rotation angle of labels (in degrees)
    with respect to the screen coordinate sytem.
grid : boolean, default True
    Setting this to True will show the grid.
figsize : A tuple (width, height) in inches
    The size of the figure to create in matplotlib.
layout : tuple (rows, columns), optional
    For example, (3, 5) will display the subplots
    using 3 columns and 5 rows, starting from the top-left.
return_type : {'axes', 'dict', 'both'} or None, default 'axes'
    The kind of object to return. The default is ``axes``.

    * 'axes' returns the matplotlib axes the boxplot is drawn on.
    * 'dict' returns a dictionary whose values are the matplotlib
      Lines of the boxplot.
    * 'both' returns a namedtuple with the axes and dict.
    * when grouping with ``by``, a Series mapping columns to
      ``return_type`` is returned.

      If ``return_type`` is `None`, a NumPy array
      of axes with the same shape as ``layout`` is returned.
**kwds : Keyword Arguments, optional
    All other plotting keyword arguments to be passed to
    :func:`matplotlib.pyplot.boxplot`.

Returns
-------
result :

    The return type depends on the `return_type` parameter:

    * 'axes' : object of class matplotlib.axes.Axes
    * 'dict' : dict of matplotlib.lines.Line2D objects
    * 'both' : a nametuple with strucure (ax, lines)

    For data grouped with ``by``:

    * :class:`~pandas.Series`
    * :class:`~numpy.array` (for ``return_type = None``)

See Also
--------
Series.plot.hist: Make a histogram.
matplotlib.pyplot.boxplot : Matplotlib equivalent plot.

Notes
-----
Use ``return_type='dict'`` when you want to tweak the appearance
of the lines after plotting. In this case a dict containing the Lines
making up the boxes, caps, fliers, medians, and whiskers is returned.

Examples
--------

Boxplots can be created for every column in the dataframe
by ``df.boxplot()`` or indicating the columns to be used:

.. plot::
    :context: close-figs

    >>> np.random.seed(1234)
    >>> df = pd.DataFrame(np.random.randn(10,4),
    ...                   columns=['Col1', 'Col2', 'Col3', 'Col4'])
    >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3'])

Boxplots of variables distributions grouped by the values of a third
variable can be created using the option ``by``. For instance:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.randn(10,2), columns=['Col1', 'Col2'] )
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> boxplot = df.boxplot(by='X')

A list of strings (i.e. ``['X','Y']``) can be passed to boxplot
in order to group the data by combination of the variables in the x-axis:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.randn(10,3),
    ...                   columns=['Col1', 'Col2', 'Col3'])
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> df['Y'] = pd.Series(['A','B','A','B','A','B','A','B','A','B'])
    >>> boxplot = df.boxplot(column=['Col1','Col2'], by=['X','Y'])

The layout of boxplot can be adjusted giving a tuple to ``layout``:

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame(np.random.randn(10,2), columns=['Col1', 'Col2'])
    >>> df['X'] = pd.Series(['A','A','A','A','A','B','B','B','B','B'])
    >>> boxplot = df.boxplot(by='X', layout=(2,1))

Additional formatting can be done to the boxplot, like suppressing the grid
(``grid=False``), rotating the labels in the x-axis (i.e. ``rot=45``)
or changing the fontsize (i.e. ``fontsize=15``):

.. plot::
    :context: close-figs

    >>> boxplot = df.boxplot(grid=False, rot=45, fontsize=15)

The parameter ``return_type`` can be used to select the type of element
returned by `boxplot`.  When ``return_type='axes'`` is selected,
the matplotlib axes on which the boxplot is drawn are returned:

    >>> boxplot = df.boxplot(column=['Col1','Col2'], return_type='axes')
    >>> type(boxplot)
    <class 'matplotlib.axes._subplots.AxesSubplot'>

When grouping with ``by``, a Series mapping columns to ``return_type``
is returned:

    >>> boxplot = df.boxplot(column=['Col1','Col2'], by='X',
    ...                      return_type='axes')
    >>> type(boxplot)
    <class 'pandas.core.series.Series'>

If ``return_type`` is `None`, a NumPy array of axes with the same shape
as ``layout`` is returned:

    >>> boxplot =  df.boxplot(column=['Col1','Col2'], by='X',
    ...                       return_type=None)
    >>> type(boxplot)
    <class 'numpy.ndarray'>

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

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

mabelvj · 2018-04-02T13:39:54Z

Result:

TomAugspurger

Looks really good. Just pushed a commit changing the formatting on some of the examples.

Merging later today.

jorisvandenbossche · 2018-04-03T07:02:50Z

@mabelvj Thanks a lot !!

mabelvj · 2018-04-03T18:36:35Z

Thank you! I've learned a lot!

cmdelatorre suggested changes Mar 10, 2018

View reviewed changes

dukebody suggested changes Mar 10, 2018

View reviewed changes

datapythonista reviewed Mar 11, 2018

View reviewed changes

jorisvandenbossche reviewed Mar 12, 2018

View reviewed changes

jorisvandenbossche added the Docs label Mar 12, 2018

jorisvandenbossche mentioned this pull request Mar 16, 2018

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

Merged

5 tasks

dukebody reviewed Mar 18, 2018

View reviewed changes

mabelvj force-pushed the DOC_Fixes_issue_8847_boxplot_docs branch from 11105ac to 7daedd4 Compare March 18, 2018 13:59

dukebody reviewed Mar 18, 2018

View reviewed changes

mabelvj force-pushed the DOC_Fixes_issue_8847_boxplot_docs branch 2 times, most recently from 8bb9d4d to e9476fc Compare March 21, 2018 16:21

TomAugspurger reviewed Mar 22, 2018

View reviewed changes

datapythonista reviewed Mar 24, 2018

View reviewed changes

mabelvj force-pushed the DOC_Fixes_issue_8847_boxplot_docs branch from 0756028 to 478ed1a Compare March 25, 2018 07:54

mabelvj added 5 commits April 2, 2018 14:00

[WIP] DOC Fixes pandas-dev#8447 added examples

018276c

[WIP] DOC Fixes pandas-dev#8447 created new example and fixed issues

f42600f

[WIP] DOC Fixes pandas-dev#8447 fixed issues and added examples for r…

e9afeb7

…eturn_type

[WIP] DOC Fixes pandas-dev#8447 fixed issues and shortened the number…

0c2398d

… of examples for return_type

[WIP] DOC Fixes pandas-dev#8447 Printing result types for different r…

a723bf2

…eturn_type values

mabelvj added 2 commits April 2, 2018 14:00

[WIP] DOC Fixes pandas-dev#8447 Replaced matplotlib.hist by Series.hi…

8eccba1

…st and corrected format issues

[WIP] DOC Fixes pandas-dev#8447 Added a comma in the description

487352b

mabelvj force-pushed the DOC_Fixes_issue_8847_boxplot_docs branch from 478ed1a to 487352b Compare April 2, 2018 13:31

PEP8 in the examples

39bb166

TomAugspurger approved these changes Apr 2, 2018

View reviewed changes

jorisvandenbossche merged commit 6eda77e into pandas-dev:master Apr 3, 2018

jorisvandenbossche added this to the 0.23.0 milestone Apr 3, 2018

jorisvandenbossche mentioned this pull request Apr 3, 2018

DOC: boxplot docs do not explain what the plot shows at all #8447

Closed

		@@ -1935,52 +1935,134 @@ def plot_series(data, kind='line', ax=None, # Series unique


		_shared_docs['boxplot'] = """
		Make a box plot from DataFrame column optionally grouped by some columns or


		>>> boxplot = df.boxplot(column=u'demand', by=u'quartiles')

		Use ``grid=False`` to hide the grid:


		>>> boxplot = df.boxplot(column=u'demand', by=u'quartiles', grid=False)

		Optionally, the layout can be changed by setting ``layout=(rows, cols)``:

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

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

Conversation

mabelvj commented Mar 10, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dukebody left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

datapythonista left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Mar 11, 2018 • edited Loading

Codecov Report

mabelvj commented Mar 11, 2018

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mabelvj Mar 15, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mabelvj Mar 18, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dukebody commented Mar 18, 2018

mabelvj commented Mar 18, 2018

dukebody commented Mar 18, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mabelvj commented Mar 10, 2018 •

edited

Loading

codecov bot commented Mar 11, 2018 •

edited

Loading

mabelvj Mar 15, 2018 •

edited

Loading

mabelvj Mar 18, 2018 •

edited

Loading

mabelvj Mar 21, 2018 •

edited

Loading