Define common LHCb features

[alexpearce]

Newcomers and old-timers alike are often confused about exactly what each branch in their ntuple means. The definitions are usually hard to find, and can even change depending on what DaVinci version you're using.

Looking in a random ntuple, I see branches for:

• Pseudorapidity (ETA)
• Best primary vertex (BPV)
• Impact parameter (IP)
  • χ²
• End vertex (ENDVERTEX)
• Own primary vertex (OWNPV)
  • Number of degrees of freedom (NDOF)
  • χ²
  • Covariance (COV)
• Origin vertex (ORIV)
  • Number of degrees of freedom (NDOF)
  • χ²
  • Covariance (COV)
• Flight distance
  • χ²
• Direction/pointing angle (DIRA)
• Momentum (P{,X,Y,Z})
  • Transverse (PT)
• Energy (PE)
• Mass
  • Measured mass (MM)
    • Error (ERR)
  • Mass (M)
• Lifetime (BPVLTIME)
• Vertex distance
  • χ²
• Distance of closest approach (DOCA)
  • χ² MAX (CHI2MAX)
  • DOCAMAX
• TIS/TOS
• PDG Monte Carlo ID (ID)
• Particle identification
  • CombDLL (PID{e,mu,K,p})
    • RichDLL
    • ...
  • ProbNN (ProbNN{e,k,p,pi,mu,ghost)
  • hasMuon
  • isMuon
  • hasRich
  • hasCalo
• TRACK
  • Type
  • Key
  • χ²
  • Number of degrees of freedom (NDOF)
  • P(χ²)
  • Match χ²
  • Ghost probability (GhostProb)
  • Clone distance (KL distance?)
  • Likelihood
• Multiple candidates
  • nCandidate
  • totCandidates
• Run number
• Event number
• Bunch crossing (BC)
  • ID
  • Type
• Odin
  • TCK
• L0
  • TCK
• HLT
  • TCK
• GpsTime
• Polarity
  nPVs
  • nPV
• Multiplicity
  • nTracks
    • One per track type
  • RICH1/2 hits
  • VELO clusters
  • TT/IT/OT clusters
  • SPD hits
  • Muon hits
  • Muon tracks

It would be awesome to have some (most? all?) of these documented.

I don't know how would be best to present them. Group them by type (PID variables, track variables, trigger variables, vertex variables, …)? One page per branch? One page for all branches?

[ibab]

This could work a bit like API documentation, where you have a single large page (so it's easy to search) with short sections on each variable.

[ibab]

Would be great to have links to the code in the SVN that calculates each variable.

[alexpearce]

Code links for sure, though as the definitions change with time I wouldn't know what version(s) to link to.

If we point to HEAD/latest then the code definition may change without us noticing, but if we point to a specific version we might have to play catch-up every once in a while.

[saschastahl]

Do you want to document Tuple tool names or LoKi names? For LoKi there exist some Twiki pages and doxygen documentation. An overview all Tuple tools would be indeed nice. (Offtopic, one could also train people to just use the Hybrid tool and put the Loki variables on the tree.)
In general, if you want to have links to the code isn't doxygen documentation the way to go?
Some of the variables above are quite generic, so for these a small glossary would be good for newcomers.

[alexpearce]

The list is just what I have in an ntuple. I don't want to re-document LoKi functors, as the TWiki pages are OK.

This issue came up mainly from things like IP χ², where it's not at all obvious where to look for the definition (some motivation for why the definition is what it is would also be nice).