Update 'Utils.hpp'

Utils.hpp.md

@@ -3,6 +3,7 @@ In this file, various helper functions are defined. Unfortunately, as we are try
 
 ## Global variables:
 
+### Number of generated MC events
 * double generated_basic_events = 10000.0
 * double generated_basic_events_PHSP = 1000.0
 * vector\<int> generated_signal_events_down  
@@ -11,10 +12,15 @@ In this file, various helper functions are defined. Unfortunately, as we are try
 * vector\<int> generated_reference_events_up  
 * vector\<int> generated_PHSP_events_down     
 * vector\<int> generated_PHSP_events_up  
+### Generator tables      
+**TODO** Add linke
 * vector\<double> gen_tables_signal_efficiency_down 
 * vector\<double> gen_tables_signal_efficiency_up   
 * vector\<double> gen_tables_reference_efficiency_down
 * vector\<double> gen_tables_reference_efficiency_up 
+
+### Yields and their errors
+Obsolete now, the numbers are not up to date!
 * vector\<int> yield_signal_events
 * vector\<int> yield_signal_events_err
 * vector\<int> yield_reference_events 
@@ -195,15 +201,18 @@ In this file, various helper functions are defined. Unfortunately, as we are try
 * **Return**
     * A string combining [getFullCut()](#string-getfullcut), [getTMcut()](#string-gettmcut) and [getMultipleCut()](#string-getmultiplecut)
 
-### string checkIf2015MC()
+## Sanity checks
 
+### string checkIf2015MC()
+Buggy 2015 MC needs to be removed and replaced by 2016, hence check whether you are trying to load ot
 * **Parameters**
     * string year
     * bool MC
     * bool Reference
     * bool PHSP
 * **Return**
-
+    * 2015 the MC sample exists, otherwise 2016
+    * 
 ### bool checkMC()
 
 * **Parameters**
@@ -212,82 +221,90 @@ In this file, various helper functions are defined. Unfortunately, as we are try
     * bool PHSP
     * bool mutuallyExclusive
 * **Return**
+    * True if you are selecting a meaningful sample, otherwise false
 
 ### bool checkMC()
-
 * **Parameters**
     * bool ReferenceChannel
     * bool PHSP
 * **Return**
+    * True if !(ReferenceChannel && PHSP), else False
 
 ### bool checkQ2Range()
-
 * **Parameters**
     * bool UseOnlyJpsi
     * bool UseOnlyMuMu
 * **Return**
+    * False if you simultaneously require reference and rare Q2 region, true otherwise
 
 ### bool checkTM()
-
 * **Parameters**
     * bool MC
     * bool &TM
     * bool &nonTM
     * bool Preselected
 * **Return**
+    * True if you require meaningful sample to be truth matched, false otherwise
 
 ### bool checkKshort()
 
 * **Parameters**
     * bool &KshortDecaysInVelo
 * **Return**
+    * Check you do not require LL tracks in the K+pi0 channel
 
 ### bool checkRefYear()
-
+No reference MC available for  2017 and 2018
 * **Parameters**
     * string year
 * **Return**
+    * True if year < 2017, false otherwise
 
 ### bool checkEntries()
-
 * **Parameters**
     * TTree \*tree
 * **Return**
+    * False if the tree is empty, true otherwise.
 
 ### bool checkYear()
-
 * **Parameters**
     * int year
     * bool MC
     * bool ReferenceChannel
     * bool PHSP
 * **Return**
+    * True if you require a meaningful year for the given data sample, false otherwise
 
 ### bool checkRun()
-
 * **Parameters**
     * int Run
 * **Return**
+    * True if the Run number is meaningful, false otherwise
+
+## Names and tags
 
 ### string getTMtag()
 
 * **Parameters**
     * string customTMbranch
 * **Return**
-
+    * Branch tag used in the truth matching branch
+    * 
 ### string getTMtag()
 
 * **Parameters**
     * string customTMbranch
     * bool gammaTM
 * **Return**
+    * Branch tag used in the truth matching branch
 
 ### string getWeightName()
-
+Weighting depends on the truth matching, hence each weight branch has a TM tag too
 * **Parameters**
     * string customTMbranch
     * bool gammaTM
 * **Return**
+    * Branch tag used in the weighting branch
 
 ### std::string getDataTypeTag()
 
@@ -299,6 +316,7 @@ In this file, various helper functions are defined. Unfortunately, as we are try
     * bool K1
     * bool Inc
 * **Return**
+    * Tag corresponding to the selected sample, eg "Data" or "MC BtoXMuMu"
 
 ### string getDataTypeTag()
 
@@ -307,6 +325,7 @@ In this file, various helper functions are defined. Unfortunately, as we are try
     * bool Reference
     * bool PHSP
 * **Return**
+    * Tag corresponding to the selected sample, calls [getDataTypeTag()](std-string-getdatatypetag)
 
 ### string getYearRunTag()
 
@@ -314,17 +333,20 @@ In this file, various helper functions are defined. Unfortunately, as we are try
     * int Run
     * string year
 * **Return**
+    * Tag with the given run or year
+    
+## Similarly populated bins
 
 ### void getSimilarlyPopulatedBins()
-
+This function assumes the original bin width is one!!! Takes the histogram and rebins it in a way the final bins are simirarly populated. 
 * **Parameters**
     * TH1D \*histogram
     * int desiredBins
     * int nBins
-* **Return**
+
    
 ### void getSimilarlyPopulatedBinsVar()
-
+Reads a TTree, fills in the histogram based on the input parameters with `var`, modifies it to be simirarly populated, and exits. The histogram is ont saved anywhere though.
 * **Parameters**
     * string var
     * int nBins
@@ -336,13 +358,14 @@ In this file, various helper functions are defined. Unfortunately, as we are try
     * int Run
     * bool ReferenceChannel
     * bool PHSP
-* **Return**
+
+## Getting results from a RooFit file
 
 ### RooFitResult\* getResult()
-
 * **Parameters**
     * TFile \*fitFile
 * **Return**
+    * Retureves the RooFitResult from the fitFile
 
 ### RooRealVar\* getVarFromResult()
 
@@ -350,92 +373,94 @@ In this file, various helper functions are defined. Unfortunately, as we are try
     * RooFitResult \*fitResult
     * string name
 * **Return**
+    * Retrieves the RooRealVar from the RooFitResult based on the name
 
 ### double getBplusMeanFromResult()
 
 * **Parameters**
     * TFile\* fitFile
 * **Return**
+    * Reads the mass mean from the mass fit file
 
 ### double getSigYield()
 
 * **Parameters**
     * TFile \*fitFile
 * **Return**
+    * signal yield from the mass fitFile
 
 ### double getSigYieldErr()
 
 * **Parameters**
     * TFile \*fitFile
 * **Return**
+    * signal yield error from the mass fitFile
 
 ### double getBkgYield()
 
 * **Parameters**
     * TFile \*fitFile
 * **Return**
+    * background yield from the mass fitFile
+
 
 ### double getBkgYieldErr()
 
 * **Parameters**
     * TFile \*fitFile
 * **Return**
+    * background yield error from the mass fitFile
 
 ### double getEffSigma()
 
 * **Parameters**
     * TFile \*fitFile
 * **Return**
+    * effective sigma from the mass fitFile
+
+## histogram/graph helpers
 
 ### TH1D \*convertTGraph()
 
 * **Parameters**
     * TGraph \*graph
 * **Return**
+    * Returns a histogram created from a TGraph
+
+## Numbers of generated events
 
 ### double get_generated_events()
-
 * **Parameters**
     * bool PHSP
 * **Return**
+    * Returns the scale used to calculate the efficiencies
 
 ### int get_position_from_year()
-
+The yields and generator efficiencies are saved in vectors for each year, 2011, 2012, 2015, 2016, 2017, 2018. This converts the year string to the correct postiion in the vector.
 * **Parameters**
     * string year
 * **Return**
+    * position in the vector where to look a for given year
 
 ### int get_gen_evts()
 
 * **Parameters**
-    * string year
+    * string year/int Run
     * bool ReferenceChannel
     * bool PHSP
 * **Return**
-
+    * The number of generated events for the given year/Run
 ### int get_gen_evts()
 
-* **Parameters**
-    * int Run
-    * bool ReferenceChannel
-    * bool PHSP
-* **Return**
 
 ### int get_selected_evts()
 
 * **Parameters**
-    * string year
+    * string year/int Run
-    * bool ReferenceChannel
-    * bool PHSP
-* **Return**
-
-### int get_selected_evts()
-
-* **Parameters**
-    * int Run
     * bool ReferenceChannel
     * bool PHSP
 * **Return**
+    * The number of selected events for the given year/Run
 
 ### int get_selected_evts_err()
 
@@ -444,40 +469,31 @@ In this file, various helper functions are defined. Unfortunately, as we are try
     * bool ReferenceChannel
     * bool PHSP
 * **Return**
+    * The error of the number of selected events for the given year
+
 
 ### double get_selection_efficiency()
 
 * **Parameters**
-    * string year
+    * string year/int Run
     * bool ReferenceChannel
     * bool PHSP
 * **Return**
+    * The selection efficiency for the given year
 
-### double get_selection_efficiency()
-
-* **Parameters**
-    * int Run
-    * bool ReferenceChannel
-    * bool PHSP
-* **Return**
 
 ### double get_tables_eff()
 
 * **Parameters**
-    * string year
+    * string year/int Run
-    * bool ReferenceChannel //Get efficiency in a year as an average between up and down
+    * bool ReferenceChannel 
 * **Return**
+    * Generator efficiency in a yearPrun as an average between up and down
 
-### double get_tables_eff()
-
-* **Parameters**
-    * int Run
-    * bool ReferenceChannel //Get efficiency of a run as an average between years
-* **Return**
 
 ### void print_all_yields_and_efficiencies()
-
+Print the number of generated events, selected events and the selection efficiency for the given year.
 * **Parameters**
     * bool ReferenceChannel
     * bool PHSP
-* **Return**
+