CMUAnalysis/Common contents

This package contains common analysis tools used by the Carnegie Mellon group.
All functions and objects defined here use the SUSYNtuples used by the SUSY
Photons subgroup as the input source.

===============
==== SETUP ====
===============

This package can be used in three different modes:
[1] With CMSSW - full functionality
[2] Without CMSSW but with SUSYNtuplizer library - making mini-ntuples from SUSYNtuples
[3] Without any external package - working with mini-ntuples only
See below for the setup instructions for each option.

[1] Setup with CMSSW

Follow the instructions on SWGuideSusyNtuplesRA3 twiki and set up the latest
version of the SUSYNtuplizer package:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
$ cd CMSSW_5_3_8_patch3/src
$ git clone -b master https://github.com/CMSSUSYPhotons/SUSYPhotonAnalysis.git
$ cd CMSSUSYPhotons git checkout cms538_v1
$ cd ../
$ (add other packages)
$ scram b -j8
$ cmsenv
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Set up ROOT to load the libraries by default:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[Add the following lines to rootlogon.C (create one anywhere if there isn't yet)]

  if(gSystem->DynamicPathName("libSusyEvent.so", true) != 0){
    gSystem->Load("libSusyEvent.so");
    gSystem->Load("full_path_to_this_directory/libCMUCommon.so");
  }
  TString CMSSW_BASE(gSystem->Getenv("CMSSW_BASE"));
  if(CMSSW_BASE != "") gSystem->AddIncludePath("-I" + CMSSW_BASE + "/src/SusyAnalysis/SusyNtuplizer/src");

[If newly creating rootlogon.C, add the following line to ~/.rootrc]

Rint.Logon: path_to_rootlogon.C
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Build the library:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
$ cd this_directory
$ make
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

[2] Setup without CMSSW but use SUSYNtuples library

Check out the latest SusyNtuplizer package to a local directory:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
$ git clone -b master https://github.com/CMSSUSYPhotons/SUSYPhotonAnalysis.git
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Compile the library:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
$ cd SUSYPhotonAnalysis/SusyNtuplizer/macro
$ make
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Set up ROOT to load the libraries by default:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[Add the following lines to rootlogon.C (create one anywhere if there isn't yet)]

  gSystem->Load("full_path_to_SusyNtuplizer/macro/libSusyEvent.so");
  gSystem->Load("full_path_to_this_directory/libCMUCommon.so");
  gSystem->AddIncludePath("-Ifull_path_to_SusyNtuplizer/src");

[If newly creating rootlogon.C, add the following line to ~/.rootrc]

Rint.Logon: path_to_rootlogon.C
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Edit the Makefile in this directory:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
SUSYNTUPLIZER=full_path_to_SusyNtuplizer/src
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Build the library:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
$ cd this_directory
$ make
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

[3] Setup without external packages (Standalone mode)

Set up ROOT to load the libraries by default:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
[Add the following lines to rootlogon.C (create one anywhere if there isn't yet)]

  gSystem->Load("full_path_to_this_directory/libCMUCommon.so");

[If newly creating rootlogon.C, add the following line to ~/.rootrc]

Rint.Logon: path_to_rootlogon.C
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Build the library:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
$ cd this_directory
$ make standalone
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

==================
==== CONTENTS ====
==================
"S" after the file name indicates that the content of the file can be used in the standalone
mode.

[ObjectVars.h/cc] S
Defines the "mini-ntuples" variables for 5 objects: Photon, Electron, Muon, Jet, and Vertex
as simple C++ classes. The constructors of the classes in the cc file are automatically
generated through the generation tool (see below). The rest of the class implementation
has to be given by hand.

The classes defined here can be used in the analyses as simple data containers (all data
members are public), but are also used to extract the information from the SUSYNtuples
during the mini-ntuples production, via the function set(), or the constructor that calls
the set() internally. See e.g. line 257 of SimpleEventProducer.cc.

[ObjectTree.h/cc] S
Declares the arrayed versions of the object classes and the controling class ObjectTree.
All of the contents of the files are automatically generated by generateObjectTree.py tool
described below.

The choice of creating an arrayed version of the object classes, instead of storing e.g.
vectors of objects, comes from the requirement that the mini-ntuples should be a flat
root-tuple. If we were to store e.g. std::vector<PhotonVars> as a tree branch, we would
have to compile and link a library to ROOT before the file can be read. By using the array
classes, the variables are stored as simple arrays of basic types.

At the analysis time, one can again use the array classes to handle the objects as whole
entities, rather than a collection of scattered ints and floats. The example usage is given
in https://twiki.cern.ch/twiki/pub/CMS/MiniNtuple/sampleAnalysisWithObjTree.cc

[generateObjectTree.py] S
A utility python macro to automate the generation of necessary overheads for the
ObjectVars/ObjectTree. It takes the ObjectVars.h/cc as inputs and writes the parts of the
class implementations that do not require human intervention.

[ObjectSelector.h/cc] S
Provides the standard object selection functions. The cuts are based on 2012 POG
recommendations.

All functions of the class are static and takes a XYZVars object and the selection type as
the arguments. The selector is used internally in the XYZVars::set functions to set the
various quality flags of the objects. The third optional argument of the functions give
the result of each quality cuts in the form of std::bitset.

[Utilities.h/cc] S
Utility functions that can be used in analysis.

[SimpleEventProducer.h/cc]
Defines a class that "translates" the SUSYNtuple events into mini-ntuples events. In the
default setup, the class produces two trees holding object variables and one tree holding
event-wide variables. The two object trees differ in whether quality selections are applied
or not; allObjects tree holds every object that appeared in the SUSYNtuples, whereas the
selectedObjects tree holds only the ones that passed the quality criteria (configurable).
The third tree, eventVars, contain variables such as trigger results and missing Et, which
does not depend on the specific object selection.

[produceSimpleTree.cc]
Defines a function that produces "mini-ntuples" from SUSYNtuples. The function is invoked
with the following arguments:
Input (RA3) file name, Output (mini) file name, PU scenario name, flag to fill selected
objects, flag to fill all objects, flag to fill PF information, flag to fill trigger
events (if available in RA3). Passing a non-empty PU scenario name will trigger the
function to run in "MC" mode. In other words, if running over MC samples, a correct
PU scenario name (e.g. S10, PU50) must be given. If running over real data on the other
hand, this argument must be an empty string.

[getLumiList.cc]
A function that dumps the list of luminosity blocks in a given dataset into JSON format.

[genDecayFilter.cc]
A function that skims the MC events by their decay chain. Requires an additional package in
github.com/yiiyama/Toolset.git

[puReweighting_2012.root] S
A ROOT file that contains the reweighting factor that mathces the MC to the full 2012 PU
distribution. Weights should be stored as a TH1 object with name weight[PUName] where
PUName is the PU scenario name. Details of each PU distribution are found in the twiki
PdmVPileUpDescription.

===============
==== USAGE ====
===============

The class objects are compiled into a library and can be used from any user-defined
functions. The last three files, which define the examples of such functions, need to be
compiled from ROOT:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
$ root
root [0] .L produceSimpleTree.cc+
root [1] TChain* susyTree = new TChain("susyTree");
root [2] susyTree->Add("susyEvents*.root");
root [3] produceSimpleTree(*susyTree, "miniNtuples.root")
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

To update the mini-ntuples content:
If you wish to add a variable to the object trees, update the corresponding class definition
in the ObjectVars.h file. Then give the implementation (how the variable should be filled from
SUSYNtuples) in the ObjectVars.cc file, and run the code generator before compiling:
$ python generateObjectTree.py
$ make

If you instead wish to add a variable to the event tree, update the EventVars struct definition
in the SimpleEventProducer.h file, and give the variable implementation somewhere proper in the
produce() function in SimpleEventProducer.cc file. You will have to compile with
$ make
in this case too.