rootpy histogram API change proposal (please comment!)

[Noel Dawe]

Dear rootpy users and developers,

In preparation for releasing version 0.8 we needed to finally address the issue with rootpy's histogram binning convention discussed here:

https://github.com/rootpy/rootpy/issues/227

To summarize, rootpy currently starts indexing at the first visible bin, so hist[0] is the same as hist.GetBinContent(1). At the time, it seemed like a more user-friendly approach but in retrospect this was a bad idea. The current indexing scheme breaks ROOT's convention, possibly leading to confusion and silly off-by-one errors, and access to the overflow bins is a bit clumsy.

So, a proposal is ready here:

https://github.com/rootpy/rootpy/pull/432

This completely overhauls the histogram classes to conform with ROOT's binning convention and adds new powerful slicing and rebinning functionality.

The link to the proposal above outlines the new features, but essentially with these changes you could iterate over bins in views of histograms. Views can be constructed by either slicing along the global bin index or along each axis separately. You can then construct new histograms from views of others where the step term in the slice will result in a rebinning along that axis.

For example:

>>> from rootpy.plotting import Hist

>>> from rootpy.plotting import Hist2D

>>> a = Hist2D(10, 0, 1, 10, 0, 1)

>>> a.FillRandom('gaus')

>>> # rebin the x axis by 2 and y axis by 5

>>> b = Hist2D(a[::2,::5])

iterate over a view:

>>> for bin in b[2:4,1:2]:

...     print bin.value, bin.error

... 

567.0 23.8117617996

483.0 21.9772609758

The downside is that this will break existing code if you rely on the current indexing scheme. The plan is to advertise this change loudly with the release of 0.8 but I would also like your input now. If you have any comments, complaints, or ideas, we would very much like to hear them!

Regards,

Noel