DRAFT: Plotting (and later fitting) Protocol

[henryiii]

I'm working on defining a Protocol for plotting histograms. To do so, I need some way to access the values and optionally variances so that mplhep and others can decide on what to plot. Here is one possible suggestion:

from numpy.typing import ArrayLike # requires NumPy master
from typing import Protocol, Optional, Tuple, Union, Iterable

class PlottableAxis(Protocol):
    label: str # May be removed soon

    edges: ArrayLike

     # For non-categorical axes, this returns None
    categories: Union[Iterable[int], Iterable[str], None]

class PlottableHistogram(Protocol):
    axes : Tuple[PlottableAxis]
   
    # Values returns the array or the values array for specialized accumulators
    def values(self, flow=False) -> ArrayLike: ...

    # Variance returns the variance if applicable, otherwise None
    # If counts is none, variance returns NaN for that cell (mean storages)
    def variances(self, flow=False) -> Optional[ArrayLike]: ...

We can look at labeling in a later draft, but there are a few key points:

• .values() is like view() for simple storages, and like .view().value for complex ones, providing plotting libraries a consistent way to access the central values for plots.
• .variances() returns None if a storage does not provide information for variances, allowing a plotting library to use if variances := h.variances(): to skip plotting error bars, or do something reasonable. If it exists for that storage, it returns an array.
• .axes[I].categories is an array of labels if this is a Category storage, otherwise it is None.

I didn't add .counts(), but maybe that should be included too?

@HDembinski, what do you think?

This is assuming the master object is the API. You could also have a __histogram_dict__ that returns something like what you see above - then it's much easier to add to existing libraries like Physt and doesn't affect/change the public API, but on the flip side, it's duplicated, all or nothing, and doesn't provide API consistency for users. (Double underscores for clarity - you really aren't supposed to add anything with double underscores, so for an API choice, it might not be ideal).

PS: This is post 0.10.0, possibly post 1.0, so no rush here, feel free to come up with something better.

PPS: Initially, boost-histogram and Uproot4 would implement this, and Hist would get it for free since it is a boost-histogram.

[henryiii]

Mostly from here, for reference: scikit-hep/hist#64

[henryiii]

I should include @jpivarski since I'm including Uproot4 here.

[HDembinski]

Does this mean you want to add .value() and .variance() to boost-histograms?

Comment on uniform handling of heterogeneous types. There are three ways to do this.

a) By enforcing the same interface on all types
b) By making a view, which takes the original type and adds the missing interface that is not available
c) By using free functions (e.g. get_categories(...), get_values(...))

a) is the simplest and most straight-forward. It is the easiest to comprehend for a user. So this is good if you want to offer users a consistent interface, even though it is disputable whether adding methods/attributes that return None makes sense in all cases.

b) and c) are good for library developers. In C++ Boost Histogram, I chose approach c). If I would do it again, I would probably use b).

[HDembinski]

I didn't add .counts(), but maybe that should be included too?

I think it is not essential. I use .counts() in practice to mask bins in profiles which have no entries. This would not be needed if there was a convention that .variance() returns NaN when there are no entries.

[henryiii]

Currently, following what I have above would amount to the following changes to boost-histogram:

• .values() and .variances() added to histograms - we could instead switch to using to_numpy as mplhep does not, but I think this would be cleaner this way. I'm open though. (@andrzejnovak could weigh in too)
• .categories() added to axes, returns None if not categorical, the categories otherwise, so plotting would be able to tell that category labels are needed.
• .label added to axes (see name/title system #430 ) - otherwise, labels can't be attached or propagated along through transformations and such.

I didn't include a way to get circular status for histograms, which plotting would ideally have - I think we could just formalize what we already have implemented, .options with circular there. If we did that, we could include underflow/overflow status (growth shouldn't matter for plotting, so would not be formalized here). I'll try to add this later.

Uproot TH* would also want to implement the above API too.

[HDembinski]

I think it is not essential. I use .counts() in practice to mask bins in profiles which have no entries. This would not be needed if there was a convention that .variance() returns NaN when there are no entries.

Actually, now I remember, since variance is the variance of the samples, you need the counts() if you want to compute the error on the mean.

Edit: You cannot resolve this by making it a convention that variance means "error on the mean". If variance means "error on the mean", then variances are again not addable anymore. Actually, they are not additive for Mean() storage, nevermind. Also, there are use cases for both the error on the mean and for the variance inside the bin. We cannot predict what the user wants. I broke the tie based on the requirement that variances should be additive. (Nope, I didn't)

[HDembinski]

.values() and .variances()

As mentioned elsewhere, singular forms are preferred over plural forms unless required for consistency with existing code.

def values(self, flow=False) -> ArrayLike: ...

Since most histogram libraries don't know anything about flow, you may want to make these properties. I haven't thought too much about this point, so haven't formed a strong opinion yet.

[andrzejnovak]

I would not get hung up on what to_numpy() methods do. They should stay and do just what you expect them to, return a numpy-like histogram tuple w/o uncertainties. Having all the methods take ...(flow=True) also makes sense, though in reality this would be ignored for vast majority of plots.

re variances() I think it may be a bit of an unfortunate misnomer inherited from the TH1 method. I expect what we actually want is the sumw2 info to go into something like this: https://github.com/scikit-hep/mplhep/blob/master/mplhep/plot.py#L214-L221 It already caused some confusion on a pervious mplhep issue.

[henryiii]

you may want to make these properties

I think for consistency, making these function calls that support flows is best in boost-histogram. Histograms support flow= arguments on methods, and Axis do not and use properties instead (as, really, only edges would make sense - centers and widths can't include flow). However, we could leave it out of the plotting Protocol if there's no reason to make it generally plottable - then someone defining def values(self): would still be a valid plottable histogram. Variance is also computed in some cases, so while one would expect to be able to write h.variances = ..., it is more obvious that .variances() is not directly settable.

On an unrelated note, I think our choices so far have also been orthogonal to Physt - @janpipek could comment, but I think these could be, in theory, added to Physt histograms to make them plottable under the same Protocol.

[janpipek]

Hi,

thanks for including me in the conversation. You're doing a great job!

I am currently not going forward with physt at a statistically significant pace ;-) Too much work and too small user base to make the development a priority...

I am split between a) adding new features, b) major API redesign, c) porting some high-level stuff to boost-histogram and freezing the library for the moment. Adapting to the protocol would not be a problem in either case (a few aliases to "a", good naming schema to start with for "b").

Just to give my two cents:

• The flow argument name sounds a bit cryptic (I had to look in the docs to understand that it is actually a suffix for under-/over-), perhaps too strict to be required by all libraries / histograms (btw. how do you define and treat underflows in case of multidimensional histograms?)
• I would warn against making to_numpy part of the protocol, unless the numpy compatibility is essential part not just of the implementation, but also of the API (for the coming years). The libraries making use of the protocol should (be allowed to) work also on objects that behave like numpy arrays but are backed by any storage / computation engine.
• That variance(s) may be or may not be actual variances in the statistical sense, is a good point (sumw2 is a bit cryptic but at least semantically correct). Even the assumption that entries are drawn independently from some distribution, may not be valid for many uses of the library (although then even sumw2 is a debatable thing and None would be the only reasonable return value there). But anyway, physt has the same problem (even worse: errors) ;-)

In any case, I will follow the issue and will happily make physt compatible :-)