\documentclass[11pt, oneside]{article}   	% use "amsart" instead of "article" for AMSLaTeX format
\usepackage{geometry}                		% See geometry.pdf to learn the layout options. There are lots.
\geometry{letterpaper}                   		% ... or a4paper or a5paper or ... 
%\geometry{landscape}                		% Activate for for rotated page geometry
%\usepackage[parfill]{parskip}    		% Activate to begin paragraphs with an empty line rather than an indent
\usepackage{graphicx}				% Use pdf, png, jpg, or eps§ with pdflatex; use eps in DVI mode
								% TeX will automatically convert eps --> pdf in pdflatex		
\usepackage{amssymb}
\usepackage{amsmath}

\usepackage{tikz} % Flow charts
\usetikzlibrary{shapes,arrows}
\usetikzlibrary{trees}

\tikzstyle{decision} = [diamond, draw, fill=blue!20, text width=4.5em, text badly centered, node distance=3cm, inner sep=0pt]
\tikzstyle{block} = [rectangle, draw, fill=blue!20, text width=3cm, text centered, rounded corners, minimum height=4em]
\tikzstyle{line} = [draw, -latex', text width=3cm]
\tikzstyle{cloud} = [draw, ellipse,fill=red!20, node distance=3cm, minimum height=2em]

% Set the overall layout of the tree
\tikzstyle{level 1}=[level distance=5.3cm, sibling distance=2cm]
\tikzstyle{level 2}=[level distance=5.3cm, sibling distance=2cm]

% Define styles for bags and leafs
\tikzstyle{bag} = [text width=0.6cm, text centered]
\tikzstyle{bag2} = [text width=3.5cm, text centered]
\tikzstyle{end} = [circle, minimum width=3pt,fill, inner sep=0pt]

\title{Pandora Analysis Calibration Executables}
\author{Steve Green, sg568@hep.phy.cam.ac.uk}
\date{}							% Activate to display a given date or no date

\begin{document}
\maketitle

%------------------------------------------------
% Abstract
%------------------------------------------------

\begin{abstract}
The calibration procedure required for simulation and reconstruction of high energy physics events at a future electron positron collider using the particle flow algorithm PandoraPFA is described in full.  The calibration procedure addresses how to set the constants used in the simulation for both digitisation, the estimation of energy deposits in the absorber material of the sampling calorimeters based on the energy deposits in the active material, and those used within PandoraPFA to set the hadronic and electromagnetic energy scales for the various particle showers being reconstructed.  To be assured of accurate reconstruction, recalibration must be performed for all changes to detector design and/or  reconstruction logic in PandoraPFA.

These studies were developed in the context of simulation of ILD (ILD\_o1\_v06) using Mokka for the detector simulation.  This procedure can be adapted to other contexts as fundamentally the logic applied is universal to simulation of sampling calorimeters.  Please contact the Cambridge linear collider group for any assistance.
\end{abstract}

%------------------------------------------------
% Introduction
%------------------------------------------------

\section{Introduction}

To ensure accurate results from the simulation of the high energy physics events at a future electron positron collider it is necessary to accurately define a number of constants used in both the simulation and reconstruction.  The calibration procedure described here addresses the setting of the calibration constants used in both the digitisation processor (ILDCaloDigi or NewLDCCaloDigi) and PandoraPFA.

The purpose of the constants used in the digitisation processor is twofold: (i) To set a series of constants that accurately estimate the amount of energy deposited in the absorber material of the sampling calorimeter being simulated based on the measured energy despots in the active material and (ii) to set the MIP scale used in the digitisers.  

It should be noted that the MIP scale only needs setting in the digitisers if you wish to apply the realistic digitisation options in ILDCaloDigi.  In such a case the MIP scale is needed to apply a dynamic range to the readout electronics in the calorimeters.

The purpose of the constants used within the particle flow algorithm PandoraPFA is to set the different energy scales for electromagnetic and hadronic particle showers.  There are a total of four constants applied, which set the electromagnetic and hadronic energy scales in both the electromagnetic calorimeter (ECal) and the hadronic calorimeter (HCal).  The constants need not be the same for both calorimeters due to the different atomic structures of the calorimeters. 

A detailed list of the calibration constants being defined in this procedure for the digitiser and for PandoraPFA can be found in table \ref{table1} and table \ref{table2} respectively.

\begin{table}[htdp]
\caption{Digitisation Constants}
\begin{center}
\begin{tabular}{|c|l|}
\hline
Constant & Description \\
\hline
CalibrECAL 		& Converts the SimCalorimeterHit energy deposit (active material) \\
                                  & into a CalorimeterHit energy deposition (active material and \\ 
                                  & absorber material) in units of GeV in the ECal \\
CalibECALMIP		& Sets the MIP energy scale in the ECal (for digitisation)\\
CalibrHCALBarrel 	& Converts the SimCalorimeterHit energy deposit (active material) \\
                                  & into a CalorimeterHit energy deposition (active material and \\ 
                                  & absorber material) in units of GeV in the HCal barrel \\
CalibrHCALEndcap 	& Converts the SimCalorimeterHit energy deposit (active material) \\
                                  & into a CalorimeterHit energy deposition (active material and \\ 
                                  & absorber material) in units of GeV in the HCal endcap \\
CalibrHCALOther 	& Converts the SimCalorimeterHit energy deposit (active material) \\
                                  & into a CalorimeterHit energy deposition (active material and \\ 
                                  & absorber material) in units of GeV in the HCal other (i.e. ring) \\
CalibHCALMIP		& Sets the MIP energy scale in the HCal (for digitisation)\\
\hline
\end{tabular}
\end{center}
\label{table1}
\end{table}%

\begin{table}[htdp]
\caption{PandoraPFA Constants}
\begin{center}
\begin{tabular}{|c|l|}
\hline
Constant & Description \\
\hline
ECalGeVToMIP 			& Converts SimCalorimeterHit energy deposits to units of number of\\
			 			& MIPs in the ECal\\
HCalGeVToMIP 			& Converts SimCalorimeterHit energy measurements to units of number of\\
			 			& MIPs in the HCal\\
MuonGeVToMIP 			& Converts SimCalorimeterHit energy measurements to units of number of\\
			 			& MIPs in the Muon Chamber\\
ECalToEMGeVCalibration 	& Energy rescaling factor for electromagnetic energy\\
					 	& in the ECal \\
HCalToEMGeVCalibration 	& Energy rescaling factor for electromagnetic energy\\
					 	& in the HCal \\
ECalToHadGeVCalibration 	& Energy rescaling factor for hadronic energy\\
					 	& in the ECal \\
HCalToHadGeVCalibration 	& Energy rescaling factor for hadronic energy\\
					 	& in the HCal \\
\hline
\end{tabular}
\end{center}
\label{table2}
\end{table}%

A series of executable files have been produced to determine the values that each of these calibration constants can take.  These executables can be found within the calibration folder inside the PandoraAnalysis toolkit. A description on how to use each of these executables follows.  It should be noted that the setting of these calibration constants is an iterative process.

\section{Calibration Files}

These executables calibrate the simulation and reconstruction using single particle events of known particle type and fixed particle energy.  Therefore, before performing any analysis with the sector model you have to simulate and reconstruct photons, muons and long-lived neutral kaons.  After running PandoraPFA in the Marlin framework, the MarlinPandora processor, on these single particle events, you must run the PfoAnalysis processor and save the output root files.  These are to be used as inputs for the calibration executables.   

To collect the relevant calibration information within the PfoAnalysis processor a series of extra parameters must be specified in the xml steering file in comparison to the default PandoraAnalysis setup.  These include the sim calo hit collections produced from GEANT (via Mokka) and the calorimeter hit collections produced from the digitisation stage.  You must also specify the CollectCalibrationDetails flag and some extra missing geometry information from the gear file.  An example Marlin steering file set up for collecting all calibration information using this processor is shown in PandoraAnalysis/scripts/PandoraAnalysisCalibration.xml.

An example steering file that is set up to run the PfoAnalysis processor and collect the calibration information referenced above can be found in scripts/PandoraAnalysisCalibration.xml. 

For the default ILD sector model it is recommended that you use 10 GeV photon samples, 10 GeV muon samples (this is a MIP definition and should not be varied) and 20 GeV long-lived neutral kaon samples.  

The increase in energy for the kaon samples is suggested as these samples are used in general for calibrating parameters relating to the HCal and we ensure that, for a typical event, the bulk of the energy is deposited in the HCal and not in the ECal.  Of course there will be some energy deposited in the ECal for certain events, but selection cuts on events used in calibration executables accounts for any effects that this may have on the calibration.  

\section{Digitisation}

\subsection{ECalDigitisation\_ContainedEvents}

This script is run on the root file outputs for the single photon events and determines how to set CalibrECAL.

Inputs:
\begin{enumerate}
\item Input root files, wildcards can be used.
\item True energy of photons being simulated.
\item Fractional calibration accuracy of digitisation step.  This is used to define the bin width in the plot, which determines precision of results.  Default: 2\%
\item Output path to send the calibration text file and the output plot to.
\item Percentage of data to perform Gaussian fit to.  This range is taken to be the continuous range of data with the minimum root mean squared (RMS).  The default is set to 90\% of data.
\end{enumerate}

After running this script on the root files you rescale CalibrECAL by:

\begin{equation}
\frac{\textit{True Photon Energy}}{\textit{Mean Reconstructed Calo Hit Energy}}
\end{equation}

Iteration is now performed until the total calorimeter hit energy for photon events contained in the ECal (produced by the script) falls within the desired accuracy.  Iteration involves changing the CalibrECAL value in your Marlin steering files and rerun the photons through Marlin.  This process is repeated until the total calorimeter hit energy for photon events contained in the ECal is within acceptable limits defined by the fractional accuracy of the digitisation step.

\subsection{HCalDigitisation\_ContainedEvents}

This script is run on the root file outputs for the single long-lived neutral kaon events and aims to set CalibrHCALEndcap and CalibrHCALBarrel.

Inputs:
\begin{enumerate}
\item Input root files, wildcards can be used.
\item True energy of long-lived neutral kaon being simulated.
\item Fractional calibration accuracy of digitisation step.  This is used to define the bin width in the plot, which determines precision of results.  Default: 2\%
\item Output path to send the calibration text file and the output plot to.
\item Percentage of data to perform Gaussian fit to.  This range is taken to be the continuous range of data with the minimum root mean squared (RMS).  The default is set to 90\% of data.
\item Number of HCal layers in detector being simulated.  Important for defining confined events.
\item Detector component string.  Used as a naming convention.  Options are either "Barrel" or "EndCap".  This parameter is used as you perform separate digitisation for the Barrel and EndCap.
\item Lower CosTheta Cut.  This is the lower limit of cos theta (polar angle), which you are using to define the Barrel or EndCap.  Default: 0.2 Barrel, 0.8 EndCap
\item Upper CosTheta Cut.  This is the upper value of cos theta (polar angle), which you are using to define the Barrel or EndCap.  Default: 0.6 Barrel, 0.9 EndCap
\end{enumerate}

After running this script on the kaonL root files you independently rescale CalibrHCALBarrel and CalibrHCALEncap by:

\begin{equation}
\frac{\textit{True KaonL Energy}}{\textit{Mean Reconstructed Calo Hit Energy}}
\end{equation}

Iteration is now performed until the total calorimeter hit energy for long-lived neutral kaon events contained in the HCal Barrel and HCal EndCap (produced by the script) falls within the desired accuracy.  Iteration involves changing the CalibrHCALEndcap and CalibrHCALBarrel values in your Marlin steering files and rerun the kaonL through Marlin.  This process is repeated until the the total calorimeter hit energy for long-lived neutral kaon events contained in the HCal Barrel or HCal EndCap are within acceptable limits defined by the fractional accuracy of the digitisation step.

\subsection{HCalDigitisation\_DirectionCorrectionDistribution}

This binary is designed to address the digitisation of the HCAL ring (CalibrHCALOther).  This script is run on the root file outputs for the single fixed long-lived neutral kaon energy.

Inputs:
\begin{enumerate}
\item Input root files, wildcards can be used.
\item True energy of kaonL being simulated.
\item Output path to send the calibration text file and the output plot to.
\end{enumerate}

This script joins together all the histograms (from all input root files) of direction corrections applied to the cells within the HCal in the barrel, endcap and other (other is ring) for the long-lived neutral kaon samples.  There is no iteration required for this step.  The mean direction corrections for each of the three distributions (barrel, endcap, other) should be recorded and saved for a later stage.

\subsection{SimCaloHitEnergyDistribution}

This binary has two functions.  The first is to continue the digitisation constant calibration of the HCal other and the second is to determine the MIP scale in both the ECal and the HCal if you wish to use the realistic digitisation options in ILDCaloDigi.  This script is run on the root file outputs for the single muon events.

Inputs:
\begin{enumerate}
\item Input root files, wildcards can be used.
\item True energy of kaonL being simulated.
\item Output path to send the calibration text file and the output plot to.
\end{enumerate}

The output once this executable has been run is a series of plots containing the direction corrected SimCalorimeterHit energies for the ECal (as a whole) and the HCal (Barrel, EndCap and Other separately).  These plots should show a clear MIP peak in all cases.

\vspace{1cm}

CalibrHCALOther is set to be equal to CalibrHCALEndcap multiplied by the ratio of the MIP peaks for the EndCap and Other (from SimCaloHitEnergyDistribution), multiplied by the ratio of the absorber scintillator ratio (from gear files) and multiplied by the ratio of direction corrections (from HCalDigitisation\_DirectionCorrectionDistribution)

\begin{equation}
\begin{split}
\text{CalibrHCALOther} & = \text{CalibrHCALEndcap} \\ \times &  \frac{\langle \text{Direction Correction}_\text{EndCap} \rangle}{\langle \text{Direction Correction}_\text{Ring} \rangle} \\ \times & \frac{ \text{MIP Peak}_\text{EndCap} }{ \text{MIP Peak}_\text{Ring} } \\ \times & \frac{ \text{Absorber Thickness}_\text{EndCap} }{ \text{Absorber Thickness}_\text{Ring} } \\ \times & \frac{ \text{Scintillator Thickness}_\text{Ring} }{ \text{Scintillator Thickness}_\text{EndCap}}
\end{split}
\end{equation}

The realistic digitisation variables are set as follows, CalibHCALMIP is set to be the peak value in the direction corrected SimCalorimeterHit energy distribution for the HCal barrel and CalibECALMIP is set to be the peak value in the direction corrected SimCalorimeterHit energy distribution for the ECal.  Note: There is some ambiguity about choosing the MIP scale in the HCal based entirely on the Barrel, but from experience the peaks in the distributions are very similar for both the Barrel and EndCap so the choice doesn't matter.  If these differ significantly in your studies then you should reevaluate this procedure.

No iteration is required at this stage.  

\section{PandoraPFACalibration}

\subsection{PandoraPFACalibration\_HadronicScale\_MipResponse}

This binary calibrates the MIP response in PandoraPFA.  This script is run on the root file outputs for the single muon samples.

Inputs:
\begin{enumerate}
\item Input root files, wildcards can be used.
\item True energy of muons being simulated.
\item Output path to send the calibration text file and the output plot to.
\end{enumerate}

This script makes plots of the direction corrected calorimeter hit energy for the HCal, ECal and Muon Chamber.  The constants ECalToGeVMIP, HCalToGeVMIP and MuonToGeVMIP are then defined as the constants, which are needed to shift the position of the observed peak in these plots to 1.  The determines the response of each part of the detector to MIP like particles and can be used to convert energy measurements into a number of normally incident mips required to deposit the same amount of energy.  There is no iteration applied here.

\subsection{PandoraPFACalibration\_EMScale}

This script is run on the root file outputs for the single photon samples and aims to set ECal/HCalToEMGeVCalibration.

Inputs:
\begin{enumerate}
\item Full path to photon root files.  Wildcards can be used here.
\item True energy of photon.
\item Fractional calibration accuracy of PandoraPFA step.  This is used to define the bin width in the plot, which determines precision of results.  Default: 0.5\%
\item Output path to send the calibration text file and the output plot to.
\item Percentage of data to perform Gaussian fit to.  This range is taken to be the continuous range of data with the minimum root mean squared (RMS).  The default is set to 90\% of data.
\end{enumerate}

After running this script on the root files you rescale ECalToEMGeVCalibraiton by:

\begin{equation}
\frac{\text{True Photon Energy}}{\text{Mean Reconstructed PFO Energy}}
\end{equation}

Mean Reconstructed PFO Energy is generated by the binary once it is run over the root files.  Iteration is then performed until the PFO energy for photon events falls within the desired accuracy.  Iteration involves changing the ECalToEMGeVCalibraiton value in your Marlin steering files and then reruning the photons through Marlin.  Iteration keeps occurring until the the PFO energy for photon events is within acceptable limits defined by the fractional accuracy of the PandoraPFA stage.  Once this stage is completed set HCalToEMGeVCalibraiton to equal ECalToEMGeVCalibraiton.

\subsection{PandoraPFACalibration\_HadronicScale\_ChiSquaredMethod}

This script is run on the root file outputs for the single fixed kaonL energy and aims to set ECal/HCalToHadGeVCalibration.

Inputs:
\begin{enumerate}
\item Full path to kaonL root files.  Wildcards can be used here.
\item True energy of kaonL particles being simulated.
\item Fractional calibration accuracy of PandoraPFA step.  This is used to define the bin width in the plot, which determines precision of results.  Default: 0.5\%
\item Output path to send the calibration text file and the output plot to.
\item Number of HCal layers for the detector being simulated.  This is the number of layers in the HCal being simulated.  This is needed to define a contained event.
\end{enumerate}

This binary forms the 2D histogram of ECalToHad energy vs HCalToHad energy.  A line of best fit is applied to the data set, once a cut is applied to remove leakage effects and the intercepts of this best fit are used to rescale ECal/HCalToHadGeVCalibration until both intercepts match the available energy of the kaonL being simulated.  Again this requires iteration.  

ECalToHadGeVCalibration and HCalToHadGeVCalibration are independently rescaled respectively by:

\begin{equation}
\frac{\text{True KaonL Energy}}{\text{ECalToHad PFO Energy Intercept}} \text{ and } \frac{\text{True KaonL Energy}}{\text{HCalToHad PFO Energy Intercept}} 
\end{equation}

The ECalToHad and HCalToHad PFO energy intercepts are generated by the binary.  Iteration involves rescaling ECalToHadGeVCalibration and HCalToHadGeVCalibration and then rerunning then rerunning the kaonL samples through Marlin again.  The calibration constants are then rescaled again and this continues until the ECalToHad and HCalToHad PFO energy intercepts fall within the desired accuracy targeted from the PandoraPFA stage.

\subsection{PandoraPFACalibration\_HadronicScale\_TotalEnergyMethod}

This script is run on the root file outputs for the single fixed kaonL energy and is an alternative method for setting ECal/HCalToHadGeVCalibration.

Inputs:
\begin{enumerate}
\item Full path to kaonL root files.  Wildcards can be used here.
\item True energy of kaonL particles being simulated.
\item Fractional calibration accuracy of PandoraPFA step.  This is used to define the bin width in the plot, which determines precision of results.  Default: 0.5\%
\item Output path to send the calibration text file and the output plot to.
\item Percentage of data to perform Gaussian fit to.  This range is taken to be the continuous range of data with the minimum root mean squared (RMS).  The default is set to 90\% of data.
\item Number of HCal layers for simulated detector.  This is the number of layers in the HCal being simulated.  This is needed to define a contained event.
\end{enumerate}

This binary performs a Gaussian fit to total PFO energy, once both ECal/HCalToHad have been independently rescaled.  The mean of this Gaussian fit is fixed and the ideal rescaling constants (one for ECalToHad one for HCalToHad) minimise the standard deviation of that Gaussian fit.  The scale factors produced for the ideal fit, which are generated by the script, are used to rescale ECal/HCalToHadGeVCalibration independently.

Iteration involves rescaling ECalToHadGeVCalibration and HCalToHadGeVCalibration and then rerunning the kaonL samples through Marlin again.  The calibration constants are then rescaled again and this continues until the rescaling factors produced by this method are both equal to unity within the errors defined to be the desired accuracy of the PandoraPFA stage.  

\subsection{PandoraPFACalibration\_HadronicEnergyGaussianFit}

This script is run on the root file outputs for the single fixed kaonL energy.  It is used for applying Gaussian fits to reconstructed kaonL PFO energy, for events contained within the HCal.  

Such events can also be used for the implementation of non-linearity corrections designed to force a linear relationship between simulated and reconstructed kaon samples across a range of different simulated energies, however, by default it is not recommended that you used these non-linearity corrections in your simulation.

Inputs:
\begin{enumerate}
\item Full path to kaonL root files.  Wildcards can be used here.
\item True energy of kaonL.
\item Fractional calibration accuracy of PandoraPFA step.  This is used to define the bin width in the plot, which determines precision of results.  Default: 0.5\%
\item Output path to send the calibration text file and the output plot to.
\item Percentage of data to perform Gaussian fit to.  This range is taken to be the continuous range of data with the minimum root mean squared (RMS).  The default is set to 90\% of data.
\item Number of HCal layers for simulated detector.  This is the number of layers in the HCal being simulated.  This is needed to define a contained event.
\item Non linearity constants on or off (just sets the labels for the output).
\end{enumerate}

This binary produces the Gaussian fit to and histogram of PFO energy for the kaonL data.  A text file contains the mean, standard deviation and amplitude of the gaussian fit is also produced.  It would be the mean and true energy used as inputs for non linearities if they were implemented.

%------------------------------------------------
% Calibration Run Order
%------------------------------------------------

\section{Suggested Running Order of Calibration}

It is important to ensure that this calibration procedure is applied in the correct order.  As changes to each variable will effect the simulation downstream of it necessary to calibrate the simulation in such a way that mirrors the reconstruction chain.  Therefore, the digitisation stage will be calibrated before the PandoraPFA stage.  In both cases it is also essential to set the MIP scale first, as both the digitiser (realistic options only) and PandoraPFA apply cuts based in units of MIPs.  Once the MIP scale is set you can then begin the calibration procedure of the variables relating to the processor in question.  Based on that logic here is a suggested calibration chain that you should use if you wish to use the realistic digitisation options in the ILDCaloDigi processor:

\begin{enumerate}
\item SimCaloHitEnergyDistribution - Set the MIP scale in the digitiser
\item ECalDigitisation\_ContainedEvents - Digitsation for ECal
\item HCalDigitisation\_ContainedEvents - Digitsation HCal Barrel and HCal EndCap simultaneously.
\item HCalDigitisation\_DirectionCorrectionDistribution and SimCaloHitEnergyDistribution - Get variables and set digitisation of HCal other
\item PandoraPFACalibrate\_MipResponse - MIP scale in Pandora
\item PandoraPFACalibrate\_EMScale
\item PandoraPFACalibrate\_HadronicScale\_ChiSquareMethod or PandoraPFACalibrate\_HadronicScale\_TotalEnergyMethod
\end{enumerate}

If you do not require the realistic options in the ILDCaloDigi processor the procedure is the same, just omitting step 1.

\end{document}  