ENH: Prototype new plotting API for bar plot, accept and return axes

[connortann]

Overview

Supports #3411
Supports #3036

A prototype new standard API interface for the plots, using plots.bar as an example:

• Add an ax parameter to accept an existing matplotlib axes
• Return the axes (if show=False)
• Internal refactor: use the explicit matplotlib interface rather than the imperative

Discussion

I do wonder if the show argument is really needed. In jupyter notebooks, I believe plt.show() is called anyway after each cell, so this seems a little redundant. However, it does have the nice effect of returning None which avoids cluttering the output with the __repr__ of the axes object.

I think changing the return type to ax from fig is technically a breaking change; but this was only a fairly recent addition, so it's probably not too significant.

Checklist

From #3411

• Uses explicit object-oriented matplotlib interface
• Accepts an optional ax parameter
• Suitable tests using pytest-mpl
• Docstring is complete and up-to-date
• Notebook in the "API Examples" section runs and is up-to-date

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 60.65%. Comparing base (9c768ac) to head (3a7bb45).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3523      +/-   ##
==========================================
+ Coverage   59.42%   60.65%   +1.22%     
==========================================
  Files          90       90              
  Lines       12718    12722       +4     
==========================================
+ Hits         7558     7716     +158     
+ Misses       5160     5006     -154     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[connortann]

@DanGolding you may wish to take a skim through this PR if you get a minute

[DanGolding]

I do wonder if the show argument is really needed.

It seems unnecessary to me, unless this has become an established pattern in other libraries?

... avoids cluttering the output with the repr of the axes object

users can always end the line with a ; if they want to suppress the output being printed

[connortann]

I added a proposed "checklist" for things that we wish to overhaul for each plot to #3411. I'll work through that for this PR as an example - in particular, we need more tests and to update the API example notebook.

[connortann]

Here is one functional change that I needed to make in order to reproduce more closely the plots in the API example notebook.

In the API example notebook, many plots have show_data=True. This adds the small grey numbers on the left axis. It looks like this behaviour was then changed at some point to only show data values when there are no transforms applied.

However, I think show_data still makes sense as True for a single explanation when the only operation applied has been __getitem__.

Before (show_data = False)

After (show_data = True)

[connortann]

Whilst we're at it, I updated the API examples notebook. Hopefully it should be executable on CI now. Reducing the sample size of the toy dataset from 32k to 2k rows sped up the runtime significantly, without changing the overall look or complexity of the example plots.

[CloseChoice]

LGTM. Just a couple doc nitpicks from me

[connortann]

Fab - I applied those changes, and shall merge shortly.

Regarding the show param: I agree we could theoretically remove it. I'm inclined to leave that for later, to avoid making too many breaking changes.