Difference between revisions of "Analysis TTreeFormat"

From GlueXWiki
Jump to: navigation, search
(→‎Example: Create & Process Tree)
(→‎Thrown Beam Particle)
 
(624 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
== Why a standard TTree format? ==
+
= TTree Format - Overview =
−
* For any reaction can streamline (and provide a best-practices implementation of): analysis utilities, BDT setup/input, amplitude analysis setup/input(?)
+
* Physics Analysis Root TTree (PART) format.
−
* Makes it easy for users to keep everything organized, especially handling of the combinatoric background.
+
−
* Output can be enabled/disabled with a single flag.
+
−
* Format is designed to be one-size-fits-all, but is still extensible (customizable) at every level (see summary).
+
  
−
== Summary ==
+
=== Data Hierarchy ===
−
* '''Data Structures:'''
+
* One <span style="color:#0000FF">TTree</span> per <span style="color:#0000FF">DReaction</span>, each stored in the ROOT files specified by the user.
−
** <span style="color:#0000FF">DTreeParticle</span>: roughly mirrors <span style="color:#0000FF">DKinematicData</span>: kinematics + PID info of track
+
** e.g., If 2 DReactions: missing & detected recoil proton: 2 different trees, could be in separate files or the same file.  
−
** <span style="color:#0000FF">DTreeStep</span>: roughly mirrors <span style="color:#0000FF">DParticleComboStep</span>: collection of <span style="color:#0000FF">DTreeParticle</span>'s for a given step of a reaction (e.g. photoproduction, &Lambda; decay, &pi;<sup>0</sup> decay, etc.)
+
* One <span style="color:#0000FF">TTree</span> entry per event.
−
** <span style="color:#0000FF">DTreeCombo</span>: roughly mirrors <span style="color:#0000FF">DParticleCombo</span> (collection of <span style="color:#0000FF">DTreeStep</span>'s for a given reaction), + detected particles not used in the combo
+
* All particle data stored in arrays/<span style="color:#0000FF">TClonesArray</span>'s: one array index per particle.
−
** <span style="color:#0000FF">DTreeEvent</span>: contains <span style="color:#0000FF">DTreeCombo</span>'s for each output <span style="color:#0000FF">DReaction</span>, + thrown tracks
+
** Thrown particles
−
* '''Extensible:'''
+
** Reconstructed neutral and charged hypotheses (by default: only used ones, but can save all: DReaction setting)
−
** Each class has maps to contain additional data (<span style="color:#0000FF">TObject</span>* and double, map keys are string): users can add their own custom information here
+
** Beam photons that are later used in combos (unused beam particles are NOT saved)
−
** Otherwise they can make a friend <span style="color:#0000FF">TTree</span> to add branches to the existing tree.
+
** Combo particle information
−
* '''Usage:'''
+
* Event-independent information (e.g. the target, the <span style="color:#0000FF">DReaction</span> decay chain, etc.) is stored in <span style="color:#0000FF">TTree</span>::<span style="color:#008000">fUserInfo</span> (a <span style="color:#0000FF">TList</span>*)
−
** Process with a <span style="color:#0000FF">TSelector</span>.
+
−
** <span style="color:#0000FF">TTree</span>::Draw() and <span style="color:#0000FF">TTree</span>::Project will not work due to nested STL containers.
+
  
−
== Cons ==
+
=== DSelector ===
−
* Data is contained in deques/maps, which causes problems:
+
* Enables C++ interface to TTree data, provides PROOF-Lite launcher, and much more.
−
** Impossible to make them split properly for viewing in the <span style="color:#0000FF">TBrowser</span>.
+
* Instructions for making and using a DSelector can be found at: [[DSelector | Link]]
−
** May (I haven't tested it) make it impossible to use the built-in <span style="color:#0000FF">TTree</span> histogram & cutting options.
+
  
−
== DTreeParticle ==
+
= TTree Format: Simulated Data =
−
* Roughly mirrors <span style="color:#0000FF">DKinematicData</span>: kinematics + PID info of track
+
=== Thrown Non-Particle Data ===
−
* p3, v3, and t are stored at both the start (production) and end points (decay, TOF/BCAL/FCAL hit) of the track. 
+
−
** This is primarily motivated by the &Xi;<sup>-</sup>, which is long-lived and whose trajectory is bent by the magnetic field before it decays.
+
−
* Extensible: maps can be used by users to add their own custom information.
+
 
<syntaxhighlight>
 
<syntaxhighlight>
−
class DTreeParticle : public TObject
+
// EVENT DATA
−
{
+
"RunNumber": UInt_t
−
  public:
+
"EventNumber": ULong64_t
−
    // PID:
+
"MCWeight": Float_t
−
    Particle_t dPID;
+
  
−
    // KINEMATICS:
+
// # PARTICLES //array size of the thrown particle branches
−
      //If kinematic fit was performed, this is the kinematic fit results.  Else is measured results.
+
"NumThrown": UInt_t
−
    TVector3 dPosition_Start; //the position where the particle is produced
+
−
    double dTime_Start; //time of the track at dPosition_Start: if value is not kinfit, is projected from measured TOF/BCAL/FCAL time
+
−
    TVector3 dMomentum_Start; //momentum of the track at dPosition_Start
+
  
−
    TVector3 dPosition_End; //detected particles: the reconstructed position of the BCAL/FCAL/TOF hit; decaying particles: the point where it decays
+
// THROWN REACTION INFO
−
    double dTime_End; //time of the track at dPosition_End
+
"NumPIDThrown_FinalState": ULong64_t //the # of thrown final-state particles (+ pi0) of each type (multiplexed in base 10)
−
    TVector3 dMomentum_End; //momentum of the track at dPosition_End
+
                                      //types (in order from 10^0 -> 10^15): g, e+, e-, nu, mu+, mu-, pi0, pi+, pi-, KLong, K+, K-, n, p, p-bar, n-bar
 +
                                      //e.g. particles decaying from final-state particles are NOT included (e.g. photons from pi0, muons from pions, etc.)
 +
                                    //is sum of #-of-PID * 10^ParticleMultiplexPower() (defined in libraries/include/particleType.h)
 +
                                    //ParticleMultiplexPower() returns a different power of 10 for each final-state PID type.
 +
                                    //A value of 9 should be interpreted as >= 9. 
 +
"PIDThrown_Decaying": ULong64_t //the types of the thrown decaying particles in the event (multiplexed in base 2)
 +
                                //not the quantity of each, just whether or not they were present (1 or 0)
 +
                                //binary power of a PID is given by ParticleMultiplexPower() (defined in libraries/include/particleType.h)
 +
                                //types: most Particle_t's that aren't final state (e.g. lambda, eta, phi, rho0, etc.) see ParticleMultiplexPower()
 +
</syntaxhighlight>
  
−
    double dPathLength; //from dPosition_Start to dPosition_End
+
=== Thrown Beam Particle ===
−
    TMatrixDSym dCovarianceMatrix; //at dPosition_Start // Order is (px, py, pz, x, y, z, t)
+
* All branch names are prefixed with <span style="color:red">"ThrownBeam__"</span>
 +
<syntaxhighlight>
 +
//IDENTIFIER
 +
"PID": Int_t //PDG ID value
  
−
    // PID QUALITY:
+
//KINEMATICS: //At the production vertex
−
    unsigned int dNDF_Tracking; //0 if neutral or decaying
+
"X4": TLorentzVector //This is the TAGGED energy //Use THIS for binning your results //Is ZERO if NOT TAGGED
−
    double dChiSq_Tracking; //NaN if neutral or decaying
+
"P4": TLorentzVector
−
    unsigned int dNDF_Timing; //0 if no TOF/BCAL/FCAL hit (e.g. slow protons)
+
"GeneratedEnergy": Float_t
−
    double dChiSq_Timing; //NaN if no TOF/BCAL/FCAL hit (e.g. slow protons)
+
</syntaxhighlight>
−
    unsigned int dNDF_DCdEdx; //0 if neutral or decaying
+
−
    double dChiSq_DCdEdx; //NaN if neutral or decaying
+
  
−
    // DEPOSITED ENERGY:
+
=== Thrown Products ===
−
      //0.0 if no hit
+
* All branch names are prefixed with <span style="color:red">"Thrown__"</span>
−
    double ddEdx_FDC;
+
* NOTE: The only contains particles corresponding to the <span style="color:red">"FinalState"</span> and <span style="color:red">"Decaying"</span> tags of <span style="color:#0000FF">DMCThrown</span>.
−
    double ddEdx_CDC;
+
** In other words: No resonances, no decay products of final-state particles, and no orphan particles.
−
    double dEnergy_BCAL;
+
<syntaxhighlight>
−
    double dEnergy_FCAL;
+
//IDENTIFIERS / MATCHING
−
    double dEnergy_TOF;
+
"ParentIndex": Int_t["NumThrown"] //the thrown particle array index of the particle this particle decayed from (-1 if none (e.g. photoproduced))
 +
"PID": Int_t["NumThrown"] //PDG ID value
  
−
    // DTREESTEP POINTERS:
+
//MATCHING //only present if reconstructed data present (i.e. not if thrown-only tree)
−
    DTreeStep* dProductionStep; //the step object in which this DTreeParticle is produced (is a final-state particle)
+
"MatchID": Int_t["NumThrown"] //the "NeutralID"/"TrackID" of the reconstructed neutral/track that it is matched with (-1 for no match)
−
    DTreeStep* dDecayStep; //the step object in which this DTreeParticle decays (is an initial-state particle) (will be null if not a decaying particle!)
+
"MatchFOM": Float_t["NumThrown"] //Neutrals: confidence level //Tracks: #-matched-hits * hit_fraction //(-1 for no match)
  
−
    // CUSTOM VARIABLES:
+
//KINEMATICS: //Reported at the particle's production vertex
−
    map<string, double> dCustomVariables; //key is unique string, double is value
+
"X4": TClonesArray(TLorentzVector["NumThrown"])
−
    map<string, const TObject*> dCustomObjects; //key is unique string, TObject* is object
+
"P4": TClonesArray(TLorentzVector["NumThrown"])
 +
</syntaxhighlight>
  
−
  ClassDef(DTreeParticle, 1)
+
= TTree Format: Combo-Independent Data =
−
};
+
 
 +
=== Non-Particle Data ===
 +
<syntaxhighlight>
 +
// EVENT DATA
 +
"RunNumber": UInt_t
 +
"EventNumber": ULong64_t
 +
"L1TriggerBits": UInt_t
 +
 
 +
// PRODUCTION SPACETIME
 +
"X4_Production": TLorentzVector //V3 from DVertex (kinfit), t from RF (propagated to V3)
 +
 
 +
// # PARTICLES //these are the array sizes for the particle branches
 +
"NumBeam": UInt_t
 +
"NumChargedHypos": UInt_t
 +
"NumNeutralHypos": UInt_t
 +
 
 +
// TOPOLOGY //only present if simulated data
 +
"IsThrownTopology": Bool_t //Does the DReaction decay chain match the thrown decay chain
 +
 
 +
// UNUSED TRACKS
 +
"NumUnusedTracks": UChar_t
 +
 
 +
//NUM COMBOS
 +
"NumCombos": UInt_t //size of all of the particle-combo-content arrays
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== DTreeStep ==
+
=== Beam Particles <span style="color:blue">(If Used in Combo) ===
−
* Roughly mirrors <span style="color:#0000FF">DParticleComboStep</span>: collection of <span style="color:#0000FF">DTreeParticle</span>'s for a given step of a reaction (e.g. photoproduction, &Lambda; decay, &pi;<sup>0</sup> decay, etc.)
+
* Only the beam particles that are included in at least one combo are present.
−
* Extensible: maps can be used by users to add their own custom information.
+
* All branch names are prefixed with <span style="color:red">"Beam__"</span>
 
<syntaxhighlight>
 
<syntaxhighlight>
−
class DTreeStep : public TObject
+
//ONLY PRESENT IF BEAM USED IN PARTICLE COMBOS
−
{
+
−
  public:
+
−
    // INITIAL PARTICLES:
+
−
    const DTreeParticle* dInitialParticle; //if is null: decaying or beam particle not yet set!
+
−
    const DTreeParticle* dTargetParticle; //NULL for no target
+
  
−
    // FINAL PARTICLES:
+
//IDENTIFIERS / MATCHING
−
    deque<DParticle_t> dFinalParticleIDs; //separate in case particle is NULL (e.g. decaying resonance)
+
"PID": Int_t["NumBeam"] //PDG ID value
−
    deque<const DTreeParticle*> dFinalParticles; //particle may be NULL if it is decaying or missing (especially if no kinematic fit was performed!!)
+
"IsGenerator": Bool_t["NumBeam"] // kTRUE/kFALSE if matches the generator beam photon (-1 for no match) //only present if simulated data
  
−
    // CUSTOM VARIABLES:
+
//KINEMATICS: MEASURED //At the production vertex
−
    map<string, double> dCustomVariables; //key is unique string, double is value
+
"X4_Measured": TClonesArray(TLorentzVector["NumBeam"]) //position is at the production vertex (same as X4_Production(), except the time)
−
    map<string, const TObject*> dCustomObjects; //key is unique string, TObject* is object
+
"P4_Measured": TClonesArray(TLorentzVector["NumBeam"])
 +
</syntaxhighlight>
  
−
  ClassDef(DTreeStep, 1)
+
=== Charged Track Hypotheses ===
−
};
+
* Includes all hypotheses, whether they appear in the combos or not.
 +
* All branch names are prefixed with <span style="color:red">"ChargedHypo__"</span>
 +
<syntaxhighlight>
 +
//IDENTIFIERS / MATCHING
 +
"TrackID": Int_t["NumChargedHypos"] //each physical particle has its own # (to keep track of different pid hypotheses for the same particle)
 +
"PID": Int_t["NumChargedHypos"] //PDG ID value
 +
"ThrownIndex": Int_t["NumChargedHypos"] //the array index of the thrown particle it is matched with (-1 for no match) //only present if simulated data
 +
 
 +
//KINEMATICS: MEASURED  //At the production vertex
 +
"P4_Measured": TClonesArray(TLorentzVector["NumChargedHypos"])
 +
"X4_Measured": TClonesArray(TLorentzVector["NumChargedHypos"]) //t is the measured value in TOF/BCAL/FCAL projected back to Position_Measured
 +
 
 +
//TRACKING INFO:
 +
"NDF_Tracking": UInt_t["NumChargedHypos"]
 +
"ChiSq_Tracking": Float_t["NumChargedHypos"]
 +
"NDF_DCdEdx": UInt_t["NumChargedHypos"]
 +
"ChiSq_DCdEdx": Float_t["NumChargedHypos"]
 +
"dEdx_CDC": Float_t["NumChargedHypos"]
 +
"dEdx_FDC": Float_t["NumChargedHypos"]
 +
 
 +
//TIMING INFO
 +
"HitTime": Float_t["NumChargedHypos"] //the system that is hit is in order of preference: BCAL/TOF/FCAL/ST
 +
                                      //to determine which, look whether energy was deposited in these systems
 +
"RFDeltaTVar": Float_t["NumChargedHypos"] //Variance of X4_Measured.T() - RFTime, regardless of which RF bunch is chosen.
 +
                                          //Can be used to compute timing ChiSq //RF bunch is combo-dependent
 +
 
 +
//PID INFO
 +
"Beta_Timing": Float_t["NumChargedHypos"] // = Path_Length/(c*Delta_t)
 +
"ChiSq_Timing": Float_t["NumChargedHypos"]
 +
"NDF_Timing": UInt_t["NumChargedHypos"]
 +
 
 +
//HIT ENERGY:
 +
"dEdx_TOF": Float_t["NumChargedHypos"]
 +
"dEdx_ST": Float_t["NumChargedHypos"]
 +
"Energy_BCAL": Float_t["NumChargedHypos"]
 +
"Energy_BCALPreshower": Float_t["NumChargedHypos"]
 +
"Energy_FCAL": Float_t["NumChargedHypos"]
 +
 
 +
//SHOWER WIDTH:
 +
"SigLong_BCAL" Float_t["NumChargedHypos"] // Longitudinal (outward radially from the target) shower width
 +
"SigTheta_BCAL" Float_t["NumChargedHypos"] // Theta shower width
 +
"SigTrans_BCAL" Float_t["NumChargedHypos"] // Transverse (azimuthal) shower width
 +
 
 +
//SHOWER MATCHING:
 +
"TrackBCAL_DeltaPhi": Float_t["NumChargedHypos"] //999.0 if not matched //units are radians
 +
"TrackBCAL_DeltaZ": Float_t["NumChargedHypos"] //999.0 if not matched //Track position - BCAL Shower
 +
"TrackFCAL_DOCA": Float_t["NumChargedHypos"] //999.0 if not matched
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== DTreeCombo ==
+
=== Neutral Particle Hypotheses ===
−
* Roughly mirrors <span style="color:#0000FF">DParticleCombo</span> (collection of <span style="color:#0000FF">DTreeStep</span>'s for a given reaction), + detected particles not used in the combo
+
* All branch names are prefixed with <span style="color:red">"NeutralHypo__"</span>
−
* Extensible: maps can be used by users to add their own custom information.  
+
* Includes all hypotheses, whether they appear in the combos or not.
 +
* Discussion on P4 & X4:
 +
** Note that P4 is not present because it is defined by X4, and X4 is not present because it is defined by the tracks, which are combo-dependent
 +
** For combo particles, P4 & X4 are listed for each combo
 +
** If not used in a combo, can be computed using the shower hit information and the vertex & RF-time of your choosing (e.g. combo production-vertex, RF-time)
 +
* To determine whether is BCAL or FCAL, see which system has non-zero energy
 
<syntaxhighlight>
 
<syntaxhighlight>
−
class DTreeCombo : public TObject
+
//IDENTIFIERS / MATCHING
−
{
+
"NeutralID": Int_t["NumNeutralHypos"] //each physical particle has its own # (to keep track of different pid hypotheses for the same particle)
−
  public:
+
"PID": Int_t["NumNeutralHypos"] //PDG ID value
−
    // STEPS:
+
"ThrownIndex": Int_t["NumNeutralHypos"] //the array index of the thrown particle it is matched with (-1 for no match) //only present if simulated data
−
    deque<const DTreeStep*> dTreeSteps;
+
  
−
    // RF:
+
//KINEMATICS: MEASURED  //At the production vertex
−
    bool dRFTimeMatchQuality; //true if good (certain), false if bad (not confident in value (e.g. no "good" tracks have TOF hits))
+
"P4_Measured": TClonesArray(TLorentzVector["NumNeutralHypos"])
−
    double dRFTime;
+
"X4_Measured": TClonesArray(TLorentzVector["NumNeutralHypos"]) //t is the measured value in TOF/BCAL/FCAL projected back to Position_Measured
−
    double dRFTimeUncertainty;
+
  
−
    // UNUSED PARTICLES:
+
//MEASURED PID INFO
−
    vector<const DTreeParticle*> dUnusedDetectedParticles;
+
"Beta_Timing": Float_t["NumNeutralHypos"] // = Path_Length/(c*Delta_t)
−
    vector<const DTreeShower*> dUnusedDetectedShowers;
+
"ChiSq_Timing": Float_t["NumNeutralHypos"] //-1 if not photon
 +
"NDF_Timing": UInt_t["NumNeutralHypos"] //0 if not photon
  
−
    // KINEMATIC FIT:
+
//SHOWER INFO
−
    DKinFitType dKinematicFitType; //Defined in DKinFitResults.h //d_NoFit if not performed
+
"X4_Shower": Float_t["NumNeutralHypos"] //location/time of the reconstructed shower
−
    double dChiSq_KinematicFit; //NaN if not performed
+
"Energy_BCAL": Float_t["NumNeutralHypos"] //is 0.0 if shower in FCAL
−
    unsigned int dNDF_KinematicFit; //0 if not performed
+
"Energy_BCALPreshower": Float_t["NumNeutralHypos"] //is 0.0 if shower in FCAL
 +
"Energy_FCAL": Float_t["NumNeutralHypos"] //is 0.0 if shower in BCAL
  
−
    // CUSTOM VARIABLES:
+
//SHOWER WIDTH:
−
    map<string, double> dCustomVariables; //key is unique string, double is value
+
"SigLong_BCAL" Float_t["NumNeutralHypos"] // Longitudinal (outward radially from the target) shower width
−
    map<string, const TObject*> dCustomObjects; //key is unique string, TObject* is object
+
"SigTheta_BCAL" Float_t["NumNeutralHypos"] // Theta shower width
 +
"SigTrans_BCAL" Float_t["NumNeutralHypos"] // Transverse (azimuthal) shower width
  
−
  ClassDef(DTreeCombo, 1)
+
//NEARBY TRACKS
−
};
+
"TrackBCAL_DeltaPhi": Float_t["NumNeutralHypos"] //is delta to nearest track, is 999.0 if no tracks on BCAL
 +
"TrackBCAL_DeltaZ": Float_t["NumNeutralHypos"] //is delta to nearest track, is 999.0 if no tracks on BCAL
 +
"TrackFCAL_DOCA": Float_t["NumNeutralHypos"] //is DOCA to nearest track, is 999.0 if no tracks on FCAL
 +
 
 +
//PHOTON PID INFO
 +
  //Computed using DVertex (best estimate of reaction vertex using all "good" tracks)
 +
  //Can be used to compute timing chisq //is invalid (0) for non-photons
 +
"PhotonRFDeltaTVar": Float_t["NumNeutralHypos"] //Variance of DVertexX4.T() - RFTime, regardless of which RF bunch is chosen. //RF bunch is combo-dependent
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== DTreeEvent ==
+
= TTree Format: Combo-Dependent Data =  
−
* Contains <span style="color:#0000FF">DTreeCombo</span>'s for each output <span style="color:#0000FF">DReaction</span>, + thrown tracks
+
* All particle combo data is stored in arrays: array entries correspond to different particle combos
−
* Extensible: maps can be used by users to add their own custom information.
+
 
 +
=== Particle-Independent Data ===
 
<syntaxhighlight>
 
<syntaxhighlight>
−
class DTreeEvent : public TObject
+
//CUT FLAG
−
{
+
"IsComboCut": Bool_t["NumCombos"] //if true, combo has been previously cut (all kFALSE originally, user can apply cuts in TSelector, change this flag, and output new TTree)
−
  public:
+
−
    // RUN, EVENT #'s:
+
−
    unsigned int dRunNumber;
+
−
    unsigned int dEventNumber;
+
  
−
    // DATA:
+
//COMBO THROWN MATCHING //not present if not simulated data
−
    map<string, deque<const DTreeCombo*> > dTreeCombos; //string key is (D)Reaction name, deque is the particle combos
+
"IsTrueCombo": Bool_t["NumCombos"] //"IsThrownTopology" = kTRUE, each particle has the right PID, and the combo particle chain matches the thrown decay chain
−
    deque<const DTreeParticle*> dThrownParticles;
+
"IsBDTSignalCombo": Bool_t["NumCombos"] //Similar to "IsTrueCombo", except other thrown topologies that decay to the DReaction topology are marked as signal
 +
                                        //Note that if you have an &omega; or &phi; in your DReaction, you still have to filter your combos prior to BDT
 +
                                        //input to remove duplicate entries. This is because the omega & phi masses are not constrained in the kinematic fit,  
 +
                                        //nor should they be in the BDT, so you have duplicate entries from the point-of-view of the BDT due to combinatorics
 +
                                        //(e.g. which pions decayed from the omega, and which ones didn't, are irrelevant to the BDT).
  
−
    // CUSTOM VARIABLES:
+
//RF
−
    map<string, double> dCustomVariables; //key is unique string, double is value
+
"RFTime_Measured": Float_t["NumCombos"] //reported at center of target
−
    map<string, const TObject*> dCustomObjects; //key is unique string, TObject* is object
+
"RFTime_KinFit": Float_t["NumCombos"] //reported at center of target //only if spacetime kinematic fit performed
 +
 
 +
//KINEMATIC FIT
 +
"ChiSq_KinFit": Float_t["NumCombos"] //only if kinematic fit performed
 +
"NDF_KinFit": UInt_t["NumCombos"] //only if kinematic fit performed // = 0 if kinematic fit doesn't converge
 +
 
 +
//UNUSED ENERGY
 +
"Energy_UnusedShowers": Float_t["NumCombos"] // summed energy of neutral showers in the event not included in the combo (requiring unused showers are in time and have a polar angle > 2 degrees to reduce contamination from EM background)
 +
 
 +
//UNUSED TRACKS //For tracks unused by combo, the hypo chosen is the one with the best tracking FOM
 +
"SumPMag_UnusedTracks": Float_t["NumCombos"]
 +
"SumP3_UnusedTracks": TClonesArray(TVector3["NumCombos"])
  
−
  ClassDef(DTreeEvent, 1)
 
−
};
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== Usage Example: Create & Process Tree ==
+
=== Particle Branch-Name Prefixes ===
−
* ROOT doesn't do a good job of properly handling nested STL containers as branches inside of <span style="color:#0000FF">TTree</span>'s.  Therefore:
+
−
** rootcint is used to create a shared object library containing the <span style="color:#0000FF">DTreeEvent</span>, <span style="color:#0000FF">DTreeParticle</span>, etc. objects, which then needs to be loaded prior to processing the <span style="color:#0000FF">TTree</span>.
+
−
** Only one branch is created: the one for <span style="color:#0000FF">DTreeEvent</span>.
+
−
** <span style="color:#0000FF">TTree</span>::Draw() and <span style="color:#0000FF">TTree</span>::Project() don't work.
+
  
−
=== Create Tree ===
+
Example Reaction (b1pi):
−
* This would be done "under-the-hood" in DANA, but a simple example is shown here: 1 event containing 1 combo, 1 step and 1 particle
+
* &gamma; p &rarr;&omega;, &pi;<sup>+</sup>, &pi;<sup>-</sup>, (p)
 +
** &omega; &rarr; &pi;<sup>+</sup>, &pi;<sup>-</sup>, &pi;<sup>0</sup>
 +
*** &pi;<sup>0</sup> &rarr; &gamma; &gamma;
 +
 
 +
'''Branch Names:'''
 +
* Beam: <span style="color:red">"ComboBeam"</span>
 +
* Detected: <span style="color:red">"PiMinus1"</span>, <span style="color:red">"PiPlus1"</span>, <span style="color:red">"PiPlus2"</span>, <span style="color:red">"PiMinus2"</span>, <span style="color:red">"Photon1"</span>, <span style="color:red">"Photon2"</span>
 +
* Decaying: <span style="color:red">"DecayingPi0"</span>
 +
* Missing: <span style="color:red">"MissingProton"</span>
 +
 
 +
=== Combo Beam Particles <span style="color:blue">(If Any)</span> ===
 +
* All branch names are prefixed with <span style="color:red">"ComboBeam__"</span>
 +
** E.g. <span style="color:red">"ComboBeam__BeamIndex"</span>
 
<syntaxhighlight>
 
<syntaxhighlight>
−
void Create_Tree(void)
+
//IDENTIFIER
−
{
+
"BeamIndex": Int_t["NumCombos"] //array index to the "Beam__" branches that correspond to this particle
−
  //load library, create file & tree
+
−
  gSystem->Load("libBANA_ROOT_TREE.so");
+
−
  TFile* locFile = new TFile("test.root", "RECREATE");
+
−
  TTree* locTree = new TTree("testtree", "testtree");
+
  
−
  //create event: THE ONLY BRANCH ON THE TREE (set run & event #'s)
+
//KINEMATICS: KINFIT //At the interaction vertex //only present if kinfit performed
−
  DTreeEvent* locTreeEvent = new DTreeEvent();
+
"X4_KinFit": TClonesArray(TLorentzVector["NumCombos"]) //not present if p4-only fit
−
  locTree->Branch("dTreeEvent", locTreeEvent, 32000, 0); //splitlevel = 0 makes sure no sub-branches are created (ROOT doesn't do them correctly)
+
"P4_KinFit": TClonesArray(TLorentzVector["NumCombos"]) //not present if vertex-only or spacetime-only fit, unless beam is charged
−
  locTreeEvent->dRunNumber = 12345;
+
</syntaxhighlight>
−
  locTreeEvent->dEventNumber = 67890;
+
  
−
  //create a step with one particle in it, set start time
+
=== Combo Tracks <span style="color:blue">(If Any)</span> ===
−
  DTreeStep* locTreeStep = new DTreeStep();
+
* All branch names are prefixed with the particle name
−
  DTreeParticle* locTreeParticle = new DTreeParticle();
+
** E.g. <span style="color:red">"Proton__ChargedIndex"</span>, <span style="color:red">"PiMinus1__P4_KinFit"</span>
−
  locTreeParticle->dTime_Start = 2.0;
+
<syntaxhighlight>
−
  locTreeStep->dFinalParticles.push_back(locTreeParticle);
+
//IDENTIFIER
 +
"ChargedIndex": Int_t["NumCombos"] //array index to the "ChargedHypo__" branches that correspond to this particle
  
−
  //put the step in the combo
+
//PID INFO: MEASURED //using combo RF bunch
−
  DTreeCombo* locTreeCombo = new DTreeCombo();
+
"Beta_Timing_Measured": Float_t["NumCombos"] // = Path_Length/(c*Delta_t)
−
  locTreeCombo->dTreeSteps.push_back(locTreeStep);
+
"ChiSq_Timing_Measured": Float_t["NumCombos"]
  
−
  //put the combo in the tree
+
//PID INFO: KINFIT //using combo RF bunch //not present if time constrained //uses combo vertex & p4 if kinfit
−
  deque<const DTreeCombo*> locCombos;
+
"Beta_Timing_KinFit": Float_t["NumCombos"] // = Path_Length/(c*Delta_t)
−
  locCombos.push_back(locTreeCombo);
+
"ChiSq_Timing_KinFit": Float_t["NumCombos"]
−
  string locReactionName = "TestReaction";
+
−
  locTreeEvent->dTreeCombos[locReactionName] = locCombos;
+
  
−
  locTree->Fill();
+
//KINEMATIC FIT KINEMATICS //only present if kinfit performed
−
  locFile->Write();
+
"X4_KinFit": TClonesArray(TLorentzVector["NumCombos"]) //not present if p4-only fit
−
  locFile->Close();
+
"P4_KinFit": TClonesArray(TLorentzVector["NumCombos"])
−
}
+
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
=== Sample TSelector ===
+
=== Combo Neutrals <span style="color:blue">(If Any)</span> ===
 +
* All branch names are prefixed with the particle name
 +
** E.g. <span style="color:red">"Photon1__NeutralIndex"</span>, <span style="color:red">"Neutron__P4_KinFit"</span>
 
<syntaxhighlight>
 
<syntaxhighlight>
−
Bool_t MySelector::Process(Long64_t entry)
+
//IDENTIFIER
−
{
+
"NeutralIndex": Int_t["NumCombos"] //array index to the "NeutralHypo__" branches that correspond to this particle
−
  //dTreeEvent IS THE ONLY BRANCH (DTreeEvent*)
+
                                  //Note that they may not have the same PID (and thus P4) as this!!
−
  GetEntry(entry);
+
                                      //If this is a PID not created by default (e.g. K0Long)
  
−
  cout << "run, event #'s: " << dTreeEvent->dRunNumber << ", " << dTreeEvent->dEventNumber << endl;
+
//KINEMATICS: MEASURED  //At the production vertex
 +
"P4_Measured": TClonesArray(TLorentzVector["NumCombos"])
 +
"X4_Measured": TClonesArray(TLorentzVector["NumCombos"]) //t is the measured value in TOF/BCAL/FCAL projected back to Position_Measured
  
−
  //get the combos for the given reaction
+
//MEASURED PID INFO
−
  string locReactionName = "TestReaction";
+
"Beta_Timing_Measured": Float_t["NumCombos"] // = Path_Length/(c*Delta_t)
−
  deque<const DTreeCombo*> locTreeCombos = dTreeEvent->dTreeCombos[locReactionName];
+
"ChiSq_Timing_Measured": Float_t["NumCombos"] //only present if photon
  
−
  //grab the step, particle, and start time
+
//KINEMATIC FIT PID INFO
−
  const DTreeStep* locTreeStep = locTreeCombos[0]->dTreeSteps[0];
+
"Beta_Timing_KinFit": Float_t["NumCombos"] // = Path_Length/(c*Delta_t) //not present if p4-only fit
−
  const DTreeParticle* locTreeParticle = locTreeStep->dFinalParticles[0];
+
"ChiSq_Timing_KinFit": Float_t["NumCombos"] //only present if photon //not present if p4-only fit
−
  cout << "t = " << locTreeParticle->dTime_Start << endl;
+
 
−
}
+
//KINEMATIC FIT KINEMATICS //only present if kinfit performed
 +
"X4_KinFit": TClonesArray(TLorentzVector["NumCombos"]) //not present if p4-only fit
 +
"P4_KinFit": TClonesArray(TLorentzVector["NumCombos"])
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
=== Process Tree ===
+
=== Combo Decaying Particles <span style="color:blue">(If Any, If Detached/KinFit)</span> ===
 +
* All branch names are prefixed with <span style="color:red">"Decaying"</span> and the particle name
 +
** E.g.: <span style="color:red">"DecayingPi0__X4"</span>
 
<syntaxhighlight>
 
<syntaxhighlight>
−
void Process_Tree(void)
 
−
{
 
−
  string locHallDHome = getenv("HALLD_HOME");
 
−
  string locIncludePath = locHallDHome + string("/include/");
 
−
  gInterpreter->AddIncludePath(locIncludePath.c_str()); //for particleType.h and whatever else is needed
 
−
  gSystem->Load("libBANA_ROOT_TREE.so"); //load the class definitions so that can read the "dTreeEvent" tree branch
 
  
−
  TFile* locFile = new TFile("test.root", "READ");
+
//KINEMATICS: //At the decay vertex
−
  TTree* locTree = (TTree*)locFile->Get("testtree");
+
"X4": TLorentzVector["NumCombos"] //only present if has a detached vertex //kinematic fit result if kinfit performed, else reconstructed from detected particles
−
  locTree->Process("MySelector.C"); //process this TSelector
+
"PathLengthSigma": Float_t["NumCombos"] //only present if has a detached vertex and both vertices are fit
−
}
+
"P4_KinFit": TLorentzVector["NumCombos"] //only present if kinfit performed
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
=== Combo Missing Particles <span style="color:blue">(If Any & If KinFit)</span> ===
 +
* All branch names are prefixed with <span style="color:red">"Missing"</span> and the particle name
 +
** E.g.: <span style="color:red">"MissingProton__P4_KinFit"</span>
 +
<syntaxhighlight>
 +
//KINFIT KINEMATICS: //At its production vertex //only present if kinfit performed
 +
"P4_KinFit": TLorentzVector["NumCombos"]
 +
</syntaxhighlight>
 +
 +
= TTree Format: <span style="color:#0000FF">DReaction</span> Info =
 +
* Stored in <span style="color:#0000FF">TTree</span>::<span style="color:#008000">fUserInfo</span> (a <span style="color:#0000FF">TList</span>*)
 +
 +
* <span style="color:red">"ParticleNameList"</span>: <span style="color:#0000FF">TList</span> of the names of the reaction particles in the tree, in the order they were specified in the <span style="color:#0000FF">DReaction</span>.
 +
 +
* <span style="color:red">"MiscInfoMap"</span>: <span style="color:#0000FF">TMap</span> of <span style="color:#0000FF">TObjString</span> -> <span style="color:#0000FF">TObjString</span>
 +
** <span style="color:red">"KinFitType"</span> -> <span style="color:#0000FF">DKinFitType</span> (converted to <span style="color:#0000FF">TObjString</span>)
 +
** <span style="color:red">"Target__PID"</span> -> <span style="color:#0000FF">int</span> (converted to <span style="color:#0000FF">TObjString</span>): PDG PID of target particle //if a target particle was specified
 +
** <span style="color:red">"Target__Mass"</span> -> <span style="color:#0000FF">double</span> (converted to <span style="color:#0000FF">TObjString</span>): Mass of the target particle. //if a target particle was specified
 +
** <span style="color:red">"Missing__PID"</span> -> <span style="color:#0000FF">int</span> (converted to <span style="color:#0000FF">TObjString</span>): PDG PID of missing particle //if a missing particle was specified
 +
** <span style="color:red">"Target__CenterX"</span> -> <span style="color:#0000FF">double</span> (converted to <span style="color:#0000FF">TObjString</span>): x-coordinate of target center
 +
** <span style="color:red">"Target__CenterY"</span> -> <span style="color:#0000FF">double</span> (converted to <span style="color:#0000FF">TObjString</span>): y-coordinate of target center
 +
** <span style="color:red">"Target__CenterZ"</span> -> <span style="color:#0000FF">double</span> (converted to <span style="color:#0000FF">TObjString</span>): z-coordinate of target center
 +
** <span style="color:red">"MissingNAME__Mass"</span> -> <span style="color:#0000FF">double</span> (converted to <span style="color:#0000FF">TObjString</span>): Mass of the <span style="color:red">'NAME'</span> missing particle (e.g. <span style="color:red">'NAME'</span> = <span style="color:red">Proton</span>). //if a missing particle was specified
 +
** <span style="color:red">"DecayingNAME__Mass"</span> -> <span style="color:#0000FF">double</span> (converted to <span style="color:#0000FF">TObjString</span>): Mass of the <span style="color:red">'NAME'</span> decaying particle (e.g. <span style="color:red">'NAME'</span> = <span style="color:red">Pi0</span>). //if decaying particles were present
 +
 +
* <span style="color:red">"NameToPIDMap"</span>: <span style="color:#0000FF">TMap</span> of <span style="color:red">"UniqueParticleName"</span> (<span style="color:#0000FF">TObjString</span>) -> <span style="color:#0000FF">int</span> (PDG) (converted to <span style="color:#0000FF">TObjString</span>)
 +
 +
* <span style="color:red">"NameToPositionMap"</span>: <span style="color:#0000FF">TMap</span> of <span style="color:red">"UniqueParticleName"</span> (<span style="color:#0000FF">TObjString</span>) -> <span style="color:red">"StepIndex_ParticleIndex"</span> (stored in <span style="color:#0000FF">TObjString</span>) (ParticleIndex = <span style="color:red">-1</span> for initial, <span style="color:red">-2</span> for target, <span style="color:red">0+</span> for final state)
 +
 +
* <span style="color:red">"PositionToNameMap"</span>: <span style="color:#0000FF">TMap</span> of <span style="color:red">"StepIndex_ParticleIndex"</span> (stored in <span style="color:#0000FF">TObjString</span>) (ParticleIndex = <span style="color:red">-1</span> for initial, <span style="color:red">-2</span> for target, <span style="color:red">0+</span> for final state) -> <span style="color:red">"UniqueParticleName"</span> (<span style="color:#0000FF">TObjString</span>)
 +
 +
* <span style="color:red">"PositionToPIDMap"</span>: <span style="color:#0000FF">TMap</span> of <span style="color:red">"StepIndex_ParticleIndex"</span> (stored in <span style="color:#0000FF">TObjString</span>) (ParticleIndex = <span style="color:red">-1</span> for initial, <span style="color:red">-2</span> for target, <span style="color:red">0+</span> for final state) -> <span style="color:#0000FF">int</span> (PDG) (converted to <span style="color:#0000FF">TObjString</span>)
 +
 +
* <span style="color:red">"DecayProductMap"</span>: <span style="color:#0000FF">TMap</span> of <span style="color:red">"DecayingParticleName"</span> (<span style="color:#0000FF">TObjString</span>) -> <span style="color:red">"DecayProductNames"</span> (stored in a <span style="color:#0000FF">TList</span> of <span style="color:#0000FF">TObjString</span> objects).  Excludes resonances and intermediate decays (e.g. if &Xi;<sup>-</sup>&rarr;&pi;<sup>-</sup>&Lambda;&rarr;&pi;<sup>-</sup>&pi;<sup>-</sup>p: will be &Xi;<sup>-</sup>&rarr;&pi;<sup>-</sup>&pi;<sup>-</sup>p and &Lambda; decay not listed)
 +
 +
= Usage =
 +
 +
=== Create TTrees ===
 +
* To save data to a <span style="color:#0000FF">TTree</span> for a given <span style="color:#0000FF">DReaction</span>, <span style="color:#0000FF">TTree</span> output must be first be enabled for that reaction.  See [https://halldweb.jlab.org/wiki/index.php/Analysis_DReaction#DReaction_Control_Variables DReaction Control Variables] for details. 
 +
** Note: Only one thrown tree will be created during program execution. If the <span style="color:#0000FF">DEventWriterROOT</span>::<span style="color:#008000">Create_ThrownTree</span>() function is called more than once, nothing happens on subsequent calls.
 +
 +
<syntaxhighlight>
 +
#include "ANALYSIS/DEventWriterROOT.h"
 +
//In plugin brun():
 +
const DEventWriterROOT* locEventWriterROOT = NULL;
 +
locEventLoop->GetSingle(locEventWriterROOT);
 +
locEventWriterROOT->Create_DataTrees(locEventLoop); //creates TTrees for all output-enabled DReactions
 +
locEventWriterROOT->Create_ThrownTree("tree_b1pi_thrownmc.root"); //optional: create a ttree containing only the thrown data //string is output file name
 +
</syntaxhighlight>
 +
 +
=== Save Data to TTree ===
 +
* The below only saves the particle combinations (for <span style="color:#0000FF">TTree</span>-output-enabled <span style="color:#0000FF">DReaction</span>'s created in the factory specified by the tag) that survived all of the <span style="color:#0000FF">DAnalysisAction</span> cuts.
 +
<syntaxhighlight>
 +
//In plugin evnt()
 +
const DEventWriterROOT* locEventWriterROOT = NULL;
 +
locEventLoop->GetSingle(locEventWriterROOT);
 +
locEventWriterROOT->Fill_DataTrees(locEventLoop, "b1pi_hists"); //string is the DReaction factory tag that the DReactions were created in
 +
</syntaxhighlight>
 +
 +
* The below allows you to choose which <span style="color:#0000FF">DParticleCombo</span>'s (<span style="color:#008000">locParticleCombos</span>) of which <span style="color:#0000FF">DReaction</span>'s (<span style="color:#008000">locReaction</span>) to save.
 +
** Beware: the <span style="color:#008000">locParticleCombos</span> MUST have originated from the <span style="color:#008000">locReaction</span> or else this will probably crash (can check <span style="color:#0000FF">DParticleCombo</span>::<span style="color:#008000">Get_Reaction</span>()).
 +
<syntaxhighlight>
 +
//In plugin evnt()
 +
#include "ANALYSIS/DEventWriterROOT.h"
 +
vector<const DEventWriterROOT*> locEventWriterROOTVector;
 +
locEventLoop->Get(locEventWriterROOTVector); //creates the TTrees for all DReactions upon first call
 +
locEventWriterROOTVector[0]->Fill_Tree(locEventLoop, locReaction, locParticleCombos);
 +
</syntaxhighlight>
 +
 +
* The below fills a <span style="color:#0000FF">TTree</span> that only contains the thrown particle data.
 +
<syntaxhighlight>
 +
//In plugin evnt()
 +
const DEventWriterROOT* locEventWriterROOT = NULL;
 +
locEventLoop->GetSingle(locEventWriterROOT);
 +
locEventWriterROOT->Fill_ThrownTree(locEventLoop);
 +
</syntaxhighlight>
 +
 +
=== Accessing TTree Data ===
 +
* <span style="color:#0000FF">TTree</span>:
 +
<syntaxhighlight>
 +
MyTree->Draw("PiMinus1__P4_Measured->Theta()"); //draws all particle combinations
 +
</syntaxhighlight>
 +
 +
* <span style="color:#0000FF">TBrowser</span> (draws all particle combinations):
 +
[[Image:Mattione_TTreeFormat_b1piTBrowserExample.png|thumb|left|900px|b1pi Events]]
 +
<br style="clear:both;"/>
 +
 +
=== TSelector / TPROOF Links===
 +
* [https://root.cern.ch/drupal/content/proof Documentation Link: PROOF]
 +
* [https://root.cern.ch/drupal/content/proof-multicore-desktop-laptop-proof-lite Documentation Link: PROOF-Lite]
 +
* [https://root.cern.ch/drupal/content/developing-tselector Documentation Link: TSelector]
 +
* [https://root.cern.ch/drupal/content/processing-proof Documentation Link: Full TSelector Example (with PROOF-Lite)]
 +
* [https://root.cern.ch/drupal/content/basic-processing Documentation Link: Process Examples]
 +
* [https://root.cern.ch/drupal/content/handling-large-outputs-root-files Documentation Link: Large Output Files]
 +
* [https://root.cern.ch/drupal/content/loading-macro-or-class Documentation Link: Loading a macro for PROOF]
 +
* [https://root.cern.ch/drupal/content/working-packages-par-files Documentation Link: Working with packages]
 +
 +
= Usage - Advanced =
 +
=== Custom Branches ===
 +
* You can create and fill custom branches by inheriting from the  <span style="color:#0000FF">DEventWriterROOT</span> class to create your own writer class.
 +
* Use the <span style="color:red">trunk/scripts/analysis/MakeEventWriterROOT.pl</span> script to generate the necessary code to do this.
 +
* Run this perl script with no arguments to get complete usage instructions.
 +
 +
=== Preventing Double-Counting ===
 +
* Since you can have multiple particle combinations per event, you have to be very careful to make sure you aren't double-counting when filling your histograms. 
 +
** For example, if you're histogramming the invariant mass of the &pi;<sup>0</sup>'s decay to &gamma;&gamma; in b1pi events using the measured photon data, multiple combinations may use the same showers for the photons, while having different tracks for the other particles.
 +
 +
= Converting for AmpTools =
 +
* To convert the <span style="color:#0000FF">TTree</span> for use as input to AmpTools, use the tree_to_amptools in the gluex_root_analysis repository. Run with no arguments for instructions.

Latest revision as of 10:41, 19 October 2017

TTree Format - Overview

  • Physics Analysis Root TTree (PART) format.

Data Hierarchy

  • One TTree per DReaction, each stored in the ROOT files specified by the user.
    • e.g., If 2 DReactions: missing & detected recoil proton: 2 different trees, could be in separate files or the same file.
  • One TTree entry per event.
  • All particle data stored in arrays/TClonesArray's: one array index per particle.
    • Thrown particles
    • Reconstructed neutral and charged hypotheses (by default: only used ones, but can save all: DReaction setting)
    • Beam photons that are later used in combos (unused beam particles are NOT saved)
    • Combo particle information
  • Event-independent information (e.g. the target, the DReaction decay chain, etc.) is stored in TTree::fUserInfo (a TList*)

DSelector

  • Enables C++ interface to TTree data, provides PROOF-Lite launcher, and much more.
  • Instructions for making and using a DSelector can be found at: Link

TTree Format: Simulated Data

Thrown Non-Particle Data

// EVENT DATA
"RunNumber": UInt_t
"EventNumber": ULong64_t
"MCWeight": Float_t
 
// # PARTICLES //array size of the thrown particle branches
"NumThrown": UInt_t
 
// THROWN REACTION INFO
"NumPIDThrown_FinalState": ULong64_t //the # of thrown final-state particles (+ pi0) of each type (multiplexed in base 10)
                                       //types (in order from 10^0 -> 10^15): g, e+, e-, nu, mu+, mu-, pi0, pi+, pi-, KLong, K+, K-, n, p, p-bar, n-bar
                                       //e.g. particles decaying from final-state particles are NOT included (e.g. photons from pi0, muons from pions, etc.)
                                     //is sum of #-of-PID * 10^ParticleMultiplexPower() (defined in libraries/include/particleType.h)
                                     //ParticleMultiplexPower() returns a different power of 10 for each final-state PID type. 
                                     //A value of 9 should be interpreted as >= 9.  
"PIDThrown_Decaying": ULong64_t //the types of the thrown decaying particles in the event (multiplexed in base 2)
                                //not the quantity of each, just whether or not they were present (1 or 0)
                                //binary power of a PID is given by ParticleMultiplexPower() (defined in libraries/include/particleType.h)
                                //types: most Particle_t's that aren't final state (e.g. lambda, eta, phi, rho0, etc.) see ParticleMultiplexPower()

Thrown Beam Particle

  • All branch names are prefixed with "ThrownBeam__"
//IDENTIFIER
"PID": Int_t //PDG ID value
 
//KINEMATICS: //At the production vertex 
"X4": TLorentzVector //This is the TAGGED energy //Use THIS for binning your results //Is ZERO if NOT TAGGED
"P4": TLorentzVector
"GeneratedEnergy": Float_t

Thrown Products

  • All branch names are prefixed with "Thrown__"
  • NOTE: The only contains particles corresponding to the "FinalState" and "Decaying" tags of DMCThrown.
    • In other words: No resonances, no decay products of final-state particles, and no orphan particles. 
//IDENTIFIERS / MATCHING
"ParentIndex": Int_t["NumThrown"] //the thrown particle array index of the particle this particle decayed from (-1 if none (e.g. photoproduced))
"PID": Int_t["NumThrown"] //PDG ID value
 
//MATCHING //only present if reconstructed data present (i.e. not if thrown-only tree)
"MatchID": Int_t["NumThrown"] //the "NeutralID"/"TrackID" of the reconstructed neutral/track that it is matched with (-1 for no match)
"MatchFOM": Float_t["NumThrown"] //Neutrals: confidence level //Tracks: #-matched-hits * hit_fraction //(-1 for no match)
 
//KINEMATICS: //Reported at the particle's production vertex 
"X4": TClonesArray(TLorentzVector["NumThrown"])
"P4": TClonesArray(TLorentzVector["NumThrown"])

TTree Format: Combo-Independent Data

Non-Particle Data

// EVENT DATA
"RunNumber": UInt_t
"EventNumber": ULong64_t
"L1TriggerBits": UInt_t
 
// PRODUCTION SPACETIME
"X4_Production": TLorentzVector //V3 from DVertex (kinfit), t from RF (propagated to V3)
 
// # PARTICLES //these are the array sizes for the particle branches
"NumBeam": UInt_t
"NumChargedHypos": UInt_t
"NumNeutralHypos": UInt_t
 
// TOPOLOGY //only present if simulated data
"IsThrownTopology": Bool_t //Does the DReaction decay chain match the thrown decay chain
 
// UNUSED TRACKS
"NumUnusedTracks": UChar_t
 
//NUM COMBOS
"NumCombos": UInt_t //size of all of the particle-combo-content arrays

Beam Particles (If Used in Combo)

  • Only the beam particles that are included in at least one combo are present.
  • All branch names are prefixed with "Beam__"
//ONLY PRESENT IF BEAM USED IN PARTICLE COMBOS
 
//IDENTIFIERS / MATCHING
"PID": Int_t["NumBeam"] //PDG ID value
"IsGenerator": Bool_t["NumBeam"] // kTRUE/kFALSE if matches the generator beam photon (-1 for no match) //only present if simulated data
 
//KINEMATICS: MEASURED //At the production vertex
"X4_Measured": TClonesArray(TLorentzVector["NumBeam"]) //position is at the production vertex (same as X4_Production(), except the time)
"P4_Measured": TClonesArray(TLorentzVector["NumBeam"])

Charged Track Hypotheses

  • Includes all hypotheses, whether they appear in the combos or not.
  • All branch names are prefixed with "ChargedHypo__"
//IDENTIFIERS / MATCHING
"TrackID": Int_t["NumChargedHypos"] //each physical particle has its own # (to keep track of different pid hypotheses for the same particle)
"PID": Int_t["NumChargedHypos"] //PDG ID value
"ThrownIndex": Int_t["NumChargedHypos"] //the array index of the thrown particle it is matched with (-1 for no match) //only present if simulated data
 
//KINEMATICS: MEASURED  //At the production vertex 
"P4_Measured": TClonesArray(TLorentzVector["NumChargedHypos"])
"X4_Measured": TClonesArray(TLorentzVector["NumChargedHypos"]) //t is the measured value in TOF/BCAL/FCAL projected back to Position_Measured
 
//TRACKING INFO:
"NDF_Tracking": UInt_t["NumChargedHypos"]
"ChiSq_Tracking": Float_t["NumChargedHypos"]
"NDF_DCdEdx": UInt_t["NumChargedHypos"]
"ChiSq_DCdEdx": Float_t["NumChargedHypos"]
"dEdx_CDC": Float_t["NumChargedHypos"]
"dEdx_FDC": Float_t["NumChargedHypos"]
 
//TIMING INFO
"HitTime": Float_t["NumChargedHypos"] //the system that is hit is in order of preference: BCAL/TOF/FCAL/ST 
                                      //to determine which, look whether energy was deposited in these systems
"RFDeltaTVar": Float_t["NumChargedHypos"] //Variance of X4_Measured.T() - RFTime, regardless of which RF bunch is chosen. 
                                          //Can be used to compute timing ChiSq //RF bunch is combo-dependent
 
//PID INFO
"Beta_Timing": Float_t["NumChargedHypos"] // = Path_Length/(c*Delta_t)
"ChiSq_Timing": Float_t["NumChargedHypos"]
"NDF_Timing": UInt_t["NumChargedHypos"]
 
//HIT ENERGY:
"dEdx_TOF": Float_t["NumChargedHypos"]
"dEdx_ST": Float_t["NumChargedHypos"]
"Energy_BCAL": Float_t["NumChargedHypos"]
"Energy_BCALPreshower": Float_t["NumChargedHypos"]
"Energy_FCAL": Float_t["NumChargedHypos"]
 
//SHOWER WIDTH:
"SigLong_BCAL" Float_t["NumChargedHypos"] // Longitudinal (outward radially from the target) shower width
"SigTheta_BCAL" Float_t["NumChargedHypos"] // Theta shower width
"SigTrans_BCAL" Float_t["NumChargedHypos"] // Transverse (azimuthal) shower width 
 
//SHOWER MATCHING:
"TrackBCAL_DeltaPhi": Float_t["NumChargedHypos"] //999.0 if not matched //units are radians
"TrackBCAL_DeltaZ": Float_t["NumChargedHypos"] //999.0 if not matched //Track position - BCAL Shower
"TrackFCAL_DOCA": Float_t["NumChargedHypos"] //999.0 if not matched

Neutral Particle Hypotheses

  • All branch names are prefixed with "NeutralHypo__"
  • Includes all hypotheses, whether they appear in the combos or not.
  • Discussion on P4 & X4:
    • Note that P4 is not present because it is defined by X4, and X4 is not present because it is defined by the tracks, which are combo-dependent
    • For combo particles, P4 & X4 are listed for each combo
    • If not used in a combo, can be computed using the shower hit information and the vertex & RF-time of your choosing (e.g. combo production-vertex, RF-time)
  • To determine whether is BCAL or FCAL, see which system has non-zero energy
//IDENTIFIERS / MATCHING
"NeutralID": Int_t["NumNeutralHypos"] //each physical particle has its own # (to keep track of different pid hypotheses for the same particle)
"PID": Int_t["NumNeutralHypos"] //PDG ID value
"ThrownIndex": Int_t["NumNeutralHypos"] //the array index of the thrown particle it is matched with (-1 for no match) //only present if simulated data
 
//KINEMATICS: MEASURED  //At the production vertex 
"P4_Measured": TClonesArray(TLorentzVector["NumNeutralHypos"])
"X4_Measured": TClonesArray(TLorentzVector["NumNeutralHypos"]) //t is the measured value in TOF/BCAL/FCAL projected back to Position_Measured
 
//MEASURED PID INFO
"Beta_Timing": Float_t["NumNeutralHypos"] // = Path_Length/(c*Delta_t)
"ChiSq_Timing": Float_t["NumNeutralHypos"] //-1 if not photon
"NDF_Timing": UInt_t["NumNeutralHypos"] //0 if not photon
 
//SHOWER INFO
"X4_Shower": Float_t["NumNeutralHypos"] //location/time of the reconstructed shower
"Energy_BCAL": Float_t["NumNeutralHypos"] //is 0.0 if shower in FCAL
"Energy_BCALPreshower": Float_t["NumNeutralHypos"] //is 0.0 if shower in FCAL
"Energy_FCAL": Float_t["NumNeutralHypos"] //is 0.0 if shower in BCAL
 
//SHOWER WIDTH:
"SigLong_BCAL" Float_t["NumNeutralHypos"] // Longitudinal (outward radially from the target) shower width
"SigTheta_BCAL" Float_t["NumNeutralHypos"] // Theta shower width
"SigTrans_BCAL" Float_t["NumNeutralHypos"] // Transverse (azimuthal) shower width 
 
//NEARBY TRACKS
"TrackBCAL_DeltaPhi": Float_t["NumNeutralHypos"] //is delta to nearest track, is 999.0 if no tracks on BCAL
"TrackBCAL_DeltaZ": Float_t["NumNeutralHypos"] //is delta to nearest track, is 999.0 if no tracks on BCAL
"TrackFCAL_DOCA": Float_t["NumNeutralHypos"] //is DOCA to nearest track, is 999.0 if no tracks on FCAL
 
//PHOTON PID INFO
   //Computed using DVertex (best estimate of reaction vertex using all "good" tracks)
   //Can be used to compute timing chisq //is invalid (0) for non-photons
"PhotonRFDeltaTVar": Float_t["NumNeutralHypos"] //Variance of DVertexX4.T() - RFTime, regardless of which RF bunch is chosen. //RF bunch is combo-dependent

TTree Format: Combo-Dependent Data

  • All particle combo data is stored in arrays: array entries correspond to different particle combos

Particle-Independent Data

//CUT FLAG
"IsComboCut": Bool_t["NumCombos"] //if true, combo has been previously cut (all kFALSE originally, user can apply cuts in TSelector, change this flag, and output new TTree)
 
//COMBO THROWN MATCHING //not present if not simulated data
"IsTrueCombo": Bool_t["NumCombos"] //"IsThrownTopology" = kTRUE, each particle has the right PID, and the combo particle chain matches the thrown decay chain
"IsBDTSignalCombo": Bool_t["NumCombos"] //Similar to "IsTrueCombo", except other thrown topologies that decay to the DReaction topology are marked as signal
                                        //Note that if you have an &omega; or &phi; in your DReaction, you still have to filter your combos prior to BDT 
                                        //input to remove duplicate entries. This is because the omega & phi masses are not constrained in the kinematic fit, 
                                        //nor should they be in the BDT, so you have duplicate entries from the point-of-view of the BDT due to combinatorics 
                                        //(e.g. which pions decayed from the omega, and which ones didn't, are irrelevant to the BDT). 
 
//RF
"RFTime_Measured": Float_t["NumCombos"] //reported at center of target
"RFTime_KinFit": Float_t["NumCombos"] //reported at center of target //only if spacetime kinematic fit performed
 
//KINEMATIC FIT
"ChiSq_KinFit": Float_t["NumCombos"] //only if kinematic fit performed
"NDF_KinFit": UInt_t["NumCombos"] //only if kinematic fit performed // = 0 if kinematic fit doesn't converge
 
//UNUSED ENERGY
"Energy_UnusedShowers": Float_t["NumCombos"] // summed energy of neutral showers in the event not included in the combo (requiring unused showers are in time and have a polar angle > 2 degrees to reduce contamination from EM background)
 
//UNUSED TRACKS //For tracks unused by combo, the hypo chosen is the one with the best tracking FOM
"SumPMag_UnusedTracks": Float_t["NumCombos"]
"SumP3_UnusedTracks": TClonesArray(TVector3["NumCombos"])

Particle Branch-Name Prefixes

Example Reaction (b1pi):

  • γ p →ω, π+, π-, (p)
    • ω → π+, π-, π0
      • π0 → γ γ

Branch Names:

  • Beam: "ComboBeam"
  • Detected: "PiMinus1", "PiPlus1", "PiPlus2", "PiMinus2", "Photon1", "Photon2"
  • Decaying: "DecayingPi0"
  • Missing: "MissingProton"

Combo Beam Particles (If Any)

  • All branch names are prefixed with "ComboBeam__"
    • E.g. "ComboBeam__BeamIndex"
//IDENTIFIER
"BeamIndex": Int_t["NumCombos"] //array index to the "Beam__" branches that correspond to this particle
 
//KINEMATICS: KINFIT //At the interaction vertex //only present if kinfit performed
"X4_KinFit": TClonesArray(TLorentzVector["NumCombos"]) //not present if p4-only fit
"P4_KinFit": TClonesArray(TLorentzVector["NumCombos"]) //not present if vertex-only or spacetime-only fit, unless beam is charged

Combo Tracks (If Any)

  • All branch names are prefixed with the particle name
    • E.g. "Proton__ChargedIndex", "PiMinus1__P4_KinFit"
//IDENTIFIER
"ChargedIndex": Int_t["NumCombos"] //array index to the "ChargedHypo__" branches that correspond to this particle
 
//PID INFO: MEASURED //using combo RF bunch
"Beta_Timing_Measured": Float_t["NumCombos"] // = Path_Length/(c*Delta_t)
"ChiSq_Timing_Measured": Float_t["NumCombos"]
 
//PID INFO: KINFIT //using combo RF bunch //not present if time constrained //uses combo vertex & p4 if kinfit
"Beta_Timing_KinFit": Float_t["NumCombos"] // = Path_Length/(c*Delta_t)
"ChiSq_Timing_KinFit": Float_t["NumCombos"]
 
//KINEMATIC FIT KINEMATICS //only present if kinfit performed
"X4_KinFit": TClonesArray(TLorentzVector["NumCombos"]) //not present if p4-only fit
"P4_KinFit": TClonesArray(TLorentzVector["NumCombos"])

Combo Neutrals (If Any)

  • All branch names are prefixed with the particle name
    • E.g. "Photon1__NeutralIndex", "Neutron__P4_KinFit"
//IDENTIFIER
"NeutralIndex": Int_t["NumCombos"] //array index to the "NeutralHypo__" branches that correspond to this particle
                                   //Note that they may not have the same PID (and thus P4) as this!!
                                      //If this is a PID not created by default (e.g. K0Long)
 
//KINEMATICS: MEASURED  //At the production vertex 
"P4_Measured": TClonesArray(TLorentzVector["NumCombos"])
"X4_Measured": TClonesArray(TLorentzVector["NumCombos"]) //t is the measured value in TOF/BCAL/FCAL projected back to Position_Measured
 
//MEASURED PID INFO
"Beta_Timing_Measured": Float_t["NumCombos"] // = Path_Length/(c*Delta_t)
"ChiSq_Timing_Measured": Float_t["NumCombos"] //only present if photon
 
//KINEMATIC FIT PID INFO
"Beta_Timing_KinFit": Float_t["NumCombos"] // = Path_Length/(c*Delta_t) //not present if p4-only fit
"ChiSq_Timing_KinFit": Float_t["NumCombos"] //only present if photon //not present if p4-only fit
 
//KINEMATIC FIT KINEMATICS //only present if kinfit performed
"X4_KinFit": TClonesArray(TLorentzVector["NumCombos"]) //not present if p4-only fit
"P4_KinFit": TClonesArray(TLorentzVector["NumCombos"])

Combo Decaying Particles (If Any, If Detached/KinFit)

  • All branch names are prefixed with "Decaying" and the particle name
    • E.g.: "DecayingPi0__X4"
//KINEMATICS: //At the decay vertex 
"X4": TLorentzVector["NumCombos"] //only present if has a detached vertex //kinematic fit result if kinfit performed, else reconstructed from detected particles
"PathLengthSigma": Float_t["NumCombos"] //only present if has a detached vertex and both vertices are fit
"P4_KinFit": TLorentzVector["NumCombos"] //only present if kinfit performed

Combo Missing Particles (If Any & If KinFit)

  • All branch names are prefixed with "Missing" and the particle name
    • E.g.: "MissingProton__P4_KinFit"
//KINFIT KINEMATICS: //At its production vertex //only present if kinfit performed
"P4_KinFit": TLorentzVector["NumCombos"]

TTree Format: DReaction Info

  • Stored in TTree::fUserInfo (a TList*)
  • "ParticleNameList": TList of the names of the reaction particles in the tree, in the order they were specified in the DReaction.
  • "MiscInfoMap": TMap of TObjString -> TObjString
    • "KinFitType" -> DKinFitType (converted to TObjString)
    • "Target__PID" -> int (converted to TObjString): PDG PID of target particle //if a target particle was specified
    • "Target__Mass" -> double (converted to TObjString): Mass of the target particle. //if a target particle was specified
    • "Missing__PID" -> int (converted to TObjString): PDG PID of missing particle //if a missing particle was specified
    • "Target__CenterX" -> double (converted to TObjString): x-coordinate of target center
    • "Target__CenterY" -> double (converted to TObjString): y-coordinate of target center
    • "Target__CenterZ" -> double (converted to TObjString): z-coordinate of target center
    • "MissingNAME__Mass" -> double (converted to TObjString): Mass of the 'NAME' missing particle (e.g. 'NAME' = Proton). //if a missing particle was specified
    • "DecayingNAME__Mass" -> double (converted to TObjString): Mass of the 'NAME' decaying particle (e.g. 'NAME' = Pi0). //if decaying particles were present
  • "NameToPIDMap": TMap of "UniqueParticleName" (TObjString) -> int (PDG) (converted to TObjString)
  • "NameToPositionMap": TMap of "UniqueParticleName" (TObjString) -> "StepIndex_ParticleIndex" (stored in TObjString) (ParticleIndex = -1 for initial, -2 for target, 0+ for final state)
  • "PositionToNameMap": TMap of "StepIndex_ParticleIndex" (stored in TObjString) (ParticleIndex = -1 for initial, -2 for target, 0+ for final state) -> "UniqueParticleName" (TObjString)
  • "PositionToPIDMap": TMap of "StepIndex_ParticleIndex" (stored in TObjString) (ParticleIndex = -1 for initial, -2 for target, 0+ for final state) -> int (PDG) (converted to TObjString)
  • "DecayProductMap": TMap of "DecayingParticleName" (TObjString) -> "DecayProductNames" (stored in a TList of TObjString objects). Excludes resonances and intermediate decays (e.g. if Ξ-→π-Λ→π-π-p: will be Ξ-→π-π-p and Λ decay not listed)

Usage

Create TTrees

  • To save data to a TTree for a given DReaction, TTree output must be first be enabled for that reaction. See DReaction Control Variables for details.
    • Note: Only one thrown tree will be created during program execution. If the DEventWriterROOT::Create_ThrownTree() function is called more than once, nothing happens on subsequent calls. 
#include "ANALYSIS/DEventWriterROOT.h"
//In plugin brun():
const DEventWriterROOT* locEventWriterROOT = NULL;
locEventLoop->GetSingle(locEventWriterROOT);
locEventWriterROOT->Create_DataTrees(locEventLoop); //creates TTrees for all output-enabled DReactions
locEventWriterROOT->Create_ThrownTree("tree_b1pi_thrownmc.root"); //optional: create a ttree containing only the thrown data //string is output file name

Save Data to TTree

  • The below only saves the particle combinations (for TTree-output-enabled DReaction's created in the factory specified by the tag) that survived all of the DAnalysisAction cuts. 
//In plugin evnt()
const DEventWriterROOT* locEventWriterROOT = NULL;
locEventLoop->GetSingle(locEventWriterROOT);
locEventWriterROOT->Fill_DataTrees(locEventLoop, "b1pi_hists"); //string is the DReaction factory tag that the DReactions were created in
  • The below allows you to choose which DParticleCombo's (locParticleCombos) of which DReaction's (locReaction) to save.
    • Beware: the locParticleCombos MUST have originated from the locReaction or else this will probably crash (can check DParticleCombo::Get_Reaction()). 
//In plugin evnt()
#include "ANALYSIS/DEventWriterROOT.h"
vector<const DEventWriterROOT*> locEventWriterROOTVector;
locEventLoop->Get(locEventWriterROOTVector); //creates the TTrees for all DReactions upon first call
locEventWriterROOTVector[0]->Fill_Tree(locEventLoop, locReaction, locParticleCombos);
  • The below fills a TTree that only contains the thrown particle data. 
//In plugin evnt()
const DEventWriterROOT* locEventWriterROOT = NULL;
locEventLoop->GetSingle(locEventWriterROOT);
locEventWriterROOT->Fill_ThrownTree(locEventLoop);

Accessing TTree Data

  • TTree:
MyTree->Draw("PiMinus1__P4_Measured->Theta()"); //draws all particle combinations
  • TBrowser (draws all particle combinations):
b1pi Events


TSelector / TPROOF Links

Usage - Advanced

Custom Branches

  • You can create and fill custom branches by inheriting from the DEventWriterROOT class to create your own writer class.
  • Use the trunk/scripts/analysis/MakeEventWriterROOT.pl script to generate the necessary code to do this.
  • Run this perl script with no arguments to get complete usage instructions.

Preventing Double-Counting

  • Since you can have multiple particle combinations per event, you have to be very careful to make sure you aren't double-counting when filling your histograms.
    • For example, if you're histogramming the invariant mass of the π0's decay to γγ in b1pi events using the measured photon data, multiple combinations may use the same showers for the photons, while having different tracks for the other particles.

Converting for AmpTools

  • To convert the TTree for use as input to AmpTools, use the tree_to_amptools in the gluex_root_analysis repository. Run with no arguments for instructions.
Retrieved from "https://halldweb1.jlab.org/wiki/index.php?title=Analysis_TTreeFormat&oldid=84075"