0. Content

1. Introduction

TMBTrees are a rather light-weight ROOT data format which allows you to analyze D0's data from within ROOT. They are much faster to read than thumbnails, and they are much smaller (TMBTrees contain less information than thumbnails - though most often that's sufficient for analyses). TMBTrees are created using TMBAnalyze_x, with one of its runTMBTreeMaker.rcp RCPs, often from thumbnails, e.g. from the common sample group. They are independent of D0's bulk of code (e.g. the "framework"); you only need a few packages to run it. This means you can analyze data even on your laptop (even on your windows laptop, the macros only work with ROOT's win32gcc build, so you can even use the free GCC as compiler).

• makers, which create TMBTrees (you probably don't care about them, but if you do: take a look at the tmb_tree_maker and tmb_tree_trigger_maker packages),
• classes that the TMBTrees consist of, e.g. TMBVrts, TMBJets etc.
• a ROOT macro that tells ROOT about these classes (MakeTMBTreeClasses_so.C)
• example macros showing how to analyze TMBTrees (TMBTree_bu.C and TMBTree_bu.h).

2. Prerequisites

$ setup gcc 
$ setup root v4_00_04a_eh

First of all, we need ROOT, which you can either download to your box or simply setup, either by setting up root itself (which lets you pick the version, ROOT >=v4.0 is preferred) or by setting up D0RunII. Make sure to also setup gcc corresponding to your root version. If it doesn't show up in the -q argument for setup (the "qualifier") for the root version (e.g. -q GCC_3_1:opt:thread) then hopefully the current GCC is the one you need.

You can see what's supposed to happen in the "screen shot" on the right; it's not a picture, so you can cut and paste from it.

$ setup d0cvs
$ kinit
$ cvs co -r p16-br-05 tmb_tree
[output of file names being checked out]
$ cvs co -r p16-br kinem_util
[output of file names being checked out]

Then we need the TMBTree code. In this document I will assume that you're using post-p14 code - it's irrelevant what the tmb_trees were created with. You need to have access to d0cvs to get the necessary code - on clued0 or d0mino you can just setup d0cvs and get a kerberos ticket; otherwise see your local experienced D0 collegue. Check the packages tmb_tree and kinem_util out of cvs (for post p16 you'll also need met_ztil). As an example I request the tags p16-br-05 and p16-br; whereas kinem_util's tag should be fine, tmb_tree's might change. Look at the TMBTree class doc page to find the latest major tag for p16.

That's it already!

3. Building the Library

$ root
  *******************************************
  *                                         *
  *        W E L C O M E  to  R O O T       *
  *                                         *
  *   Version   4.00/03     25 March 2004   *
  *                                         *
  *  You are welcome to visit our Web site  *
  *          http://root.cern.ch            *
  *                                         *
  *******************************************
Compiled for linux with thread support.
CINT/ROOT C/C++ Interpreter version 5.15.128, Mar 16 2004
Type ? for help. Commands must be C++ statements.
Enclose multiple statements between { }.
root [0] .x tmb_tree/macros/MakeTMBTreeClasses_so.C
INFO: Using package tmb_tree from ./
INFO: Using package kinem_util from ./
INFO: Using macro ./tmb_tree/macros/TMBTreeClasses.C
Info in <TUnixSystem::ACLiC>: creating shared library 
/path/TMBTreeClasses_C.so

This is again very easy: enter root, and run the macro tmb_tree/macros/MakeTMBTreeClasses_so.C (and a hint: this name is so long and ugly that you don't want to type it. Instead just type tmb_tree/m<TAB>/M<TAB>, and root will fill in the rest of the name, like in a shell). If you don't get a "1" at the end, but Compilation failed!, then the code has a bug. Go to the o noooo part to see what to do.

The MakeTMBTreeClasses_so.C macro you were calling does not only build the library - it also loads the library and it changes some ROOT settings that are needed to use TMBTree code. Many other libraries that use TMBTree code also rely on this macro. So don't forget to execute this macro whenever you start a new ROOT session, before doing any work on TMBTrees! The next time you start it the library will already be around, so the macro will just load it and change ROOT settings - which makes it a lot faster.

Now you have the library, and ROOT has loaded it. ROOT now knows about all the TMBTree classes. You can for example create a new TMBJets object: jet=new TMBJets(). Or check the plentitude of available classes by typing TMB<TAB> at a root prompt, and see what ROOT suggests as possible completions. Okay, enough playing around, now lets look at some data!

4. Running an Analysis Macro

root [1] .L tmb_tree/macros/TMBTree_bu.C+
root [2] ch = new TChain("TMBTree");
root [3] ch->Add("tmb_tree.root");
root [4] bu = new TMBTree_bu(ch);
root [5] bu->Loop();

First, we load the analysis macro, the class TMBTree_bu. The trailing "+" means that the code is compiled, which makes it more stable, and faster, and which allows us to find bugs in the code. To analyze something you'll first need a tmb_tree.root file. If you don't know where to find one, download one here.

Instead of showing you the simple case of one single tmb_tree.root file, we'll go through the much more common case of analyzing a whole list of files. For that, we create a TChain, which needs to know the name of the trees it will contain (and the names for TMBTrees is, well - "TMBTree"). A TChain is a ROOT class, so you can get documentation on that at http://root.cern.ch/root/html/TChain.html. Here's a short summary: a TChain behaves like a simple TTree (the thing that's in the tmb_tree.root files - that's where their name comes from), only it extends over multiple files. For now, we'll only add one file to the TChain - but you can simply call ch->Add("filename.root") for all the files you want to run your analysis macro on.

Now we have a TChain, filled with the tmb_tree.root files we want to analyze (which is, in our example, just one). In line root [4], we create a TMBTree_bu object, and we pass our TChain, so the TMBTree_bu object knows what to analyze. Then we tell the TMBTree_bu object to loop over all entries (which are events) in the TChain, and analyze each event.

Look at tmb_tree/macros/TMBTree_bu.C - you need to understand how to retrieve data from the tmb_tree, and what TMBTree_bu does, otherwise you won't be able to analyze your data. Let's go through the different parts. Ignore the method called TMBTree_bu::Walk(...); we'll skip to TMBTree_bu::Loop() directly. First, several histograms are created. Histograms count values; we use ROOT classes, so have a look at ROOT's documentation of the histogram classes. Then we loop over all entries - well, almost: some versions of the TMBTree_bu.C macro have a numEntriesMax value, which will stop the analysis after the first numEntriesMax number of events.

And now all these histograms are filled, with values from different parts of the tmb_tree.root file. We'll just look at one single part; you'll be able to extrapolate from there.

Let's look at the very simple part called "Vertices":

In the first line, an iterator is created; it allows to loop over lists, and lets us access the next entry. It is told that it should loop over fVrts, which is a TClonesArray. Look at TMBTree_bu's header, tmb_tree/macros/TMBTree_bu.h: It says TClonesArray* fVrts; // Container of Vertices. Of course you want to know what a TClonesArray is; as usually you should look at the ROOT documentation for that class. It's an array - but what does it contain?

There's a simple 1:1 translation between the TClonesArrays and their containers; look at the TMBTree class documentation - which class is it? Of course: TMBVrts. That's why in line 2, a TMBVrts pointer is created. It is set in line 3, in the while loop: as long as the iterator returns a next vertex, vrts will point to it. while ((vrts=(TMBVrts*)iVrts())) looks a bit complicated, so I'll split it up into non-c++ code to make it easier to read:

iVrts, our iterator, has a method called operator() (on an object named iVrts you call it as iVrts()), which returns the next entry (line a). The first time it gets called, it returns the first entry, the second time the second entry etc. If there are no more entries, it returns 0. The entry it returns is a pointer to ROOT's basic object, a TObject* (line b). This returned pointer needs to be converted ("cast") into a TMBVrts* (line c) - that's what we store in fVrts. The while loop now simply checks whether the iterator returned something useful, or 0 (line d). If it returned 0 we stop the loop (while(0) finishes the while loop).

Back to our original piece of code: in line 4, we have vrts pointing to a TMBVrts object, and we fill a histogram with its z position - look at TMBVrts' documentation to see what "vz()" stands for. The we go back to line 3, extracting the next vertex into vrts, until we've looped over all vertices of this event.

That's all there is. You might want to look at TPhysObj, the base class of most TMBTree objects. Its methods are available for all derived classes, too; for almost all of the classes you can e.g. get the TLorentzVector (a very handy ROOT class) using lorentz_vector().

Now remove all the lines of TMBTree_bu::Loop (maybe except for the line while(GetEntry(entry++))) and write your own analysis: create a histogram, and fill it with some value. Usually, you don't need all the objects that are in a TMBTree. To speed up your analysis you should tell ROOT what to read: fChain->SetBranchStatus("*",0); tells ROOT to not read anything, and the line fChain->SetBranchStatus("Vrts*",1); re-enables reading the vertices (don't forget the "*" at the end!). More precisely, it tells ROOT to read the data that's contained in the branch "Vrts". You can find the branch name that contains the data for fVrts by looking into the header file TMBTree_bu.h: TMBTree_bu::Init() contains several SetBranchAddress statements, one of them sets fVrts to whatever the branch "Vrts" contains. The comment at the beginning of TMBTree_bu::Loop() reminds you how to read only parts of the TMBTree.

This web page has now done its duty: you understand how to analyze TMBTrees, and where to look for further help. As always when running into questions, you should ask your colleagues or neighbors (yes, even the people from those other offices next to yours, the ones you never talked to!). If that takes too much time or doesn't help: send an email to d0rug@fnal.gov, telling them what you use (code versions, files, where your code is), what you try to do, how you try to do it (as in "I typed ..."), and why you think the results you get are not the results you want.

Good luck!

5. O nooooo

You should complain if something doesn't work, instead of wasting time to fix it yourself: send an email to d0rug@fnal.gov. Even if you already found a work-around: people need to know if something doesn't work, so please tell the developers. If your problem is with a certain TMBTree class, you can look at the cvsweb browser which shows all the tmb_tree files, together with the person who last changed something. Send him or her an email; (s)he might know how to solve your problem. If you suspect your problem to be a ROOT one, or if you can't find out how to do something in ROOT, send email to aboutroot@fnal.gov; a lot of ROOT users and some of the ROOT developers are reading this email list, so it's a fast source of good help.