General Afterburner Introduction

The analysis of the neutral mesons and direct photons, which is done after the pure grid analysis is organized in different macros, where we tried to have one macro per analysis step. Thus we split the steps of signal extraction, out-of-bunch pileup calculation, correction, cocktail processing, double ratio calculation, cut comparsion and systematics calculation into different macros. However, as the most of the macros need input from a previous step and it would be cumbersome to change the macro calls each time with the appropriate file. Most of steps, which need no manual intervention or optimization are handled by our steering scripts:

• start_FullMesonAnalysis_TaskV3.sh - handling the $\pi^0$ & $\eta$ in the $\gamma\gamma$-decay channel and the merged analysis as well as direct photon analysis

• start_FullMesonAnalysisDalitz_TaskV2.sh - handling the $\pi^0$ & $\eta$ in the $\gamma e^+e-$-decay channel

• start_FullOmegaMesonAnalysis.sh - handling the $\eta$ and $\omega$ analysis in the $\pi^0 \pi^+ \pi^-$ and $\pi^0 \gamma$ channel

They are stored in the main directory of the PCG-Afterburner directory. A visualisation of the paths for the neutral meson analysis in the $\gamma\gamma$-channel and the direct photon analysis can be found below using the start_FullMesonAnalysis_TaskV3.sh. It explains the main path of the analysis in the standard setup.

However, as usual there are some exceptions and you might want to read the corresponding script ones if you are analysing a well know data set for the first time, as for instance it might be necessary to run a special merging step for the efficiencies from added signals and minimum bias or jet-jet simulations. Each of the three scripts is also equipped with a short helper page, which can be called '--help' or '-h' after the script name.

In general the repository is ordered as follows:

• main directory:

  • Contains general steering scripts for the macros (start_FullMesonAnalysis_TaskV3.sh, start_FullMesonAnalysisDalitz_TaskV2.sh, start_FullOmegaMesonAnalysis), as mentioned above.

  • Furthermore, the macros to calculate the systematics of the different analysis techniques (_FinaliseSystematicErrors[Calo,Conv,ConvCalo,Merged,Dalitz]_[$SYSTEM$ENERGY].C), the combination macros for the mesons/gammas from different reconstruction techniques (CombineMesonMeasurements_*.C, CombineGammaResults_*.C) as well as comparison macros among different energies and particles (CombineNeutralPion*.C, CompareCharged*.C, CompareGamma*.C). Most of these are tailored to specific energies and cannot be used as generalized macros, but have either been used for the corresponding publications or for the preliminary creation.

  • Additional import macros contained in the main directory regarding the publications are the CalculateReference.C, CalculateSignificanceToPYTHIA.C, ComputeCorrelationFactors.C, TestMtScaling.C which can be used in a slightly more general way. In addition to these there are more specific macros, which were used for the publications (p-Pb mesons and the first meson paper), which are not necessarily maintained any longer.

  • The compilation macros of the external inputs for different data files from ALICE and other experiments (PrepareChargedPionDataALICE*.C,ProduceExperimentalDataGraphsPbPb.C) and theory predictions (ProduceTheoryGraphs*.C) can also be found here.

  • In addition to these the CompileCorrectGammaV2.C is stored here, which needs to be adjusted to contain your user-name and path to RooUnfold-headers if you want to run the direct photon extraction.

  • Last but not least a very helpful shell-script to create soft-links on your computer to one common software directory is stored here prepareResultsDirectory.sh. it is recommended to only checkout the PCG-repository once and then create soft-links to that directory in whatever other directory you are running the analysis on different data sets. It can be run by typing:

      bash $PATHTOPCGGIT/prepareResultsDirectory.sh $USERNAME [pp2760GeV,pPb5TeV,pp7TeV,pp8TeV,pp13TeV]

    with the last parameter being optional and the $USERNAME which needs to be added including the path. If the last parameter is used the number of links will be reduced in the main-dir to only include the necessary macros for that specific collision system.

• CocktailInput: Contains the output files from the cocktail generation on the grid, which are needed as input for the Afterburners once they are final. Furthermore, contains the final processed files by PrepareCocktail.C if they are close to preliminary or publication. We ask everyone not to commit too large root files here, as these will blow up the size of the repository and cannot be deleted fully again.

• CommonHeaders: Contains the header files which are commonly used in different macros:

  • AdjustHistRange.h contains the functions to automatically adjust the ranges for the QA output included in TaskQA/

  • CombinationFunctions.h contains all functions (and support routines) to combine results from different detectors/triggers (CombinePtPointsSpectraFullCorrMat(),CombinePtPointsSpectraTriggerCorrMat()) or compare spectra with different or the same binnings (CalculateRatioBetweenSpectraWithDifferentBinning()). Furthermore the previously used functions to combined only the fully independent results from PHOS and PCM are kept in this header files (CombinePtPointsSpectraAdv(), CombinePtPointsSpectra(), CombinePtPointsRAA()), however, they should not be used anymore as they will no longer be maintained. Most of these functions do rather delicate operations (i.e. matrix inversions, transformations of graphs & histos into each other, ...) as such please check the couts, they are ment as control and debug output. Last but not least it contains a function to calculate weighted quantities based on the $p_T$-dependent weights obtained in CombinePtPointsSpectraTriggerCorrMat() to properly display for instance the efficiency, acceptance, mass-position... . This function is, however, not yet fully vetted for all special cases, thus please have a look at the outcome and make sure the results are sensible.
  • ConversionFunctionsBasicsAndLabeling.h contains all common naming functions depending on the mode, trigger or cutnumber itself. Furthermore, it contains the functions which return the corresponding values of the different cuts and other general quantities, like $\sigma$ or $N_{coll}$.
  • ConversionFunctions.h contains all general functions used in the Afterburners not regarding plotting, labeling or combinations. For instance it contains functions to calculate ratios between different graphs, histos, fits and spline as well as scale functions for most of these objects. If you are not sure whether we implemented a more general operation in our framework have a look here or ask in our slack chats. it is very likely one of us already had to deal with the problem you're facing and found a solution.

  • ExtractSignalBinning.h contains all $p_T$ binnings for the different meson and photon analyses as well as the corresponding functions to set them. If you want to adjust a binning for a certain energy i.e. pp @13TeV make sure it is implemented correctly and does not interfer with anyone elses analysis settings here. Furthermore please make sure it is done in all the proper places, i.e. check on a different energy example what need to be done. We are currently in the process of trying to simplyfy the settings a little, so please implement the newer settings in InitializeBinning() using the functions: InitializeClusterBinning(), GetStartBin(), ReturnSingleInvariantMassBinPlotting(), GetOptimumNColumnsAndRows() & GetBinning() for the corresponding variables, as these can/will be used in the combination macros for instance as well.
  • ExtractSignalPlotting.h contains all functions needed for the plotting of the different invariant mass $M_\gamma\gamma$, distance of closest approach $dca_z$ or shower shape $\sigma_{long}^{2}$ slice in transverse momentum. This can either be done as single invariant mass bin plot or a plot with all slices in one plot. Also the functions for the heavier meson analysis are contained in this header file.
  • FittingGammaConversion.h contains the definitions of the fitting functions and a generalized function to initialize and fit graphs & histos with predefined functions used for the spectra fitting (FitObject()). Also the fitting functions for the resolution fitting are contained in this header.

  • PlottingGammaConversionAdditional.h This header contains a multitude of functions to make your plots even nicer and let them appear in the common sytle of the conversion/PWGGA group. For instance we defined common colors, marker styles and marker sizes for the different collision systems, energies (GetColorDefaultColor(), GetDefaultMarkerStyle(), GetDefaultMarkerSize()), triggers (GetDefaultTriggerColor(), GetDefaultTriggerMarker(), GetDefaultTriggerColorName(), GetDefaultTriggerMarkerStyleName(), GetDefaultTriggerMarkerSizeName()) and detection techniques (GetDefaultColorDiffDetectors, GetDefaultMarkerStyleDiffDetectors(), GetDefaultMarkerSizeDiffDetectors). Make sure to use them as it eases following presentations in the different meetings and the corresponding colors often have already been optimzed for visibility and style in the corresponding papers. In addition several functions to put logos and labels on the plot are contained in this header (i.e. PutALICESimulationLabel(), PutProcessLabelAndEnergyOnPlot(), DrawAliceLogoPerformance(), DrawStructure(), DrawAliceText()). Also some functions to extract the marker settings and colors from histos and graphs and create a single marker or box from these.

  • PlottingGammaConversionHistos.h contains all functions of the conversion group regarding plotting styles of hists, graphs, fits, profiles as well as some basic functions to obtain the correct text sizes for the different canvases and pads in canvases. The settings can either be done for single objects (i.e. DrawGammaSetMarker(), DrawGammaNLOTGraph(), SetStyleGammaNLOTGraphWithBand(), DrawAutoGammaHisto(), SetStyleHisto(), SetStyleHistoTH2ForGraphs(), DrawGammaHistoWithTitle2() ...) or multiple objects (DrawAutoGammaHistos(), DrawAutoGammaHistosMaterial(), DrawAutoGamma3Histos(), DrawAutoGammaHistosWOLeg() ...). Most of these functions exist for multiple objects and are named accordingly, they each have slightly different default settings and are usually optimized for a certain purpose. Thus please have a look at the different macros in which context they are used or ask in the slack chat if you are not sure. Additionally, some more general functions for setting proper canvas and pad settings are defined here: StyleSettings(), StyleSettingsThesis(), SetPlotStyle(), SetPlotStyleNConts(), DrawCanvasSettings(), DrawPadSettings() using part or all of these functions will make your code much more readable and your plots instantly better visible so please use them. Also the function: ReturnCorrectValuesForCanvasScaling() is vary handy as it return the correct values for the pad margins for multipad plots.

  • PlottingInterPolationRpPb5023GeV.h & Interpolation5023GeV.h are used in the p-Pb interpolation macros and contain specific functions for that as well as the binnings needed for the interpolation.

  • PlottingMeson.h contains the specific plotting functions for the meson QA needed in the framework.

• DownloadAndDataPrep: Contains the shell scripts to download the root-output files created by the lego-trains per period or per run (Get[GammaConv,GammaCalo,GammaConvCalo,GammaCaloMerged,NeutralMeson]FilesFromGridAndMergeThem_[pp,pPb,PbPb,XeXe][$ENERGY/$PERIOD].sh). The newest versions of these script are for the Run2 p-Pb and Xe-Xe data, which already depend on the (basicFunction.sh). In this shell script the commonly used functions for the download are stored for usage in other shell scripts. In the future please use these functions as they already check the consistency of the file and prevent multiple downloads, if not explicitly desired. Furthermore, the directory contains the helper macros for the download to separate files into their different directories (SeparateDifferentCutnumbers.C), to change the directory name to the default name (ChangeStructureToStandard.C) and to combine the output from different folders into one file (CombineDifferentFolders.C). In addition, a number of perl-scripts are provide to create the disired structure for the added signal processing for certain data sets (MakeLinks*.C). Last but not least this directory contains the different run lists and Jet-Jet bin number list in DownloadAndDataPrep/runlists. Please make sure that if you create a new data set or analyse a new data set that these are contained under the proper name in this folder.

• RooUnfold: Contains the necessary inputs to include RooUnfold. You need to compile RooUnfold uisng make in this folder once you have downloaded the directory in order to be able run the direct photon extraction properly. Afterwards the path to this directory needs to be included in CompileCorrectGammaV2.C including your user-name on your device.

• ExternalInput, ExternalInputpPb, ExternalInputPbPb, LHC11hInputFiles: These directories contain additional root & text files from external sources (like other analyzers in ALICE from PHOS & EMCal on $\pi^0, \eta \& \omega$), other particles like $\pi^\pm, K^\pm \ldots$ or theory calculations on the various topics. Furthermore they contain the final results for the neutral mesons once they are prelimary or published.
• SimulationStudies, ToyModels: These folders contain macros to analyse the pure simulation output created by the task AliAnalysisTaskGammaPureMC.cxx in AliPhysics/PWGGA/GammaConv as well as some macros to produce Toy-MC simulations to study for instance the effect of the the different resultions in the merged cluster analysis and a simple decay simulation for secondary decay studies.

• DeprecatedMacros: Here all macros have been moved which are no longer maintained but have been used to create published or preliminary plots. Additionally some older shell scripts to stear the material budget analysis can be found here.

• SupportingMacros: This directory contains a number of small macros, which are currently not need in general for the processing, but might be helpful to visualize some specific parts of the data or create specific input files for the grid analysis.

• SystematicErrorsNew, SystematicErrorsOld: These folder should contain all systematic errors in a text format which have been used for publication or preliminary creation. They will soon be sorted a bit better and reorganized to ease the understanding of these inputs.

• TaskFlow: This folder contains all necessary macros to perform the direct photon flow analysis, for further details please ask Mike Sas

• TaskQA: This is the dedicated folder for the post-processing macro of the analysis-level QA, they are explained in detail in the section Quality Assurance and Energy Calibration of Calorimeters. In order to ease the processing also examples for the configuration files are given in TaskQA/ExampleConfigurations.

• TaskV1: This folder contains all macros and header files needed to perform the neutral meson ($\pi^0/\eta \rightarrow \gamma\gamma, \gamma e^+,e^-$ & merged), heavy meson ($\omega, ...$) and direct photon analyses, which will be explained in the next sections. Addtionally, it contains macros to perform the material budget analysis and characterize the meson analysis further. Also the macros to perform create the energy-position-correction of the calorimeters are stored here. Once more example configurations for the macors which need a text file as input are provide in TaskV1/ExampleConfigs.

As you can imagine the software is evolving, as such some macros may exist in several version (V1,V2..), please make sure to always use the latest version if you start developing on top of something, as at some point the older ones will be deleted. In order to prevent incontinuities or larger disruptions these major deletion processes are kept to a minimum though and we try to do the changes in a more gradual fashion.