Here we will work on a combined proposal using the other two by combining their strengths and eliminating their weaknesses. We first define the rules for each type of block and the structure of the file in total. We then follow with an explicit proposal that should correspond to some real-life analyses from ATLAS and CMS. ====== Open Questions/Comments ====== - D: Maybe the overall description comment should start with '###' as in Python to distinguish from normal '#' comments which the parser should just ignore * S: The proposal concerning '#' is a really tricky thing. How about including three single quotes like in python docstrings? or /* description*/ like in c++ - D: See 'detectorobj' description: A 'take external' selection could clearly point out those objects which have to be defined on a fundamental level in whatever program one uses - D: What is the difference between 'doc' and 'code'? Can't the 'doc' contain everything, including the code? * N: 'doc' is a link to a human-readable document. 'code' is the name of the function/link to the function (for when they make a library of functions). - D: What is the purpose of 'eff' in the cuts and what distinguishes a 'trigger' selection from a normal 'select'? * N: There is no difference between 'trigger' and 'cut'. In the original version, one could have aribitrary xml tags, so I thought it'd be nice to have explicit names. Now, everything should be a 'cut'. * N: The eff is an estimated efficiency for things like the trigger/b-tagging etc. provided by the experiments. We should in principle also allow inclusion of efficiency tables instead of a single number. - D: In cuts, I again would rather use 'take' instead of 'contains': if 'B' uses the events from A, then 'A takes the events from B' (but 'B contains the events from A, as A applies more cuts') * N: Maybe 'include' instead of 'take'? The idea behind 'contains' was a generic inheritance (not just for cuts) where any block can inherit from any other. - D: Is it possible to use '|' instead of .OR.? the dot to me always refers to a member of a class. * N: I don't see why not (or even a c-like || which is easier for a human to read than a single |). ====== General Structure ====== The idea is to write a plain text file that can be read easily into xml if needed (and hence universally readable). The name of the block becomes the xml tag. Anything that follows is turned into attributes. e.g. "name ATLAS" inside the block becomes . Anything inside the block starting with "#" is added as a comment, i.e. the block info analysis # Details about experiment id ATLAS-2014-XXX publication JHEP11(2014)118 sqrtS 8.0 lumi 20.0 converts to There are five types of pre-defined blocks: - **detectorobj** (defines reconstructed objects) - **function** (defines functions that act on these) - **cut** (blocks of cuts) - **binning** (following Daniel's idea, for complex descriptions of orthogonal signal regions) - **info** (for meta information chosen by the implementer, e.g. information about publication, conf-notes, theory papers used for interpretation, benchmarks, etc.) For presenting results, we need two more blocks, e.g. - **results** (for expected, observed, S95, etc.) - **cutflow** (for cutflows) - **table** (for providing digitised histograms etc.) For any block, a link to code or external documentation can be provided. We can also include a MCsamples block to document the programs used to generate signal and background samples. ==== info ==== ... info analysis # Details about experiment id SUSY-2013-15 publication JHEP11(2014)118 sqrtS 8.0 lumi 20.0 arXiv 1407.0583 hepdata https://atlas.web.cern.ch/Atlas/GROUPS/PHYSICS/PAPERS/SUSY-2013-15/ info units ### Details about units for dimensionful quantities energy GeV length mm xsec pb # If using function repository, need to clarify if phi is between 0-2pi or -pi to pi. ==== function ===== function function_name arg1 type-of-arg1 arg2 type-of-arg2 return type-of-returnvalue code link-to-actual-code doc link-to-documentation Rules: * allowed keywords: argX, return, code, doc * argX must count from 1 upwards * it is recommended to follow with a comment about its meaning after each argument * allowed types: int, float, string, bool, detectorobj, tlorentzvector, X-list (X is any of the allowed types) * for type 'detectorobj' it should be clear from the documentation which information the detectorobj needs to have Example: function isolation ### Sums up activity in the vicinity of a given candidate arg1 detectorobj # a single electron, muon or photon arg2 string # "calo", "tracks", "eflow" arg3 float # dR cone to be probed arg4 ptmin # minpt of objects to be counted arg5 bool # divide by candidate's pt? return float # sum of pT of the respective surrounding objects code http://google.de doc http://google.de function overlap ### Checks if the candidate overlaps with any object of the list provided arg1 detectorobj # to be tested candidate arg2 detectorobj-list # to be tested potential neighbours arg3 float # dR cone to be probed return bool # true if any of the neighbours is closer than dR to the candidate code http://overlap.de doc http://overlap.de function hasMediumTag ### Checks if the candidate overlaps with any object of the list provided arg1 detectorobj # electron return bool # true if it is tagged as medium code http://electrons.de/medium code http://electrons.de/medium ==== detectorobj ===== Rules: * Each detectorobj must start with the keyword "take X". X can either be a detectorobj-list X defined before or 'external'. In that case, the list is a fundamental object to be defined globally. * select or reject keywords can filter out specific candidates out of the input list: They have to be followed by a Boolean expression, in which a single candidate of the given detectorobj list can be tested via name.? (see examples) * functions can access previously defined detectorobj-lists by their name, but not the current detectorobj-list itself * additional optional keywords can give more insightful information about commonly used parameters. Example: detectorobj muon_l ### Loose muons take external select isolation(muon_l.?, 'tracks', 0.4, 0.5)<0.1 code http://muons.mu doc http://checkmate.muons.mu detectorobj elec_l ### loose electrons take external select isolation(elec_l.?, 'tracks', 0.4, 0.5)<0.1 reject overlap(elec_l.?, muon_l, 0.4) code http://elecs.el doc http://checkmate.elecs.el detectorobj elec_m ### medium electrons take elec_l select hasMediumTag(elec_l.?) code http://elecs.el/medium doc http://checkmate.elecs.el/medium detectorobj lep ### signal leptons # lep contains medium electrons and loose muons take elec_m take muon_l detectorobj jet ### clustered jets from the calorimeter cells take external algorithm anti-kt R 0.4 ptmin 20 etamax 2.5 code http://jets.jet doc http://checkmate.jets.de ==== cut ===== Rules: * a cut block processes a list of conditions from top to bottom: * 'select ' only lets events pass for which the boolean expression holds true * 'reject ' only lets events pass for which the boolean expression holds false * eff? * trigger? * .OR.? * allowed brackets for functions? Example: cut preselect ### Pre-selection cuts eff 0.95 trigger e_trigger.OR.mu_trigger.OR.met_trigger select lep.1.pt>25 reject lep.size>1 select jet.size>2 select met>100 ==== binning ===== ==== results ===== ==== cutflow ===== info MCsamples ### All information concerning signal and background generation goes here signal Sherpa1.4.1 stop-pair background POWHEG ttbar mtop = 172.5 NLO table maasinfo doc http://singalgenerator.generate doc _benchmark_SLHA_ doc _MG5_model_files_ ==== table ===== table massinfo cut pdgid mass tN_diag 1000022 1 1000006 700 ====== Examples ====== ==== ATLAS, 1 Lepton Stop Search ==== [[http://arxiv.org/abs/1407.0583|Link]] Issues: - pt-selection, identification, overlap removal, isolation are sometimes done in alternating order. This can lead to a plethora of detector-obj. - cuts can be very hard to read and even hard to parse. Maybe one could improve on that info analysis # Details about experiment id SUSY-2013-15 publication JHEP11(2014)118 sqrtS 8.0 lumi 20.0 arXiv 1407.0583 hepdata https://atlas.web.cern.ch/Atlas/GROUPS/PHYSICS/PAPERS/SUSY-2013-15/ info units energy GeV length mm xsec pb function mT ### transverse mass arg1 tlorentzvector # visible particle arg2 tlorentzvector # missing energy vector arg3 float # mass return float # transverse mass code http://google.de doc http://google.de function amT2 ### asymmetric stransverse mass arg1 tlorentzvector # visible particle arg2 tlorentzvector # missing energy vector arg3 float # mass return float # asymmetric stransverse mass code http://google.de doc http://google.de function mT2tau ### Sums up activity in the vicinity of a given candidate arg1 detectorobj # a single electron, muon or photon arg2 string # "calo", "tracks", "eflow" arg3 float # dR cone to be probed arg4 ptmin # minpt of objects to be counted arg5 bool # divide by candidate's pt? return float # sum of pT of the respective surrounding objects code http://google.de doc http://google.de function mHadTop ### Sums up activity in the vicinity of a given candidate arg1 detectorobj # a single electron, muon or photon arg2 string # "calo", "tracks", "eflow" arg3 float # dR cone to be probed arg4 ptmin # minpt of objects to be counted arg5 bool # divide by candidate's pt? return float # sum of pT of the respective surrounding objects code http://google.de doc http://google.de function HTMissSig ### Sums up activity in the vicinity of a given candidate arg1 detectorobj # a single electron, muon or photon arg2 string # "calo", "tracks", "eflow" arg3 float # dR cone to be probed arg4 ptmin # minpt of objects to be counted arg5 bool # divide by candidate's pt? return float # sum of pT of the respective surrounding objects code http://google.de doc http://google.de function HT ### Sums up the scalar pt of the leading n objects in the given list arg1 detectorobj-list # a list of objects arg2 integer # the leading n objects of the list should be counted return float # scalarHT function isBJet ### Checks if a given jet is tagged w.r.t to the given working point efficiency arg1 detectorobj # a single jet which contains btag information arg2 float # the working point signal efficiency within [0, 1] return bool # 'true' if tagged, else false code doc function isTauJet ### Checks if a given jet is tagged w.r.t to the given working point efficiency arg1 detectorobj # a single jet which contains btag information arg2 string # the working point, "loose", "medium", "tight" return bool # 'true' if tagged, else false code doc function isIdentifiedElec ### Checks if a given electron is tagged w.r.t a given ID arg1 detectorobj # a single electron which contains rec+id information arg2 string # the working point, "loose", "medium", "tight" return bool # 'true' if tagged, else false code doc function isIdentifiedMu ### Checks if a given muon is tagged w.r.t a given ID arg1 detectorobj # a single muon which contains rec+id information arg2 string # the working point, "combined" return bool # 'true' if tagged, else false code doc function isIsolated ### Checks surroundings of an object arg1 detectorobj # electron, muon, photon arg2 string # isolation test, "tracks", "calo", "eflow" arg3 float # dR to object to count for isolation arg4 float # ptmin of object to count for isolation arg5 bool # if true, sum(pt) is divided by pt(cand) arg6 float # maximum allowed value of sum(pt) or sum(pt)/pt(cand) return bool # 'true' if sum(pt) < maxval, else false code doc function overlaps ### Checks if the candidate overlaps with any object of the list provided arg1 detectorobj # to be tested candidate arg2 detectorobj-list # to be tested potential neighbours arg3 float # dR cone to be probed return bool # true if any of the neighbours is closer than dR to the candidate code http://overlap.de doc http://overlap.de Now for the detector objects detectorobj jets ### clustered jets from the calorimeter cells take external algorithm anti-kt R 0.4 ptmin 20 etamax 2.5 code http://jets.jet doc http://checkmate.jets.de detectorobj b_jets ### jets with btag take jets select isBJet(b_jets.?, 70) detectorobj nob_jets ### jets without btag take jets reject isBJet(b_jets.?, 70) detectorobj tau_jets_l ### jets with loose tau tag take jets reject isTauJet(tau_jets_l.?, "loose") detectorobj tau_jets_t ### jets with tight tau tag take tau_jets_l reject isTauJet(tau_jets_t.?, "tight") detectorobj elecs_rec ### reconstructed electrons take external detectorobj elecs_l ### loosely reconstructed electrons take elecs_rec select elecs_l.?.pt>7 select elecs_l.?.eta>-2.47 select elecs_l.?.eta<2.47 detectorobj elecs_m ### medium electrons take elecs_l select isIdentifiedEl(elecs_m.?, "medium") select elecs_m.?.pt>10 code http://elecs.el/medium doc http://checkmate.elecs.el/medium detectorobj muons_rec ### reconstructed muons take external detectorobj muons_l take muons_rec select isIdentifiedMu(muons_l.?, "loose") select muons_l.?.pt>6 select muons_l.?.eta>-2.4 select muons_l.?.eta<2.4 detectorobj muons_m take muons_l select isIdentifiedMu(muons_m.?, "medium") select muons_m.?.pt>10 detectorobj nob_jets_iso ### isolated jets take nob_jets reject overlaps(nob_jets.?, elecs_m, 0.2) detectorobj elecs_t_iso ### isolated electrons take elecs_m reject overlaps(elecs_m.?, nob_jets, 0.4) reject overlaps(elecs_m.?, b_jets, 0.2) reject overlaps(elecs_m.?, tau_jets_t, 0.2) select elecs_t_iso.?.pt>25 select isIdentifiedEl(elecs_t_iso.?, "tight") select isIsolated(elecs_t_iso.?, "tracks", 0.2, 0.5, true, 0.1) detectorobj muons_t_iso ### isolated muons take muons_m reject overlaps(muons_m.?, jets, 0.4) select isIsolated(muons_m.?, "tracks", 0.2, 0.5, false, 1.8) detectorobj leptons_l ### loose leptons take muons_l take elecs_l select leptons_l.?.pt>10 detectorobj leptons ### signal leptons take elecs_t_iso take muons_m_iso select leptons.?.pt>25 detectorobj etmiss ### missing et take external cut common select leptons.n=1 select leptons_l.n=1 select jets.n>=4 select etmiss.pt>100 cut dPhi12 select etmiss.dphi(jet.1)>0.8 select etmiss.dphi(jet.2)>0.8 cut leadjets_60to25 jets.1.pt>60 jets.2.pt>60 jets.3.pt>40 jets.4.pt>25 cut leadjets_80to25 jets.1.pt>80 jets.2.pt>60 jets.3.pt>40 jets.4.pt>25 cut leadjets_100to25 jets.1.pt>100 jets.2.pt>80 jets.3.pt>40 jets.4.pt>25 cut leading_bjet select isBJet(jets.1, 70)||isBJet(jets.2, 70)||isBJet(jets.3, 70)||isBJet(jets.4, 70) cut tN_diag select common select leadjets_60to25 select leading_bjet select mT(leptons.1,etmiss)>100 select mHadTop(?,?)>130 select mHadTop(?,?)<205 select tau_jets_t.n=0 select b_jets.1.dR<2.5 ???? select etmiss.pt/HT(jets.1,jets.2,jets.3,jets.4)>5 select dPhi12 CUT tN_med select common select leadjets_80to25 select leading_bjet select etmiss.pt>200 select mT>140 select amT2>170 select mHadTop>130 select mHadTop<195 select HTMissSig>12.5 select dPhi12 CUT tN_high select common select leadjets_80to25 select leading_bjet select etmiss.pt>320 select mT>200 select amT2>170 select mT2tau>120 select mHadTop>130 select mHadTop<250 select dRbl<3.0 select HtMissSig>12.5