Root Histogram Names and Titles

John Marraffino
6 June 2003

Sharp-eyed readers of the HepRootFileManager header file will have noted that the first argument to the hist1D, hist2D and histProf member functions is advertised to be the histogram object's title. Because of the addition of the setTitle member function, that is only partly true and requires some explanation. In Root, each histogram object (as well as objects of many other classes not of interest to us here) has a name and, separately, a title. In the original implementation of the Root portion of the HepTuple code, the string given as the first argument to these functions was used for both, which a number of users found inconvenient. In particular, some users found it troublesome for the object name to be long enough to be fully descriptive of the histogram's physical content and very troublesome when the object name contained whitespace. Indeed, that was the main motivation for adding a member function to set the histogram title separately.

Another example has surfaced recently. Certain special characters - notably the slash "/" - provoked an exception objecting to an allegedly invalid histogram name. The problem is that histogram names are treated internally much like UNIX-style file names which may have an inplicit path-like structure prefixed with the slash as the separator between components of that path. The code carefully checks to see if a slash appears in the histogram name and objects because that slash will later be taken as a path component separator and be badly misinterpreted.

The solution is to use a simple, short string for the histogram object name and then set the title to something meaningful. The string argument to setTitle(const std::string&) is simply taken as given, stored blindly in the object's member data and presented to the graphics drivers later. There is no interpretation done and, consequently, that string may contain anything, including special characters.

The following code fragment will serve as an example,

			:
			:
//  Instantiate a Root manager

    fMan = new HepRootFileManager( "crashola.root" );
			:
//  Make a histogram with a simple name, then give it a useful title
			:
    HepHist1D & ecal = fMan->hist1D("ECAL", 50, 0.0, 1.0);
    ecal.setTitle("Electron E/p");
			:
			:

The point to all this is the following: The first argument to the hist1D, hist2D and histProf is indeed used as both the histogram name and title in the default case and all the restrictions on the name discussed earlier apply. However one can always use setTitle to redefine the title to any reasonable string with impunity. The implication is then clear. Use short, simple names and be creative with titles.