Subsections

2.4 Histograms in 1D. H1D class

jHepWork uses the JAIDA FreeHEP libraries [4] for histogramming. The main class for an one-dimensional histogram is H1D class, which is an extension of the JAIDA histogram class Histogram1D. Let us create a 1D histogram and fill it with random Gaussian numbers:

>>> from java.util import Random
>>> from jhplot  import H1D,HPlot
>>>
>>> c1=HPlot("Histogram",600,400)
>>> c1.visible()
>>> c1.setAutoRange()
>>> c1.setGTitle("Global title")       # set a title
>>> h1=H1D("Simple1",20, -2.0, 2.0)
>>> rand=Random()
>>> for i in range(100):               # fill histogram
...      h1.fill(rand.nextGaussian())
>>> c1.draw(h1) # draw histogram
One can notice that the code is significantly shorter than the equivalent code written using JAIDA. It should also be noted again that the Jython code above is not too efficient for large loops. One can write a program which is a factor 10 faster by creating an array with random numbers using the jhplot.math package and fill the H1D histogram using the method h1.fill(Array[]). See Section :autorefsection2.25 for more details.

One can access the JAIDA Histogram1D class using the method get().

>>> ha= h1.get()  # get JAIDA Histogram1D object
The corresponding JAIDA class should be exported before doing this. One can also convert the standard JAIDA histogram into the H1D class as:

>>> xAx = new FixedAxis(20,-2.0, 2.0)
>>> haida = new Histogram1D("histogram1","histogram1", xAx )
>>> h2 = H1D(haida) # conversion
As before, one can learn about the public methods of H1D using the Code Assist described in Section :autorefsubsection1.4.3.

One can also define a histogram with variable size of the bins. In this case, you should specify an array of bin edges when constructing the histogram (read the API for details). Here are the major methods associated with the H1D class:

>>> h1.setFill(1)                 # fill the histogram (set 0 if no fill)
>>> h1.fillColor(Color.green)     # fill color
>>> h1.errX(0)                    # do not show horizontal error bar
>>> h1.errY(1)                    # show vertical  error bar
>>> h1.setPenWidthErr(2)          # width of the line
>>> h1.fillColorTransparency(0.7) # set transparency level in case of filled histogram
>>> h1.errColorY(Color.black)     # set color for error bars
It should be noted that the integers in setFill(), errX(), errY() mean logical true for Jython. For BeanShell or JAVA, you should use ``true'' and ``false''. You can edit the plot using a pop-up menu Edit to set all the attribute using the style editor.

2.4.1 H1D operations

If there are two H1D histograms, one can do the following operations:

>>> h1=h1.oper(h2,"New Title","+")     # add  h2 to h1
>>> h1=h1.oper(h2,"New Title","-")     # subtract h2 from h1
>>> h1=h1.oper(h2,"New Title","*")     # multiply h1 by h2
>>> h1=h1.oper(h2,"New Title","/")     # divide   h1 by h2
One can skip the string with a new title if one has to keep the same title as for the original histogram. For example, in this case, the additive operation will be h1=h1.oper(h1,"+")

To scale a histogram, use a similar statement:

>>> h1=h1.operScale("New Title", scaleFactor )
where scaleFactor is a double or an integer scale factor. The title string is optional.

Let us note that all operations in jHepWork do not create new objects after modifications, they all operate on the same object. If you want to create a new object, use copy() method. Usually, all operations return the same (but modified) objects. Therefore, you do not to use h1= in front of the operation.

Here are examples:

>>> #  assume that h1 was created
>>> h2=h1.copy()               # h2 is different object now
>>> h1.operScale(scaleFactor)  # h1 will be scaled. Do not need to return anything  
>>> c1.draw(h1)                # draw scaled and non-scale objects
>>  c1.draw(h2)

Histograms can also be smoothed using operSmooth() method.

2.4.2 Main H1D methods

Here are some other useful methods associated with the H1D class:

>>> h1=H1D(Histogram1D)      # create H1D from JAIDA (Histogram1D)
>>> h1=H1D(IHistogram1D)     # create H1D from JAIDA (IHistogram1D)
>>> h1.setTitle("Title")     # set Title
>>> h1.getTitle()            # get the Title (return string)
>>> hh=h1.get()              # return JAIDA Histogram1D
>>> h1.getMin()              # Min value (return double)
>>> h1.getMax()              # Max value
>>> h1.fill(double)          # fill a histogram with "value"
>>> h1.fill(double, weight)  # fill a histogram, using "weight"
>>> h1.mean()                # get mean value (return double)
>>> h1.rms()                 # get RMS        (return double)
>>> h1.allEntries()          # all entries    (return int)
>>> h1.extraEntries()        # under and overflow entries
>>> h1.entries()             # number of in-range entries
>>> h1.maxBinHeight()        # maximum height of in-range bins
>>> h1.minBinHeight()        # minimum height of in-range bins
>>> h1.sumAllBinHeights()    # sum of bin heights for all entries
>>> h1.print()               # print H1D to the screen
>>> h1.toFile("File")        # write H1D to a file "File"
>>> h1.toTable()             # write H1D to a table for sorting
One can access the information in each bin characterized by the index i using the following methods:

>>> h1.binEntries(i)       # get entries in the corresponding bin
>>> h1.binError(i)         # error on this bin
>>> h1.binHeight(i)        # total height of the corresponding bin
>>> h1.binMean(i)          # get the mean of a bin
>>> h1.binRms(i)           # get the RMS of a bin
Read the full documentation of the JHPlot package.

2.4.3 Reading ROOT histograms

To view ROOT histograms, jHepWork uses the FreeHEP library. First, open a Root Histogram viewer as:

>>> BRoot()                   # open a viewer in a separate frame, or
>>> BRoot("input.root")       # open a ROOT file
The BRoot class is a simple wrapper of the HistogramBrowser class from FreeHEP. One can find the relevant example in root_browser.py file.

To read dimensional histograms is very easy in jHepWork. Use HRoot which opens a ROOT file and extract H1D histograms. This is an example:

>>> from jhplot  import HPlot,H1D,HRoot 
>>> rfr = HRoot( file )  # specify ROOT file  
>>> print "number of histograms=",rfr.getNKeys()
>>> print "ROOT version=",rfr.getVersion()
>>> print "ROOT version=",rfr.getTitle()
>>> print "Print all histograms=",rfr.toString()
>>> # get ROOT histograms 
>>> h1 = rfr.getH1D("mainHistogram")  # H1D histogram created 
>>> h2 = rfr.getH1D("totalHistogram") # H1D histogram created  
>>> # you can also extract them as P1D objects
>>> p1 = rfr.getP1D("mainHistogram")  # P1D class  
>>> p2 = rfr.getP1D("totalHistogram") # P1D class 
>>> c1 = HPlot("Canvas",600,400,1, 1)
>>> c1.visible()
>>> c1.setAutoRange(1,1)
>>> c1.draw(h1)
>>> c1.draw(h2)

One can also use RootFileReader to do the same (but it takes more typing):

>>> from jhplot  import HPlot,H1D
>>> from hep.io.root import RootFileReader
>>> rfr = RootFileReader(file)
>>> print "number of histograms=",rfr.nKeys()
>>> print "ROOT version=",rfr.getVersion()
>>> key = rfr.getKey("mainHistogram")
>>> his1 = key.getObject()        # TH1 histogram created  
>>> h1 = H1D(his1)                # H1D histogram created
Then the h1 object can be plotted in the usual way using draw() method of the HPlot class. Look at the example file in histo_root.py which creates and displays ROOT histograms.