Accessing existing Histograms and Ntuples

• Basic Readout methods, suitable for accessing the stored data. Viewing tools may be written in terms of these generic methods.
• The ability to activate an existing manager, access a previously created Histogram, and update by adding new points of data.

Constructing an object refering to an existing Histogram

These methods are not yet present in released package

1. It is recommended that the user invoke manager methods to check that the required Histogram (or Ntuple) exists:
   • bool existHist1D ( const char title[] ) const;
   • bool existHist2D ( const char title[] ) const;
   • bool existHistProf ( const char title[] ) const;
   • bool existFlatNtuple ( const char title[] ) const;
   • bool existNtuple ( const char title[] ) const;
     
   Methods accepting an id instead of the title are also provided:
   bool existHist1D ( const int id ) const;
   bool existHist2D ( const int id ) const;
   bool existHistProf ( const int id ) const;
   bool existFlatNtuple ( const int id ) const;
   bool existNtuple ( const int id ) const;

2. Methods of the manager are available to create each type of a Histogram without supplying characteristics:
   • HepHist1D * newHist1D ( const char title[] );
     HepHist1D * newHist1D ( const int id ) ;
   • HepHist2D * newHist2D ( const char title[] );
     HepHist2D * newHist2D ( const int id ) ;
   • HepHistProf * newHistProf ( const char title[] );
     HepHistProf* newHistProf ( const int id ) ;
   These method names have "new" in them, refering to the fact that this Histogram object is newly created for this program, and the pointer should be deleted when the Histogram access is no longer needed.

   The characteristics of the Histogram will be obtained automatically from the manager, and set for the constructed Histogram. Each Histogram class has methods to access this class information.

3. The user may instead provide the full specification of the characteristics of a Histogram. If the Histogram exists, and the characteristics supplied conflict with those known to the manager for that Histogram, an exception will be thrown.

4. The user may now utilize read-access methods such as
   float HepHist2D::bin(const int& binX, const int& binY) const;
   to find the contents of the bins.
   The user may also continue to fill the Histogram (that is, "update" the data) by invoking its accumulate() method.

Constructing an object refering to an existing Histogram

FlatNtuple

Since the constructor for a fresh FlatNtuple does contain definition of its characteristics, a FlatNtuple behaves like a Histogram in this respect. Cosntructors are available to construct a FlatNtuple (which must match an existing one in the manager) without supplying characteristics:

• HepFlatNtuple * newFlatNtuple ( const char title[] );
  HepFlatNtuple * newFlatNtuple ( const int id ) ;
• HepFlatNtuple::HepFlatNtuple ( HepFileManager &mgr, const char title[] );
  HepFlatNtuple::HepFlatNtuple ( HepFileManager &mgr, const int id );

Ntuple

Unlike Histograms and FlatNuples, general Ntuples must invoke methods after construction to define characteristics. Even retrieving data from an existing Ntuple requires specification of column and block information for those columns/blocks desired.

1. The HepNtuple object is constructed. This is the same whether a fresh or existing Ntuple is desired, though an existing Ntuple may be selected by id rather than title. Again, this can be done by a method of
   • HepNtuple * newNtuple ( const char title[] );
     HepNtuple * newNtuple ( const int id ) ;
   • HepNtuple::HepNtuple ( HepFileManager &mgr, const char title[] );
     HepNtuple::HepNtuple ( HepFileManager &mgr, const int id );
2. The characteristics of any columns and blocks the user will wish to access must be supplied. For each column, the basic column method, should be called:
   • HepNtuple:: void column (

     char tag[],

     ColumnData_t type,

     void* variable,

     char block[]);

   Note that this not only defines the column tag (which one could get from the manager in priciple), but also specifies a "designated variable) to use when placing the retrieved value.
   None of the optional methods to define packing, array dimensions, index or default should be called for existing Ntuples; if they are called, conflicting information will throw an exception.

   For each block that may be accessed as a whole block, the user must invoke the method to define that block:

   • HepNtuple:: void block (char name[], void* data);
   • HepNtuple:: void block (char name[], void* data, char* CHForm);
   Unless the method supplying CHForm to define all its columns is used, each column within the block must also be defined, as above.

   Finally, if the Ntuple is to be updated (adding more rows), or if the data will be retrieved by entire row, each block in the Ntuple must be defined.