KAHIBARO
4.2. Object Names and Titles
Table of Contents
Object names
Every ROOT object that can be stored or managed in a directory, such as a file or a canvas, has a name. The name is a short string that uniquely identifies that object inside its parent directory. The name is not just a label for humans, it is also the key that ROOT uses internally when you save and retrieve objects from a TFile, a TDirectory, or a TCanvas pad.
Many ROOT classes inherit from TObject and therefore support names. In practice, you almost always encounter this when you create histograms, graphs, functions, and trees. The name is typically the first argument in the constructor. For example, a one dimensional histogram might be created as:
TH1F *hEnergy = new TH1F("hEnergy", "Energy spectrum", 100, 0.0, 10.0);
Here "hEnergy" is the object name. ROOT will use this name when you save hEnergy into a ROOT file or when it appears as a primitive on a canvas.
Names must follow some important rules.
ROOT object names must be unique within the same directory or list, must not contain slashes /, and are case sensitive.
Uniqueness is local. You cannot have two objects with name "hEnergy" in the same TFile directory or in the same TCanvas pad. However, you can have the same name in different directories, for example "hEnergy" in file1.root and another "hEnergy" in file2.root. If you try to write two objects with the same name into the same TDirectory, the second one overwrites the first unless you explicitly change the behavior.
Slashes are reserved by ROOT to navigate directory structures, so they cannot appear in object names. It is good practice to keep names simple, without spaces or special characters. You can use letters, digits, and underscores. ROOT treats names as case sensitive, so "hEnergy" and "henergy" are different objects.
Although you are not forced to follow any particular naming convention, a consistent scheme is very helpful in larger analyses. Typical patterns include prefixes for the object type and a short description of the content, for example hEnergy, hEnergyCalib, gResolution, fFitPeak. Choose names that are informative enough that you can guess what the object contains when you see the name in a file browser or when you list the contents of a TFile.
You can access and modify an object name through the GetName() and SetName() methods provided by TObject. For example:
cout << hEnergy->GetName() << endl; // prints "hEnergy"
hEnergy->SetName("hEnergyCalib");Renaming after creation is possible but should be used carefully, especially when the object has already been written to a file or stored in some container, because other code might refer to it by its original name.
In some cases, ROOT auto generates names if you omit them or pass an empty string. For histograms created interactively in the ROOT prompt without an explicit name, ROOT may assign names like "htemp". For anything beyond quick tests, it is strongly recommended that you set meaningful names explicitly instead of leaving the default, because automatically generated names are not stable and are not helpful when you later search for objects.
Object titles
While the name is mainly for ROOT and for programmatic access, the title is for humans. The title is a text string associated with an object that is typically displayed on plots, legends, and graphical interfaces. In many constructors, the title is the second argument. In the histogram example:
TH1F *hEnergy = new TH1F("hEnergy", "Energy spectrum", 100, 0.0, 10.0);
the string "Energy spectrum" is the title.
In contrast to names, titles do not need to be unique. You can give several histograms the same title if you like. Titles can contain spaces, punctuation, and LaTeX style syntax for Greek letters and mathematical symbols when used with ROOT text tools such as TLatex. For example:
hEnergy->SetTitle("Energy spectrum;E [MeV];Counts");
For histograms and graphs, the title string can also encode axis titles if you separate parts with semicolons. In the example above, "Energy spectrum" is the main title, "E [MeV]" is the x axis title, and "Counts" is the y axis title. This compact convention is specific to plotting classes in ROOT and is very convenient for quick setup of axes and labels.
You can modify or read the object title at any time with SetTitle() and GetTitle():
cout << hEnergy->GetTitle() << endl;
hEnergy->SetTitle("Calibrated energy;E_{cal} [MeV];Events");Changing the title does not change how the object is stored or identified in a file. It only affects how it appears in plots and browsers. This separation is important. Names refer to the internal key, titles to the user facing description.
Although titles are optional, they are extremely helpful for documentation. A plot with a meaningful title and labeled axes is much easier to interpret than one that only shows anonymous shapes. In a typical workflow, you pick short but descriptive names and more verbose and clear titles.
Finding ROOT objects
Since names are the keys used to store objects, they are also the main way to find objects again. Depending on where an object lives, ROOT offers different methods to retrieve it by name.
The first common case is ROOT files. When you create a TFile, write objects into it, and close it, ROOT stores each object with its name as the key. Later, you open the file and use Get() to retrieve objects:
TFile *f = TFile::Open("results.root");
TH1F *h = (TH1F*)f->Get("hEnergy");
Here "hEnergy" must match exactly the name you used when you originally created and wrote the histogram. If the name does not exist in the file, Get() returns a null pointer. Exact spelling, including case, is required.
You can get an overview of what is stored in a file or directory by listing its contents. For example:
f->ls();prints the names, classes, and sometimes titles of objects in the file. This is especially useful if you forgot the names or are exploring a file created by someone else. There is also a graphical ROOT browser that allows you to navigate files and directories interactively and see object names and titles.
Objects can also be stored in other containers, such as TDirectory objects inside a file or the list of primitives on a TCanvas or TPad. These containers provide methods to search by name as well. For example, if you drew several objects on a canvas and want to retrieve one by its name, you can do:
TCanvas *c = gPad->GetCanvas();
TObject *obj = c->FindObject("hEnergy");
FindObject() searches the list of primitives attached to the canvas and returns the first object whose name matches the string. You may need to cast the result to the appropriate type if you know what it is.
Similarly, each TDirectory inherits from TNamed and has methods to look up objects. In many analyses you will use the TFile interface directly, but internally TFile is a TDirectory, so the same logic applies. Using directories within a file allows you to organize large numbers of objects hierarchically, and you still retrieve them by name, but relative to the directory they are stored in.
When you do not know the exact name but know part of it, you can iterate over the list of keys or objects and filter by name or by class. For example:
TIter nextkey(f->GetListOfKeys());
TKey *key;
while ((key = (TKey*)nextkey())) {
if (TString(key->GetName()).BeginsWith("hEnergy")) {
cout << "Found: " << key->GetName() << endl;
}
}This kind of loop is useful for batch operations over groups of objects with a common naming pattern.
The ROOT object browser, which you can start from the ROOT prompt with:
new TBrowser();provides a graphical way to find objects in memory or in files. It shows object names and titles, the directory structure, and lets you double click items to draw them. This is particularly practical for beginners and for interactive exploration. You can use the browser to verify that objects are in the place you expect and have the names and titles you intended.
In summary, names are your primary tool to store and later find objects in ROOT, while titles help you understand and present them. A good habit is to always choose clear names that you can easily type and clear titles that you and your collaborators can easily read.
Views: 11