1. D: Maybe the overall description comment should start with '###' as in Python to distinguish from normal '#' comments which the parser should just ignore
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?
4. D: What is the purpose of 'eff' in the cuts and what distinguishes a 'trigger' selection from a normal 'select'?
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')
6. D: Is it possible to use '|' instead of .OR.? the dot to me always refers to a member of a class

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 ATLAS-2014-XXX
  publication JHEP11(2014)118
  sqrtS 8.0
  lumi 20.0

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

Link