HTL Histogram Template Library

1
HTL - Histogram Template Library

• Pavel Binko
• LHCb / CERN

2
What is HTL ?

• C class library
• Provides powerful histogramming functionality
• It only deals with histograms - binned data
• (not with n-tuples - unbinned data)
• Exploits the template facility of C
• Designed to be compact, extensible, modular and
  performant
• Uses the same basic signature as HBOOK
  subroutines
• Histogram name, number of bins, lower and upper
  bounds of the histogram axis are enough to create
  a 1D histogram
• Transient and Persistent Histograms are
  de-coupled
• Uses Objectivity/DB for persistency
• Light weight Persistent Object Manager available
  (pre-alpha version)

3
Histogram Classes

• User works with these predefined types
• Histo1D - 1D histogram with Gravity_Bin_1D and
  fixed binning
• Histo1DVar - 1D histogram with Gravity_Bin_1D and
  variable binning
• ProfileHisto - 1D histogram with Profile_Bin and
  fixed binning
• ProfileHistoVar - 1D histogram with Profile_Bin
  and variable binning
• Histo2D - 2D histogram with Weighted_Bin and
  fixed binning
• Histo2DF - 2D histogram with Float_Weighted_Bin
  and fixed binning
• Histo2DVar - 2D histogram with Weighted_Bin and
  variable binning
• Persistent version of all of them available
• PHisto1D etc.

4
Partitions and Bins

• Partitions describe
• One dimension of the problem space
• How it is divided into intervals
• Bins contain information about
• The content, the error and possibly the center of
  the bin
• Fix and variable binning available
• Weighted_Bin represents bins with weighted data
  points
• By default the gravity centers are the middle or
  center of the bin
• Gravity_Bin_1D represents bins with weighted data
  points
• They know how to determine the gravity center of
  the bins
• Profile_Bin represents bins that can average
  another quantity

5
I_Histo Interface

• virtual const char name( )
• Title attached to current histogram.
• virtual I_Bin i_bin( I_Bin_Location a_location
  )
• virtual I_Bin i_extra_bin( I_Extra_Bin_Location
  a_location )
• In-range and extra bin associated with extra
  location a_location
• virtual Size bin_count( )
• virtual Size extra_bin_count( )
• Number of in-range and extra bins
• virtual Size dim( )
• Dimension of the histo, i.e., of the problem
  space
• virtual I_Partition i_partition( Index p 0 )
• Partition interface of this histogram
• virtual I_Bin i_bin( Index i )
• Any bin (in-range or extra) with index "i" (note
  that this is a linear access)

6
I_Partition Interface

• virtual double i_bin_width( Index i )
• Width of in-range bin "i".
• virtual double i_lower_point( )
• Leftmost point of the partition.
• virtual double i_lower_point( Index i )
• Leftmost point of bin indexed by "i".
• virtual double i_upper_point( )
• Rightmost point of the partition.
• virtual double i_upper_point( Index i )
• Rightmost point of bin indexed by "i".

7
I_Bin Interface

• virtual double value( Index i 0) and virtual
  double error( Index i 0)
• Value and error associated with this bin
• virtual Size count( )
• Count associated with this bin Number of
  entries
• virtual void set_value( double other, Index i 0
  )
• Set the value associated with this bin to "other"
• virtual void set_error( double other, Index i 0
  )
• Change/set the error of the bin to "other"
• virtual void set_count( Size other )
• Change/set the count of the bin to "other"
• virtual double center( Index i 0)
• Absolute or relative center of this bin on axis
  "i"
• virtual int offset( Index i 0)
• Relative or absolute position for the center of
  the bin

8
Create and fill a histogram

• include "HTL/Histograms.h"
  // Transient histograms
• Histo1D histo new Histo1D( "Transient
  Histo_1D", 20, 0.0, 20.0 )
• // Let's fill the histogram with 50000 points
• long i
• double x, w
• for( i0 ilt50000 i )
• x (i 22) - 1
• w (x-9.5)(x-9.5)/100
• histo-gtfill(x,w)
• delete histo

9
Helper Classes

• I_Histo, I_Partition and I_Bin interfaces not
  sufficient
• Helper classes introduced do add missing
  functionality
• H_2D_Helper ( make slices, 2D projections )
• H_Bin_Helper ( mins, maxs, in_range_error( ),
  bin_center() )
• H_HistoTable1D and 2D ( write( ) - ASCII table
  output )
• H_Printout ( print( ) - line printer output )
• H_Statistics ( mean( ), rms( ), entries counts )
• Shortcuts for mean( ) and rms( ) provided
• Syntax histo-gtmean( )

10
Output of a histogram

• include "HTL/Histograms.h"
  // Transient histograms
• include "HTL/PHistograms.h"
  // Persistent histograms
• Histo1D histoT new Histo1D("Transient
  Histo_1D", 20, 0.0, 20.0 )
• HepRef(PHisto2D) histoP
• new PHisto2D("Persistent Histo_2D", 20, 0.0,
  20.0, 20, 0.0, 20.0 )
• // Line printer representation of a histogram
• HPrinter hp( cout )
  // Into any output stream
• hp.print( histoT )
• // ASCII table with a histogram contents
• HistoTable1D ht1( "histo.txt )
  // Only into a text file
• ht1.write( histoP )
• delete histoT
• delete histoP

11
What is missing

• Fill( ) is not part of any interface
• Implemented as non-virtual inline functions
• Output the histogram contents as an array (not
  ASCII)
• Open for any input ...

12
Interface to PAW (1)

• Provide set of new (similar to old) PAW commands
• To access HTL histograms the same way as the
  HBOOK histograms are accessed now
• Two new menus created
• OODB - interface to the Objectivity/DB
• OPEN - Open a data base and a container
• HTLIN - Put in memory the HTL histogram indexed
  by ID
• LIST - List the HTL histograms in the currently
  opened data base
• T_HTL - to manipulate HTL transient histograms
• 1DHISTO - Create an HTL histogram
• PRINT - Print a HTL histogram
• LIST - List HTL histograms
• DELETE - Delete HTL histograms identified by ID
• PLOT - Plot a HTL histogram
• FRHBOOK - Convert the HBOOK histogram ID into an
  HTL histogram

13
Interface to PAW (2)

• Proof of concept done
• Integration of C in a FORTRAN application
  possible
• Integration of HTL in well known PAW framework
  possible
• Missing
• 1D histograms with non-equidistant binning
• Profile histograms
• 2D histograms
• Interface to KUIP vectors (PUT/CONTENT,
  GET/CONTENT etc ...)
• HTL histograms filling
• Fitting
• etc.

14
Integration in GAUDI

• Neither HTL code, nor HTL libraries compatible
  with our strategy
• Changes done by Dino Ferrero Merlino and me
• Library compiled in our environment with new
  created project file
• Integration started last week - not part of this
  GAUDI release
• Required changes
• Slight modifications into HistogramSvc
• Decisive changes in IHistogram interface
• Merging of HTL interfaces into single consistent
  IHistogram interface