Histogram/Ntuple Package

Classes to provide general Ntuple and Histogram support. Abstract classes provide the structure and interface, which concrete classes based on HBook, Histoscope and Root implement.

Released Version as of May, 5, 2003: v2.2.1

• HepRootNtuple library build is now ISOcxx-aware.

This package may be obtained from:

• The ZOOM reference copy, on the Fermilab fnalu Unix cluster (for example, on fsgi02.fnal.gov) in directories rooted at
  /afs/fnal.gov/files/reports/working-groups/fpcltf/Pkg/HepTuple

• For CDF or D0 users, a reference copy maintained in the standard CDF or D0 manner on their Unix systems. These have a standard mechanism for dealing with "external" supporting software, for example, ensuring that if the HBook product is needed, it is available in a library in the proper place.

• A CVS repository managed by SoftRelTools. A file cvs.setup (last revised October 9, 1997) provides a script for setting up this and/or other zoom products.

Description

User Interface

Documentation and Headers

A Tutorial Example of Writing an Ntuple File

A Note on Ways to Recover Data After a Crash

Comments, questions about getting started, feature needs, and bug/annoyance reports may be sent to ZOOM-support@fnal.gov.

Description

This is a set of "wrappers" expressing the relevant Histogram and Ntuple concepts and hooking to any of a number of underlying Histogram/Ntuple manipulation packages. It is historically based on HepTuple, uses the HepTuple code where applicable, and largely conforms to the naming conventions and choices HepTuple presents. However, the treatment of Ntuples is somewhat modified.

All public symbols start with the letters "Hep" in order to control user namespace pollution.

This package:

• Provides a common interface to the functionallity commonly available for HEP users, for building and filling Histograms and Ntuples.
• Allows for the actual work to manipulate these Histograms to be handled by any of a variety of "managers." An example of a manager is HBook.
• Provides a light-weight Histogram manager, for applications which neither need nor wish to link in HBook/ZEBRA or similarly heavy packages. As of release 1.5.3, the link libraries have been split into four separate files: libHepTuple.a, which contains the manager-independent code, and libHBookHepTuple.a, libRootHepTuple.a and libHistoHepTuple.a, which contain the manager-specific code. Having made a choice of manager, it is then necessary to link only with the manager independent library and the one other that corresponds to your choice of manager.
• As of release 1.7.7, new utility functions are available that attempt to determine which manager was used to produce an existing file. See the header file hepTupleFileType.h for details. In addition, one can use the function
  
  HepFileManager * man = newManager( const string& filename, HepFileManager::mode req_mode )
  
  to open an existing file without knowing the manager type. Note that the second argument may be omitted, in which case it defaults to HEP_UPDATE, just as in the full constructor. Again, see the header file newManager.h for details.
• Provides simple basic mechanisms for retrieving the accumulated data.
• Does not provide viewing, fitting, or plotting functions. Viewers for data managed by HBook or other supported managers are in common use in the HEP community.

This package provides compatibility with the original classes and methods in HepTuple as of March, 1997.

Background and Intentions:

• Interface was developed based on HepTuple work from CLHEP and BaBar.
• Implementation is to be capable of using various existing packages (HBook, Histoscope) as underlying managers, wrapped in that uniform interface.

Development status

• 6/20/97: Interface definition jelled, based on discussion with BaBar's HepTuple representative
  
• 7/15/97: Trial release of histogramming portion only
  
• 10/1/97: Alpha release of full package, restricted to gcc
  
• 11/15/97: First beta release: gcc, KAI on IRIX
  
• 07/27/98: Port to NT, bug fixes, FileManager improvements
  
• 10/23/98: Port BaBar platforms, using STLUtility
  
• 12/4/99: v1.3 includes Histoscope file manager
  
• 9/29/99: v1.5.3 split library into manager independent and manager specific parts
  
• 3/07/01: v1.7.5 Add the combine function to HepFileManager. See Dealing with Data for Multiple Collections in the section on class HepFileManager.
• 3/22/01: v1.7.7 Add functions to determine the manager type for an existing file and, if desired, instantiate an appropriate manager for it.

• Current Efforts : Incorporation of Columnwise Ntuples into Histoscope, which will then be supported as an alternative underlying manager.

User Interface

The HepTuple model is that a user does not have to specify the concrete class type when creating an Ntuple or Histogram. When a manager is declared, it uses some underlying implementation (for example HBook). Therefore, only minimal modifications to user code will be necessary to switch from one underlying package to the next.

There are 3 main user interface classes:

HepFileManager . . . . . . . . . . . . . . . . . . . HepFileManager.h

Specific types of managers:

HepHBookFileManager . . . . . . . . HepHBookFileManager.h

HepRootFileManager . . . . . . . . . . HepRootFileManager.h

HepHistoFileManager . . . . . . . . .. HepHistoFileManager.h

HepHist (Histograms of various types)

HepHist1D . . . . . . . . . . . . . . . . . . . HepHist1D.h

HepHist2D . . . . . . . . . . . . . . . . . . . HepHist2D.h

HepHistProf . . . . . . . . . . . . . . . . . . HepHistProf.h

HepNTuple . . . . .. . . . . . . . . . . .. . . . . . . . HepNtuple.h

m = new HepHBookFileManager( "nameOfFile" );

HepHist1D & stats = m->Hist1D( "MyStatistics", 0, 50.0, 1000 );
HepTuple & events = m->Ntuple( "MyEvents" );


Note that these methods return a reference (rather than a pointer) to the histogram or Ntuple object. See our discussion On the Use of Reference Semantics in HepTuple.

float myVariable;
events.columnAt( "MyTag", &myVariable );


float x;
stats.accumulate( x );
events.captureThenStore();


The best way to understand this package is to look at the physics-oriented tutorial examples.

Documentation and Headers