Table of Contents

Modifications: (19-Jun)

  1. Removed end blocks
  2. Added function arguments (e.g arg1, arg2,..)
  3. Renamed SR to CUT
  4. Inheritance explicitly defined by key 'contains'
  5. Changed cut language to select/reject
  6. Added new info block “units”

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 become sthe 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. 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.

Part I: Preamble (define detector objects, variables)

info analysis
  # Details about experiment 
  id ATLAS-2014-XXX
  publication JHEP11(2014)118
  sqrtS 8.0
  lumi 20.0
 
info units
  energy GeV
  length mm
  xsec pb
  # If using function repository, need to clarify if phi is between 0-2pi or -pi to pi.
 
detectorobj jet
  # detectorobj are lists of objects of same type
  # <detectorobj type="jet" ... >
  # Some human readable definition goes here; we assume sorted by pt
  algorithm anti-kt
  R 0.4
  ptmin 20
  etamax 2.5
  # Can provide code and/or link to writeup with details of implementation
  code _code_link
  doc _link_to_file_with_details
  doc _link_to_doc_about_pilup_removal	
 
function isolation 
  # Takes 2 arguments -- object, conesize; returns (sum of pT in cone of 0.1 around
  # electron)/(pt of lepton) takes in lepton and conesize
  arg1 detectorobj
  arg2 float
  return float
  code _code_link
  doc _link_to_file_with_details	
 
function overlap_removal 
  # takes in jet list and lepton, reduces them to non-overlapping objects
  arg1 detectorobj-list
  arg2 detectorobj-list
  code _code_link
  doc _link_to_file_with_details	
 
detectorobj elec_l
  # Can provide code and/or link to writeup with details of implementation
  cut isolation<0.1
  cut overlap_removal
  code _code_link
  doc _link_to_file_with_details	
 
detectorobj elec_m 
  # electron-medium inherits from loose.
  # Can provide code and/or link to writeup with details of implementation
  contains elec_l
  code _code_link
  doc _link_to_file_with_details	
 
detectorobj lep 
  # lep inherits from medium electrons or muons
  contains elec_m 
  contains mu_m
 
detectorobj met
  # Can provide code and/or link to writeup with details of implementation
  code _code_link
  doc _link_to_file_with_details	
 
cut e_trigger
  # Human readable info
  # Each signal analysis will need atleast one trigger to be satisfied
  # Can provide code and/or link to writeup with details of implementation
  eff 0.8
  code _code_link
  doc _link_to_file_with_details	
 
cut mu_trigger
  # human readable info
  eff 0.8
  code _code_link
  doc _link_to_file_with_details
 
cut met_trigger
  # human readable info
  eff 0.8	   
  code _code_link
  doc _link_to_file_with_details
 
function mt
  # mT requires one lepton and met i.e. mt(lep.1,met)
  arg1 detectorobj
  arg2 detectorobj
  return float
  code _code_link
  doc _link_to_file_with_details
 
 
function b-tag 
  # takes in a jet and returns whether it is b-tagged
  arg1 detectorobj
  return bool
  eff 0.7
  code _code_link
  doc _link_to_file_with_details
 
function select 
  # select(listname, criterion)
  # e.g. select(jet, b-tag) returns number of objects (i.e. jets) give
  # true for the test (i.e. b-tag).  Should be made a global function like pT?
  arg1 detectorobj-list
  arg2 function
  return int
  code _code_link
  doc _link_to_file_with_details
 
detectorobj hadtop
  # Define hadtop 
 
function deltaR 
  # takes in two objects; returns deltaR
  arg1 detectorobj
  arg2 detectorobj
  return float
 
 
function HT
  code _code_
  doc _doc_link_
 
function metBYsqrtHT
  # returns MET/sqrt(HT) 
  return float
 
function delPhi 
  # returns minimum delta phi between objects
  arg1 detectorobj
  arg2 detectorobj
  return float

PART 2: uses the objects defined above to define the signal regions

cut cleaning
  # List of preselection cuts: Give human readable descriptions (for
  # your experimental collaborators) and efficiency for theorists (if applicable)
  code _link_to_code
  doc _link_to_doc
 
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
 
 
cut tN_diag
  contains preselect
  select jet.size>4
  select jet.1.pt>60
  select jet.2.pt>60
  select jet.3.pt>40
  select jet.4.pt>25
  select mt(lep.1,met)>=60
  select m(hadtop)>=130
  select m(hadtop)<=205
  reject size(tau)>0
  select deltaR(bjet.1,lep.1)<2.5
  select metBYsqrtHT>5
  select delPhi(jet.1,met)>0.8
  select delPhi(jet.2,met)>0.8

Part 3: Present results of the analysis. Give numbers, exclusions, digitised histograms, link to plots, etc.

We need to think about information that is absolutely necessary for validation and whether to put it in the same kind of info block (which are currently entirely optional).

info MCsamples
  # Human readable info regarding what programs were used to make what
  # sample suggested format: Signal program extra details (extras are
  # stored in description for xml
  signal Sherpa1.4.1 stop-pair
  background POWHEG ttbar mtop = 172.5 NLO
  doc _link_to_file_with_details
 
result tN_diag
  exp_sig
  stat_sig
  sys_sig
  exp_bg
  stat_bg
  sys_bg
  obs
  s95
  table data1
 
table data1
  # Not real data in example; could be used to provide histograms/tables/likelihoods
  bins nn
  data xlabel ylabel yerr 
   1.0 2.0 1.0
   2.0 1.0 1.0
   3.0 10.0 1.0
   4.0 15.0 1.0