#################################################################
                    Physics Analysis Code
#################################################################

Physics Analysis Code (PAC) is an attempt to organize multiple analyses using
a common set of tools rather than having random analysis areas scattered
throughout. It main design requirements were:

1.  Builds using fully compiled C++ outside of ACLiC
2.  Platform independent (at least MAC and Linux)
3.  Modular to facilitate reusable code

This README is organized as follows

1.  Install instructions
2.  Running instructions
3.  Description of modules
4.  Building the code

To analysis specific instructions can be found in the sub folder
analysis/<analysis name> (e.g. analysis/ss2012).


#################################################################
                  1. Install Instructions
#################################################################

Requirements:
----------------------------------------------------------------

You must have a version of ROOT installed that is relatively recent. I have
only tested this with 5.30.0X and greater. The one we use on the uaf is located
at /code/osgcode/fgolf/5.30-patches and can be setup using the command

source /code/osgcode/fgolf/5.30-patches/bin/thisroot.sh 

Also, you must have the BOOST c++ libraries installed somewhere. We have only
tested PAC with version 1-49-0. On the uaf, there is a version checked out at
/home/users/rwkelley/code/boost/1.49.0 so you won't need to install this. If
you are installing PAC on a different system or your laptop, you will need to
install the BOOST c++ libraries. Instructions to setup boost are below.

Setup:
----------------------------------------------------------------

To check out the code:
git clone https://github.com/fgolf/pac pac

We will refer to the directory you chose to install PAC to as simply PAC (e.g.
/home/users/rwkelley/Development/pac == PAC).

If you need to install the BOOST c++ libraries, then run the following script:

cd PAC
./tools/setup_boost.sh

NOTE: This step is not necessary if you are running on the uaf since
there is a version of boost that all SnT can access installed at
/home/users/rwkelley/code/boost/1.49.0.

Next, we run the setup script. This will check out off the code from
CMS2/NtupleMacros that is required to run the analysis code.

cd PAC
source tools/env.sh
./tools/setup_pac.sh 

The last line of output for this should be "build successful" for a successful install.


#################################################################
                2. Running Instructions
#################################################################

PAC creates both command line executables and shared libraries that you can
loaded in ROOT and use interactively (in the interpreter or in ROOT scripts).

Any time you use PAC, you will need to source the env.sh script to setup the
basic environment (or put it in your .bashrc).

cd PAC 
source tools/env.sh

In order to use PAC interactively in ROOT, you will need to call the following
whenever you launch ROOT (or put it in your root logon script):

.x $PAC/tools/load_pac.C

You are now ready to run the analyses.  Currently there are:

- $PAC/analysis/ewkino2012           :8 TeV ewkino analysis
- $PAC/analysis/ss2012               :8 TeV SS analysis
- $PAC/analysis/ttv2012              :8 TeV ttV analysis
- $PAC/analysis/RpvStop2012          :8 TeV RPV stop analysis
- $PAC/analysis/FakeRateAnalysis2011 :Deprecated 7 TeV dilepton fake rate study (mostly directed for the SS analysis)
- $PAC/analysis/FakeRateAnalysis2012 :8 TeV dilepton fake rate study (mostly directed for the SS analysis)
- $PAC/analysis/EfficiencyStudy      :8 TeV simple lepton efficiency study
- $PAC/analysis/TagAndProbe          :8 TeV simple tag and probe setup

For instructions on running the specific analyses, see the README files in the specific analysis directories.


#################################################################
                 3. Description of Modules 
#################################################################

This code is organized as follows:

#PAC/tools:
----------------------------------------------------------------

Low level tools/files needed to install and run PAC.  This includes:

- Makefile.common:             common makefile that all the makefiles includes
- convertGoodRunsList_JSON.py: converts json file to a flat text file.
- env.sh:                      setup environment variables needed by PAC.  This needs to sourced every time you want to use PAC.
- index.php:                   this is a nice script that makes a folder with plots look nice when viewed from a browser.  
                               This is used by packages/RootTools.
- load_pac.C:                  ROOT script to setup PAC libraries for use with CINT 
- makeCMS2ClassFiles.C:        a script to make a looper include file (e.g. CMS2.h/cc)
- setup_boost.sh:              setup the boost C++ libraries
- setup_pac.sh:                setup PAC for the first time

The following files are used by BOOST Build.  They are described below.
rootcint.jam
default-install.jam
build_all_bjam.sh


$PAC/packages:
----------------------------------------------------------------

reusable libraries that are independent of any analysis

- RootTools:     histogram and other root based tools.  This strives to be analysis independent.
- AnalysisTools: analysis independent tools but uses CMS2.
- FakeRateTools: tools for the dilepton fake rates derivation and studies.
                 I put this here so that other analyses may want to use it but right now this is
                 mostly for the dilepton analysis.
- cms2:          The header file for cms2 loopers (CMS2.h/cc)
- FGTools:       Frank Golf's original analysis code. Some of this is duplicated
                 and we are slowly removing the duplicates (but this is low priority).

$PAC/externals
----------------------------------------------------------------

An "external" library is any code that is not maintained by PAC but we use
extensively. The setup script checks/downloads these libraries from there
various places and puts it all under $PAC/external/source. We do not maintain this code
and so it is not checked into our cvs area.

Under $PAC/external/build is all the scripts, Makefiles, etc. to build and link the code for PAC.

The current external libraries are:

- SimpleTable: A simple table class to print tables of numbers and strings
- cms2_core:   CMS2/NtupleMacros/CORE
- cms2_tools:  CMS2/NtupleMacros/Tools (contains MiniFWLite)
- cms2_frb:    CMS2/NtupleMacros/fakeRAte/myBabyMaker.{h,cc} which are used to make the fake rate babies
- root:        ROOT

$PAC/analysis
----------------------------------------------------------------

- $PAC/analysis/ewkino2012           :8 TeV ewkino analysis
- $PAC/analysis/ss2012               :8 TeV SS analysis
- $PAC/analysis/ttv2012              :8 TeV ttV analysis
- $PAC/analysis/RpvStop2012          :8 TeV RPV stop analysis
- $PAC/analysis/FakeRateAnalysis2011 :Deprecated 7 TeV dilepton fake rate study (mostly directed for the SS analysis)
- $PAC/analysis/FakeRateAnalysis2012 :8 TeV dilepton fake rate study (mostly directed for the SS analysis)
- $PAC/analysis/EfficiencyStudy      :8 TeV simple lepton efficiency study
- $PAC/analysis/TagAndProbe          :8 TeV simple tag and probe setup

$PAC/lib
----------------------------------------------------------------

Directory to hold the shared libraries.

$PAC/bin
----------------------------------------------------------------

Directory to hold the object files and executables.


#################################################################
                  4. Building the Code 
#################################################################

There are two ways to build this code: using GNU Make an BOOST Build.

GNU Make (deprecated)
----------------------------------------------------------------

There makefiles are organized hierarchically starting with the Makefile in the
PAC directory. To do a complete build of the code, you call make from this
directory anytime the code needs to be compiled:

cd $PAC
make

OPTIONAL: If you are working in a specific package or analysis and you have not modified
code in others modules, you only need to call make from that current directory:

cd $PAC/analysis/ss2012
make

The advantage is it doesn't search the all of PAC to determine what needs to
get rebuild; however, if you have changed something in another module, these
changes will not get picked up. If you have modified multiple modules, you
should call make from the PAC directory.

To build PAC with debug symbols, you should do a clean build with the debug symbols turned on:

cd $PAC/analysis/ss2012
make clean
make DEBUG=1


BOOST Build (supported method)
----------------------------------------------------------------

This is a build system that is a specific to C++ and offers more off the
shelf features than GNU Make. The advantage is it requires little effort to
configure; however, the disadvantage is that it is not the most intuitive
language (Jam).

From the analysis or package you wish to use, simply call:

cd $PAC/analysis/ss2012
bjam release

To build a debug version:

cd $PAC/analysis/ss2012
bjam debug

You can learn more about BOOST build at: http://www.boost.org/boost-build2/
A human readable tutorial can be found at: http://www.highscore.de/cpp/boostbuild/