d0root_example

This package contains code that shows you how to use d0root in the TMB, TMBTree, and top_analyze (object reader) environments. This page contains instructions for how to build and run in each of the environments, and a short list of what directions I'm hoping to push this package. In particular, several d0root based source files are run on all formats of data.

What is in this Package

The directories

• macros - contains the outter-shell code for running on the TMBTree.
• src - contains the code for running the TMB/framework shell code as well as the common code.
• d0root_example - header files
• bin - Build the TMB executable.
• top_tree - the infrastructure code to run top_tree based tagging analysis.
• sa_tmb_tree - code to build an executable that runs over TMBTrees (instead of running from within root, as the macros guys do).

The Common Code

There are two functions with d0root code that you can start with to do various tasks. Both are located in the src directory. Both are passed the ReadEvent object as an argument. The ReadEvent header can be found in d0root_analysis/read_event/ReadEvent.h -- it is an abstract class. Use it to get lists of jets, tracks, etc. The objects themselves can be found in d0root_analysis/objects.

• loop_over_jets_common.cpp - Very simple function that gets the list of jets in the event and prints out pt, eta, and phi.
• loop_over_PV_common.cpp - Simple function that will re-vertex using the p14 certified PV vertex and min bias selection.
• loop_over_btags_common.cpp - More complex function that implements and runs the tagging algorithms (SVKalman, JLIP, CSIP, and SLT). Please note this code is not the official way to run the algorithms. The BID group is working on a package to do that, but it isn't ready yet.
  • loop_over_btags_common contains the code to extract jets, tracks, and the PV from the event.
  • CSIPExample, JLIPExample, SVKalmanExample, and SLTExample contain code to run the taggers given the above list of tracks, jets, PV, and muons for SLT.
  • btagsCertExample contains code to instantiate a particular btager using the btags_cert package. NOTE: unless you are planning on getting into the dirty details of the btagging, it is recommended to use the btags_cert package rather than the raw taggers themselves. The interface is much simpler, and all the behind the scenes work is taken care of.

Environment Specific Code

Each environment -- TMB, TMBTree, and top_tree -- requires different infrastructure code to load in the event, loop over the events, and convert the events to d0root format. This code is unique to each environment and calls the common code routines listed above.

• TMB - The executable D0RootExample_x is build (in the bin directory). Two of the objects listed are RegD0RootExample and RegD0RootExampleBTag. Further, note that the d0root_tmb package Regd0rootPkg is also included. The source code for the D0RootExample and D0RootExampleBTag packages calls the common interface directly. In the rcp (or for btagging) that runs the executable you have to be sure to run the D0RootPkg before anything that uses d0root! There is no code for the PV finder, but if you use the btagging environment code as a shell (and the instructions) it will work fine.
• TMBTree - When running directly in root you have to make sure to build all the objects into sharable libraries. Other than d0root_btag (which should be built with gmake d0root_btag.all), everything is build by root in the compile.C files (found in d0root_analysis root directory, for example). The first part of the infrastructure, loop_over_jets and loop_over_btags (found in the macros subdirectory), calls all these compile routines and make sure everything is loaded. The second half of the code loops over all events in the TMBTree and calls the common code. This can be found in loop_over_jets_ana and loop_over_jets_btag, also found in the macros subdirectory.
• Stand Along TMBTree - If you don't want to mess with shared libraries or run under root, but would rather just use an executable, this is the way to go.
• top_tree - Running in this environment is also most often done by executable. Unlike a framework executable, however, the main program is fairly simple and just calls the common code. The code, top_tree_example and top_tree_btag_example, can be found in the top_tree subdirectory. There is no code for the PV finder, but if you use the btagging environment code as a shell (and the instructions) it will work fine.

Package Tags

While d0root is undergoing development, it can be hard to get a working set of packages together. And getting them checked out is even more painful. We used to maintain a list below, but it turns out it was often out of date vs the what really worked. In stead, we've moved the information into a file called checkout_bid.sh that resides in the btags_cert package. It is a script that will automatically check out the required packages for you for a given format.

Package	Tag
d0root_example	v00-02-03
btags_cert (p16)	v00-02-09
btags_cert(p14)	p14cert-br-07

Notes:

• Both btags_cert and d0root_example don't build out of the box any longer. You have to run setup scripts to configure the packages first. Please see the Instructions section below.
• There is a script in d0root_example/scripts/build_and_run_all_formats.sh. It has all the code below, written as a bash script. I use it to make sure that I've got all formats working. It does run all the executables, and uses input files that may move around from time-to-time, so keep your eyes open if you are trying it out.
• All package tags are verified to work in p14.06.00 and p14.07.00.

Instructions

Scripts have been created to aid with downloading and running these packages. For all formats, follow the following instructions. Replace <format> with either tmb, tmb_tree, or top_tree. Release shoudl be the release this is used for. For p14 this was last tested on p14.06.00, and for p16 it was last tested on p16.06.00.

setup D0RunII <release>
setup d0cvs
newrel -t <release> root_example
cd root_example
d0setwa
addpkg d0root_example <tag-from-table>
addpkg btags_cert <tag-from-table>
d0root_example/checkout.sh <format>
btags_cert/checkout_bid.sh <format>

Next follow instructions for the particular format. Make sure you do the d0setwa or you'll be sorry 9-ways to heck. When you forget this a lot of times the error messages you get later are... weird.

Running on a TMB

This code was last tested on p14.06.00. The code is known not to work on some earlier versions of p14 due to muo_candidate versioning problems (before p14.05.01). You'll need a TMB file stored somewhere.

gmake
setup d0tools
rund0exe -exe=D0RootExample_x -rcp=runD0RootExampleTMB.rcp \
   -rcppkg=d0root_example -localbuild -localrcp -localfwkrcp \
   -filelist=test.dat -num=10

The file test.dat contains the listing of the TMB files you want to run over (the standard rund0exe format). When you run you should see an output buried in your .out file that looks something like this one. Use the framework rcp file runD0RootExampleBTagTMB.rcp to run the btagging instead of the simple jet looping.

The setenv command is required only when running the btagging code. d0root_btag is built as a shareable library, and so must be in the executable path or it won't be found when running. We are working to see how we can get around this without breaking too much code.

During the build of d0root_analysis, under KCC, you'll get a large number of warnings for unreachable code. This is known, and is an incompatibility between the compiler and rootcint, the code generator in root. Ignore them. Under gcc this works fine.

The infrastructure code is in the D0RootExample.cpp class.

When you are ready to create your own analysis environment, copy the package D0RootExample, and make sure to copy the OBJECTS file from the bin area, and the run rcp from the rcp area. In particular, you must include the d0root_tmb package d0rootPkg in the execution stream before your new package (see the file d0root_example/rcp/runD0RootExampleTMB.rcp).

The packages:

• d0root_analysis - Contains the basic d0root infrastructure.
• d0root_tmb - Contains the shell code that converts the data from TMB format to d0root format.
• d0root_btag - Contains the SVKalman tagging algorithm.
• d0root_example - The example.
• bc_csiptagger - Contains implementation code for the CSIP tagger
• d0root_csip - Contains the d0root interface to the CSIP tagger
• d0root_jlip - Contains the JLIP tagging code.
• d0root_slt - Contains the SLT tagging code.
• top_tree_to_d0root, top_tree_reader, top_tree - Not required to build this example, but are required to build the d0root example. If you wanted to build your own example in another package and weren't planning on building top_tree support, you'd not need to include these packages! You can even leave them out from above, but it would be best to remove the top_tree line from the SUBDIRS file or you'll get plenty of errors.
• cal_event_quality - Contains code to determine calorimeter object quality.

It shouldn't be a problem to run on the DST. Modify the runD0RootExample.rcp or runD0RootExampleBTag.rcp so that it doesn't do the unpacking.

Running on a TMBTree

The code is known not to work on earlier versions of p14 than p14.06.00 due to muo_candidate versioning problems.

You'll need a TMBTree file stored somewhere. Start with the following:

gmake d0root_btag.all
gmake d0root_jlip.codegen
gmake d0root_analysis.codegen
[p14]cp tmb_analyze/macros/MakeTMBTreeClasses_so.C .
[p16]cp $SRT_PUBLIC_CONTEXT/tmb_tree/macros/MakeTMBTreeClasses_so.C .
root -l -q MakeTMBTreeClasses_so.C
root -l -q d0root_example/macros/loop_over_jets.C

You need repeat only the last line each time you want to run your analysis code. The first three lines are all initialization that is needed only once per directory (note that you'll get some warnings you can ignore!). You'll have a screen full of lines that looks like this. Use the loop_over_btags.C file to run simple btagging instead of simple jet looping. Use the loop_over_PV.C file to run a simple PV finder example.

The d0setwa command is crucial. You'll be very sorry if you don't issue it, and the errors you get will never lead you to think that this is what you've forgotten!

The two infrastructure files, loop_over_jets.C and loop_over_btags.C differ only in loading the d0root_btag sharable library.

The current version is known not to work on p15 and the head because of the change in the location of the TMB MC classes (moved from the mc_analyze to the tmb_tree package). This is easy enough to change. Also, the MakeTMBTreeClasses_so.C has moved from tmb_analyze to tmb_tree in p15 and the head.

The packages:

• d0root_analysis - Contains the basic d0root infrastructure
• d0root_tmbtree - Contains the TMBTree -> d0root converter routine
• d0root_example - Contains the example
• bc_csiptagger - Contains implementation code for the CSIP tagger
• d0root_csip - Contains the d0root interface to the CSIP tagger
• d0root_jlip - Contains the JLIP tagging code.
• d0root_slt - Contains the SLT tagging code.
• d0root_btag - Contains the SVKalman algorithm
• tmb_tree - Contains the TMBTree objects (as well as their Makers in p14). Has modifications vs the base.
• tmb_analyze - Contains macros to run the TMBTree analysis.

Running on a top_tree

This code was last tested on p14.08.00. The code is known not to work on earlier versions of p14 due to muo_candidate versioning problems. You'll need a top_analyze file stored somewhere.

gmake
top_tree_example \
  /rooms/barbershop/projects/MUqcd/p14.03.02/sk70/output_00.root

The gmake will have a few warnings about bad conversions and unreachable code, but you can ignore them. The executable takes one command-line-argument -- the location of the top-tree file.

Use top_tree_btag_example to run the btagging code.

The setenv command is required only when running the btagging code. d0root_btag is built as a shareable library, and so must be in the executable path or it won't be found when running. We are working to see how we can get around this without breaking too much code.

The infrastructure code can be found in top_tree/top_tree_example.cpp and its btag counterpart (they are almost identical, of course).

The Packages:

• d0root_analysis - Contains the basic d0root infrastructure.
• d0root_example - Contains the example
• d0root_btag - Contains the SVKalman tagging algorithm.
• d0root_tmb - Required to build d0root_example, but no code used in this example.
• bc_csiptagger - Contains implementation code for the CSIP tagger
• d0root_csip - Contains the d0root interface to the CSIP tagger
• d0root_jlip - Contains the JLIP tagging code.
• d0root_slt - Contains the SLT tagging code.
• top_tree - Contains the objects present in the top tree
• top_tree_reader - Contains boiler plate code to aid with reading in the top tree in object form.
• top_tree_to_d0root - Contains code to convert the top tree objects into d0root objects.

Running on a TMBTree Stand Alone

To build an executable that runs on TMBTrees as input, follow the below instructions. The below instructions should work, but they fail when building linked_physobj. I'll update as soon as I found out why this is failing.

setup D0RunII p14.06.00
newrel -t p14.06.00 root_example
cd root_example
d0setwa
addpkg xxx <tag> All tags marked "Y" in the "Required to build d0root example and sa TMBTree*" column?
gmake
run the resulting executable.

This process currently hangs when trying to build linked_physobj -- actually it doesn't hang, it just takes more than 20 minutes to generate the d0om files (see the p14.06.00 log file <works only if you are in the fnal.gov domain). I'm afraid I didn't have the patience to wait this out.

Notes

Running p15

This information is preliminary; d0root isn't officially supported on p15 or the head yet (p14 is the BID's focus right now). All testing was done in p15.07.00

• Running on TMB
  • in runD0RootExample.rcp, change the unpack_with_Builder rcp to UnpThumbNail.
• Running on top_tree
  • No changes required
• Running on TMBTree
  • link to tmb_tree rather than tmb_analyze
  • Change all occurances of mc_analyze to tmb_tree in TMBRootReader.h in the d0root_tmbtree package.
  • You'll get lots of crazy looking errors from the root -l -q Makexxx command. You can ignore them, that is just gcc being very strict during the build. But it should work in the end.

To Do

This is a short list of things that are (I hope) coming for this package.

• Add tagability to the tagger examples.