1. 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++
2. 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
3. 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).
4. 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.
5. 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.
6. 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 |).

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 <experiment name=“ATLAS”>. 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

<info name="analysis" id="ATLAS-2014-XXX" publication="JHEP11(2014)118" sqrtS="8.0" lumi="20.0" description="Details about analysis">

There are five types of pre-defined blocks:

1. detectorobj (defines reconstructed objects)
2. function (defines functions that act on these)
3. cut (blocks of cuts)
4. binning (following Daniel's idea, for complex descriptions of orthogonal signal regions)
5. 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.

1. results (for expected, observed, S95, etc.)
2. cutflow (for cutflows)
3. 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 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_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

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

Rules:

• a cut block processes a list of conditions from top to bottom:
  • 'select <bool>' only lets events pass for which the boolean expression holds true
  • 'reject <bool>' 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

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 massinfo
   cut     pdgid      mass
   tN_diag 1000022    1    
           1000006    700

Link Issues:

1. pt-selection, identification, overlap removal, isolation are sometimes done in alternating order. This can lead to a plethora of detector-obj.
2. 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