How to implement your analysis: The ATLASWatchMan Steering File

Introduction

The Steering File is the core of the user interface of ATLASWatchMan.

Here the user can choose how many analyses he/she want to implement, and for each of them he/she can specify the cuts and the related values. The cuts can use default formulas from a built-in library or defined and inserted by the user. In addition the user can choose to add extra branches to the output file containing the results of the analysis (in ATLAS called D3PD, a plain ROOT format file). The user can fill those extra branches with conatiners from the AOD file or with quantities computed with deafult or custom user-defined formulas. Using the external PlotROOT package the user can get plots from her/his analysis as well.

Fig. 1 How the Steering File logics works. You define your cuts and channels, you get the D3PD and the plots

Here below follows a detailed description of the Steering File structure. Examples of analsysis impementation are provided as well.

The Steering File structure

The ATLASWatchMan Steering File is a Python file. Once you installed the package (see here) you can find a template for your Steering File, ready to be used as template, under the run/ directory:

emacs share/ATLASWatchMan_AnalysisSteeringFile.py

Let's take a look at the structure of this file.

It is a Python file containing variables and dictionaries. Variables are used to declare options, while dictonaries to store informtion about analyses/channels, datasets to run upon and user-defined formulas to use in the cuts.

At the beginning of the file, under User Gobal Options, the user can set different options:

Fig. 2 The global user options

• outputFileName : the name of the final output .root file containing the results of the analysis;
• treeName : the name of the TTree within the .root file;
• printLevel : the printing level of the generated analysis code while running the analysis: 0 : deep debug, 5 : minimal print ;
• printLevelGen : the printing level of the generation of the analysis code: 0 : deep debug, 5 : minimal print ;
• outputLevelAthena : running on Athena you can set from here the level of printed output;
• applyObjSelection : Here you can choose if apply object selection or not...
• applyOverlapRemoval : ...and overlap removal;
• runOnAtlfast1 : This is a special flag. Set to True if you want to run on files produced with Atlfast1 ( with Atlfast2 leave it to =False= );
• doSkimmingGlobal : Set it to True if you want to skim the events while running on all the files or datasets you specify below in this same Steering File. If you set it to True only events which pass at least ALL the cuts specified for one channel/analysis are kept. If False all the events are kept and stored in the output file;
• doEvenSelectionEvenIfNotSkimming : If you have set False in doSkimmingGlobal, so you can choose here if you want or not to apply the event selection: if True the event selection is performed and the events in the output TTree will be flagged with the name of the channels/analyses whose cuts they have satisfied; all event will be kept (because you have choosen so above) so events not satisfying any analysis will be not flagged. If False so no event selection will be applied, but only the object selection and overlap removal. And the user-defined branches, if any, will be filled with the appropriate quantity.

Then, below, you can see a Python dictionary named 'channels'. This is the place where you can define your analyses!

Fig. 3 The code in the Steering File. Here you define your cuts and channels, and your custom formulas

Let's take a look at the example. Here we define a CSC-like SUSY search with 4 jets and 0 leptons.

Let's say that for our analysis we want these cuts:

• The jets have to be pT > [100,50,50,50] GeV respectevely;
• the EtMiss has to be greater than 100 GeV
• the EtMiss, again, has to be greater than 0.2 Effective Mass as well;
• the Sphericity has to be greater than 0.2
• the angular difference dPhy between jets and EtMiss has to be greater than 0.2, and we want this cut applied only on the 1st, the 2nd and the 3rd jet;
• we don't want to have any electrons, so we want to apply an electron veto;
• ...and the same for muons;
• and we want to apply a cut on a custom Effective Mass quantity, whose formula we want to define it ouserlves.

Those are the requests for our analysis. Now we will see how to implement them.

Let's browse the dictionary as it were a hierarchical tree.

The first item we meet is the dictionary name storing all analysis info, it's called channels .

Fig. 4 The Python dictionary containing definitions of channels, with cuts and user-defined custom formulas

As first 'index' we find the label that I chose for my specific analysis, '4j0lepCSC'; it has to be a string so it has to be quoted. This label will be used to flag events passing the event selection and particle passing the object selection and the overlap removal cuts defined inside this specific channel/analsyis.

Inside this item we find a label called 'channel' where you can specify the particles you want to use in your analysis. Here you can see 'jjjj' as we want just 4 jets. This field will be implemented as an interactive field in the future, loading only the containers specified here and so on. Now the only interactive feature it's when you use leptons in you channel: if you want to implement, for instance, the 4jets+1lepton analysis, where the 1lepton stand for (1electron OR 1muon), so you can put 'channel': 'jjjjl'; when you specify a 'l' in the 'channel' string, so a piece of code will be dinamically added to your generated analysis code; this piece of code builds the lepton container, i.e. a container called leptons where electrons and muons are stored in descending order of pT. Then you don't need to cut separately on electrons and muons but you can use this lepton container, either with default ATLASWatchMan built-in formulas for handle leptons, or with user-defined custom formulas, again. (Please notice: the so called 'lepton container' contains only electrons and muons)

A second field can be seen in our newly created '4j0lepCSC' analysis, the field 'cuts' . Here you define the cuts and formulas you want to apply in your analysis. To specify the order of the cuts you have to specify them under different keys, as shown in the example. The cut defined under the label '1' will be applied as the first cut, that one defined under the flag '2' as the second, and so on. Notice that there is no need to write them in a specified order: in the steering file you can write them in different order, provided that all of the cuts have a numbered unique 'label'. In this way it's also easier to change the order of cuts in your analysis, if you want to try a different cuts chain. Let's say we want to try to apply the 'jet_metDPhiCuts' before the 'sphericityCutCSC': just swap the numbered labels and it's done! (See Fig. 5)

Fig. 5 You can change the order of the cuts application just changing the numbered flags, as shown here. Left: Sphericity cut is applied before DPhi cut; Right: Sphericity cut is applied after the DPhi cut.

Let's take a look to a fully working example!

Now we can see a full edited working examples implementing many analyses at the same time. You can find it under the run/ folder. Open it with an editor, for example Emacs:

emacs run/ATLASWatchMan_AnalysisSteeringFile_benchmarkChannels.py

As you can see, in the channels dict many analyses have been defined.

How to edit the Steering File: Examples on implementing analyses

You can find how-to's, information and examples of working analyses here.

-- RiccardoMariaBianchi - 28 Jan 2009