DataFrame.boxplot returns a dict instead of axes

[fonnesbeck]

The docstring for DataFRame.boxplot claims that the method returns matplotlib axes:

Returns
-------
ax : matplotlib.axes.AxesSubplot

In fact, it instead returns a dict:

In [71]: data.boxplot()
Out[71]:
{'boxes': [<matplotlib.lines.Line2D at 0x10e376110>,
  <matplotlib.lines.Line2D at 0x10e491350>,
  <matplotlib.lines.Line2D at 0x10e477590>,
  <matplotlib.lines.Line2D at 0x10eb0e7d0>,
  <matplotlib.lines.Line2D at 0x10eb3da10>,
  <matplotlib.lines.Line2D at 0x10eb7ec50>,
  <matplotlib.lines.Line2D at 0x10eb9be90>],
 'caps': [<matplotlib.lines.Line2D at 0x10e3ab5d0>,
  <matplotlib.lines.Line2D at 0x10ebbc4d0>,
  <matplotlib.lines.Line2D at 0x10e357690>,
  ...
  <matplotlib.lines.Line2D at 0x10eb020d0>,
  <matplotlib.lines.Line2D at 0x10eb02710>,
  <matplotlib.lines.Line2D at 0x10eb0b310>,
  <matplotlib.lines.Line2D at 0x10eb0b950>,
  <matplotlib.lines.Line2D at 0x10eb9a550>,
  <matplotlib.lines.Line2D at 0x10eb9ab90>]}

Aside from being inconsistent with the documentation, this is inconvenient because I am no longer able to manipulate the axes of the plot directly.

Using Pandas 0.12.0.dev-af85719

Noting that Git blame points at #985, this was intentional at the time.

cc @jseabold

[jreback]

@TomAugspurger address in 0.14? bump?

[TomAugspurger]

I'll just fix the docstring quick. Then there's #4472 that may change the actual behavior.

[jseabold]

This is a bit annoying. I think the dict should be the optional return and the axes always returned, though this breaks backwards compatibility. I think there's even a new boxplot API in maplotlib that might be used. Either way it should be a trivial fix.

To get the axes from the boxplot dict you can just do something like

ax = df.boxplot()['boxes'][0].axes 

[TomAugspurger]

Agreed about the dict. #4472 will change it to always return an array, and I'm fine with breaking backwards compat for that.

[jreback]

yes, ok about breaking this in 0.14 (it needs to be).

[jseabold]

That's not how I read the changeset there. It will always return None if by
is None and ax is not given to boxplot. The right fix there is to define
ret = ax (not bp) and to still return ret. I would add an optional
boxplot_dict = False keyword to the signature and optionally return bp if
True (and appropriate).

[jseabold]

The reason to optionally return the boxplot dict (and why I originally wanted it) is because I don't think you can recover it from just the axes, so you're left with a plot that's really hard to update unless you know what you're doing. Not that the status quo with the dict is all that much better, but at least you know what the objects are for in the case of the dict.