allow injecting axes into plotting functions

[lukasheinrich]

sometimes it's useful too have a pattern in which you can explicitly pass in axes to plot on. This can be useful when trying to compose multiple visualizations into subplots

in pyhf I'd like to introduce the following pattern:

import numpy as np
import matplotlib.pyplot as plt

def plot_results(mutests, tests, test_size=0.05, ax = None):
    """Plot a series of hypothesis tests for various POI values."""
    ax = ax or plt.gca()
    ....
    return ax

saving will still be easy:

Happy to work / PR this is that seems useful

[alexander-held]

Moving this from a v0.3 target to a v0.4 target. #264 will allow returning figures to users for some level of customization, but drawing on user-provided axes requires some more thoughts about API design. For the functions that return many figures (visualize.data_mc and visualize.templates), it is unclear to me how to best provide axes. For the visualize.templates case, the user may not even know how many figures will be created.

One way this may work is changing the visualize.data_mc and visualize.templates API to add kwargs to do one plot at a time, and then just provide the axes for that single plot. Alternatively, axes arguments may be added to the lower-level visualize.plot_result and visualize.plot_model implementations, which produce one figure at a time. When using these functions directly, users would however miss out on the convenience features introduced at the higher level.

[alexander-held]

Moving this once more from v0.4 to v0.5. #219 took priority for an upcoming workshop (https://indico.cern.ch/e/agc-tools-workshop) and the corresponding feature (histogram inputs) will introduce breaking features that will be released in v0.4.