Difference between revisions of "Mattione GlueX Analysis Factories"

From GlueXWiki
Jump to: navigation, search
(DAnalysisAction Objects)
 
(45 intermediate revisions by the same user not shown)
Line 1: Line 1:
== NOTE: ==
+
== Reaction Analysis Factories ==
 +
* NOTE: Most of these are located in sim-recon/src/libraries/ANALYSIS/
  
* This is now superceded by (under construction): [[GlueX_Analysis_Software | GlueX Analysis Software]]
+
=== Pre-Selection ===
 +
* '''DNeutralShower_factory_PreSelect''': Pre-selects which <span style="color:#0000FF">DNeutralShower</span> objects should be included in analyses.
 +
* '''DChargedTrack_factory_PreSelect''': Pre-selects which <span style="color:#0000FF">DChargedTrack</span> objects should be included in analyses.
  
 +
=== User Input ===
 +
* '''DReaction_factory''': Creates <span style="color:#0000FF">DReaction</span> objects to be analyzed.  Needs to be created in each analysis plugin. 
  
== Analysis Procedure Details ==
+
=== Combo Construction Factories ===
 +
* '''DTrackTimeBased_factory_Combo''': If a charged PID is needed for an analysis for which a corresponding <span style="color:#0000FF">DTrackTimeBased</span> is not present in the data, a new one is created.  E.g. if mu+/- are requested.  This uses the reconstructed momentum from the <span style="color:#0000FF">DTrackTimeBased</span> object with the closest mass.
 +
* '''DDetectorMatches_factory_Combo''': Stores the matching between each new <span style="color:#0000FF">DTrackTimeBased</span> object (from the <span style="color:Red">"Combo"</span> factory) and the existing shower/hit objects. No new matching is done, it just uses the matching results from the source object. Also stores the matching results from the default factory.
 +
* '''DAnalysisResults_factory''': Creates the combos via the DSourceComboer class (detailed below). Loops over the <span style="color:#0000FF">DAnalysisAction</span> objects stored in each <span style="color:#0000FF">DReaction</span>, and executing them on the corresponding <span style="color:#0000FF">DParticleCombo</span>.  This creates and fills histograms of the number of events and <span style="color:#0000FF">DParticleCombo</span> objects that survive each cut.
  
=== Analysis Overview ===
+
=== Combo Construction Classes (not factories) ===
* Generate every possible combination of particles (<span style="color:#0000FF">DParticleCombo</span>) that can represent the desired <span style="color:#0000FF">DReaction</span> objects.
+
* '''DSourceComboer''': Finds all combos of charged tracks / neutral showers necessary to make the desired combos. Calls methods in the other DSourceCombo* classes below as needed.  Also is responsible for dE/dx and E/p PID cuts.  
** This can yield many <span style="color:#0000FF">DParticleCombo</span> objects per event.  
+
* '''DSourceComboTimeHandler''': Responsible for PID timing cuts, binning photons by vertex-z, and RF bunch selection.
** This is regardless of PID, # of remaining tracks, timing, track position or momentum, etc.
+
* '''DSourceComboVertexHandler''': Responsible for finding pre-kinfit vertex positions for the combos. If is photoproduction step, the POCA to the beamline of the tracks with &theta; closest to 90 degrees. Otherwise, is the POCA between the two closest tracks.  
*** Only extremely loose cuts are placed by default on PID, track-vertex-z, and beam photon time prior to creating <span style="color:#0000FF">DParticleCombo</span> objects: this is to avoid memory spikes from events with too many particles.  
+
* '''DSourceComboP4Handler''': Responsible for placing invariant mass and missing mass squared cuts on the combosAlso for reconstructing the P4 of decaying particles as needed.
**** These can be changed by modifying the command line parameters defined in <span style="color:#0000FF">DParticleComboBlueprint_factory</span>::<span style="color:#008000">brun</span>() and <span style="color:#0000FF">DParticleCombo_factory_PreKinFit</span>::<span style="color:#008000">brun</span>().  
+
* '''DParticleComboCreator''': Takes the results from the DSourceComboer and creates DParticleCombo objects from them, along with new DChargedTrackHypothesis and DNeutralParticleHypothesis objects for the tracks (using the combo-specific vertex position for PID, etc.).  
* User-specified cuts are then used to eliminate <span style="color:#0000FF">DParticleCombo</span> objects that do not much the desired <span style="color:#0000FF">DReaction</span> objects (e.g. PID, kinematic fit, invariant mass, etc.)
+
** This is done by executing <span style="color:#0000FF">DAnalysisActions</span> (e.g. histogramming, cutting) in sequence on each <span style="color:#0000FF">DParticleCombo</span> until it fails a cut.   
+
** The kinematic fit (if specified) is not performed until the kinematic fit results are required for a <span style="color:#0000FF">DAnalysisAction</span> (<span style="color:#0000FF">DAnalysisAction</span>::<span style="color:#008000">Get_UseKinFitResultsFlag()</span> == true).  This saves time and memory by letting users cut <span style="color:#0000FF">DParticleCombo</span> objects prior to fitting.
+
* Save the results to disk further analysis (currently not built-in (except for histograms)).
+
  
 +
== Thrown Factories ==
 +
* '''DReaction_factory_Thrown''': Creates a <span style="color:#0000FF">DReaction</span> object representing the thrown reaction.  Final state particles listed in <span style="color:#0000FF">DMCThrown</span> are ignored if they have decayed from pions, kaons, or other "typical" final state particles (e.g. muons, electrons, pions, and neutrinos are ignored if they decay from a kaon, etc.).  Also, particles not defined in sim-recon/src/libraries/include/particleType.h are ignored.
 +
* '''DParticleCombo_factory_Thrown''': Creates a <span style="color:#0000FF">DParticleCombo</span> object representing the thrown reaction.  The <span style="color:#0000FF">DMCThrown</span> objects are used for the particle data, except pure <span style="color:#0000FF">DKinematicData</span> objects are used for the beam particle and target objects (from <span style="color:#0000FF">DMCReaction</span>). Final state particles listed in <span style="color:#0000FF">DMCThrown</span> are ignored if they have decayed from pions, kaons, or other "typical" final state particles (e.g. muons, electrons, pions, and neutrinos are ignored if they decay from a kaon, etc.).  Also, particles not defined in sim-recon/src/libraries/include/particleType.h are ignored.
 +
* '''DEventRFBunch_factory_Thrown''': Creates a <span style="color:#0000FF">DEventRFBunch</span> object for the simulated event.
  
=== Reaction Analysis ===
+
== Analysis Utilities ==
* NOTE: These are located in sim-recon/src/libraries/ANALYSIS/
+
* '''DReaction_factory''': Creates <span style="color:#0000FF">DReaction</span> objects to be analyzed.  Needs to be created in each analysis plugin. 
+
* '''DParticleComboBlueprint_factory''': Creates a <span style="color:#0000FF">DParticleComboBlueprint</span> object for each possible track combination, excluding any possible multiplicity from multiple beam photons.  These <span style="color:#0000FF">DParticleComboBlueprint</span> objects store pointers to which <span style="color:#0000FF">DChargedTrack</span> and <span style="color:#0000FF">DNeutralShower</span> objects will be used for each particle in the reaction.  The beam photon multiplicity is handled in <span style="color:#0000FF">DParticleCombo_factory_PreKinFit</span>.
+
* '''DTrackTimeBased_factory_Reaction''': If none of the existing <span style="color:#0000FF">DTrackTimeBased</span> objects for a given reconstructed track have the needed PID for a particle in a <span style="color:#0000FF">DReaction</span>, this creates new <span style="color:#0000FF">DTrackTimeBased</span> objects for them (e.g. e<sup>-</sup>, or if one of the default PIDs (e.g. &pi;<sup>+</sup>) fails reconstruction while the others don't (e.g. K<sup>+</sup>)). This uses the reconstructed momentum from the <span style="color:#0000FF">DTrackTimeBased</span> object with the closest mass, and re-swims the track.
+
* '''DChargedTrackHypothesis_factory_Reaction''': Creates <span style="color:#0000FF">DChargedTrackHypothesis</span> objects for the <span style="color:#0000FF">DTrackTimeBased</span> objects created by <span style="color:#0000FF">DTrackTimeBased_factory_Reaction</span>.
+
* '''DParticleCombo_factory_PreKinFit''': Creates a <span style="color:#0000FF">DParticleCombo</span> object for each <span style="color:#0000FF">DParticleComboBlueprint</span>, setting the data with the measured <span style="color:#0000FF">DChargedTrackHypothesis</span>, <span style="color:#0000FF">DNeutralParticleHypothesis</span>, and <span style="color:#0000FF">DBeamPhoton</span> objects.  A loose timing cut is placed between the <span style="color:#0000FF">DEventRFBunch</span> time and the <span style="color:#0000FF">DBeamPhoton</span> objects, and additional <span style="color:#0000FF">DParticleCombo</span> objects are created if more than one <span style="color:#0000FF">DBeamPhoton</span> object survives the cut.
+
* '''DAnalysisResults_PreKinFit''': Loops over the <span style="color:#0000FF">DAnalysisAction</span> objects stored in each <span style="color:#0000FF">DReaction</span>, executing them on the corresponding <span style="color:#0000FF">DParticleCombo</span> objects until the kinematic fit results are needed for an action (<span style="color:#0000FF">DAnalysisAction</span>::<span style="color:#008000">Get_UseKinFitResultsFlag</span>() == true). This allows <span style="color:#0000FF">DAnalysisAction</span> objects to reject background combinations prior to kinematic fitting to save time and memory.  This creates and fills histograms of the number of events and <span style="color:#0000FF">DParticleCombo</span> objects that survive each cut.  This also creates and fills several reaction-independent histograms, such as thrown and reconstructed particle kinematics, and track multiplicity.
+
* '''DKinFitResults_factory''': For each <span style="color:#0000FF">DParticleCombo</span> that survived all of the cuts executed in <span style="color:#0000FF">DAnalysisResults_PreKinFit</span>, perform the kinematic fit specified by the <span style="color:#0000FF">DReaction</span> objects (if desired).  See the "DKinFitResults_factory" section of [[Mattione_GlueX_Kinematic_Fitting | GlueX Kinematic Fitting]] for more details. 
+
* '''DChargedTrackHypothesis_factory_KinFit''': Create <span style="color:#0000FF">DChargedTrackHypothesis</span> objects containing the kinematically fit track parameters.  New, unique objects are created for each charged particle in each kinematically fit <span style="color:#0000FF">DParticleCombo</span>.
+
* '''DNeutralParticleHypothesis_factory_KinFit''': Create <span style="color:#0000FF">DNeutralParticleHypothesis</span> objects containing the kinematically fit track parameters.  New, unique objects are created for each neutral particle in each kinematically fit <span style="color:#0000FF">DParticleCombo</span>.
+
* '''DBeamPhoton_factory_KinFit''': Create <span style="color:#0000FF">DBeamPhoton</span> objects containing the kinematically fit track parameters.  New, unique objects are created for each beam photon in each kinematically fit <span style="color:#0000FF">DParticleCombo</span>.
+
* '''DParticleCombo_factory''': Creates a new <span style="color:#0000FF">DParticleCombo</span> object in each <span style="color:#0000FF">DParticleCombo</span> that survived all of the cuts executed in <span style="color:#0000FF">DAnalysisResults_PreKinFit</span>, but containing the kinematically fit track parameters (in addition to the original, measured parameters).
+
* '''DAnalysisResults_factory''': Loops over the <span style="color:#0000FF">DAnalysisAction</span> objects stored in each <span style="color:#0000FF">DReaction</span>, skipping those that were executed by <span style="color:#0000FF">DAnalysisResults_PreKinFit</span>, and executing the remaining ones on the corresponding <span style="color:#0000FF">DParticleCombo</span> objects created by <span style="color:#0000FF">DParticleCombo_factory</span>.  This creates and fills histograms of the number of events and <span style="color:#0000FF">DParticleCombo</span> objects that survive each cut.
+
  
=== Analysis Utilities ===
+
* '''DParticleID''': (Located in the PID library) Collection of functions used to match charged tracks to hits in the BCAL, FCAL, SC, and TOF, and to calculate the PID FOM from the TOF and DC dE/dx information.
 
+
* '''DMCThrownMatching''': Matches reconstructed particles to generated particles. Only the best match for each particle is saved.  
* '''DParticleID''': Collection of functions used to match charged tracks to hits in the BCAL, FCAL, SC, and TOF, and to calculate the PID FOM from the TOF and DC dE/dx information.
+
** For neutrals, compares the thrown and reconstructed shower momenta and uses the shower covariance matrix to calculate a match FOM. This FOM is NOT cut, so extremely poor matches are included in the results.
* '''DMCThrownMatching''': Matches reconstructed particles to generated particles.  
+
** For tracks, compares the hits on the track to the thrown hits. First, the % of the track hits on each thrown track is computed (in the <span style="color:#0000FF">DTrackTimeBased</span> factory), and the highest total is set in <span style="color:#0000FF">DTrackTimeBased</span> (as well as the corresponding <span style="color:#0000FF">DMCThrown</span>::<span style="color:#008000">myid</span>). In the <span style="color:#0000FF">DMCThrownMatching</span> factory, for each <span style="color:#0000FF">DTrackTimeBased</span>, the number of matched hits is weighted (multiplied) by the track hit-fraction (#-hits-on-track-matched-to-MC / #-hits-on-track). Matches are then recorded in order from highest weighted-#-hits to least, such that each <span style="color:#0000FF">DMCThrown</span> is only matched once (other matches are ignored).  Hit fractions less than <span style="color:#0000FF">DMCThrownMatching</span>::<span style="color:#008000">dMinTrackMatchHitFraction</span> (default <span style="color:Red">0.5</span>, set-able on command-line via <span style="color:Red">-PMCMATCH:MIN_TRACK_MATCH</span>) are ignored.  
* '''DAnalysisUtilities''': Collection of utility functions used to facilitate physics analyses. These include methods for calculating invariant mass, missing mass, DOCA, etc., as well as methods for determining whether a <span style="color:#0000FF">DParticleCombo</span> is in some ways similar to other <span style="color:#0000FF">DParticleCombo</span> objects (e.g. the same track hypotheses make up a given decay chain) (useful for preventing double-counting when histogramming (e.g. invariant mass)).  
+
** Also matches thrown and reconstructed BCAL, FCAL, and TOF hits, although currently only the TOF hits have been vetted.
 +
* '''DAnalysisUtilities''': Collection of utility functions used to facilitate physics analyses. These include methods for calculating invariant mass, missing mass, DOCA, etc.
 
* '''DKinFitter_GlueX''': See [[Mattione_GlueX_Kinematic_Fitting | GlueX Kinematic Fitting]]
 
* '''DKinFitter_GlueX''': See [[Mattione_GlueX_Kinematic_Fitting | GlueX Kinematic Fitting]]
 
=== Factories Tree ===
 
* This tree was generated using the b1pi_hists plugin on December 8, 2012. 
 
[[Image:Mattione_AnalysisFactories_b1piFactoryTree.png|left|600px]]
 
<br style="clear:both;"/>
 
 
== DParticleCombo ==
 
* Located in src/libraries/ANALYSIS/
 
 
=== Particles ===
 
* Particle data is contained in either <span style="color:#0000FF">DChargedTrackHypothesis</span>, <span style="color:#0000FF">DNeutralParticleHypothesis</span>, <span style="color:#0000FF">DBeamPhoton</span>, or <span style="color:#0000FF">DKinematicData</span> (for reconstructed missing or decaying particles) objects.
 
** However, all of these objects are stored in <span style="color:#0000FF">DParticleComboStep</span> as pointers to <span style="color:#0000FF">DKinematicData</span>.  If you want the <span style="color:#0000FF">DBeamPhoton</span>, etc. objects, you need to cast them back that type. 
 
* The order of the particles and steps are the same as specified by the <span style="color:#0000FF">DReaction</span> and <span style="color:#0000FF">DReactionStep</span> objects.
 
* Both the measured data and the kinematic fit data are accessible from these classes.
 
** In <span style="color:#0000FF">DParticleCombo</span> objects grabbed from the "PreKinFit" tag factory, the measured data is stored in the both the "default" and the "measured" members (e.g. dFinalParticles and dFinalParticles_Measured).
 
** In <span style="color:#0000FF">DParticleCombo</span> objects grabbed from the default (no tag) factory, the kinematic data is stored in the "default" members (e.g. dFinalParticles) and the measured data is stored in the "measured" members (e.g. dFinalParticles_Measured).
 
* The source objects (<span style="color:#0000FF">DChargedTrack</span> and <span style="color:#0000FF">DNeutralShower</span>) and PIDs are accessible through the <span style="color:#0000FF">DParticleComboBlueprintStep</span>.
 
* Particles that are missing or are decaying may have NULL pointers stored for the objects.
 
** The source and measured pointers will be NULL, and the "default" pointers will be NULL unless they are constrained by the kinematic fit (e.g. resonances are not constrained, but a &Lambda; or a missing recoil proton will be).
 
 
=== Source Code ===
 
* C++ code of class members (methods aren't shown):
 
<syntaxhighlight>
 
class DParticleComboStep
 
{
 
  private:
 
    // BLUEPRINT:
 
    const DParticleComboBlueprintStep* dParticleComboBlueprintStep; //contains PIDs, source objects
 
 
    // INITIAL PARTICLES:
 
    const DKinematicData* dInitialParticle; //if is null: decaying or beam particle not yet set!
 
    const DKinematicData* dInitialParticle_Measured; //if is null: decaying or beam particle not yet set!
 
    const DKinematicData* dTargetParticle; //NULL for no target
 
 
    // FINAL PARTICLES:
 
    deque<const DKinematicData*> dFinalParticles; //if particle is null: missing or decaying! //these are DChargedTrackHypothesis or DNeutralParticleHypothesis objects if detected
 
    deque<const DKinematicData*> dFinalParticles_Measured; //if particle is null: missing or decaying! //these are DChargedTrackHypothesis or DNeutralParticleHypothesis objects if detected
 
};
 
</syntaxhighlight>
 
 
<syntaxhighlight>
 
class DParticleCombo : public JObject
 
{
 
  private:
 
    const DReaction* dReaction;
 
    const DKinFitResults* dKinFitResults;
 
    deque<const DParticleComboStep*> dParticleComboSteps;
 
};
 
</syntaxhighlight>
 
 
== User Plugin DReaction_factory ==
 
* This is from sim-recon/src/programs/Analysis/plugins/b1pi_hists/
 
<syntaxhighlight>
 
//------------------
 
// init
 
//------------------
 
jerror_t DReaction_factory::init(void)
 
{
 
  // Setting the PERSISTANT prevents JANA from deleting
 
  // the objects every event so we only create them once.
 
  SetFactoryFlag(PERSISTANT);
 
 
  DReaction* locReaction;
 
  DReactionStep* locReactionStep;
 
 
  // Make as many DReaction objects as desired
 
 
  deque<DReactionStep*> locReactionSteps;
 
 
/**************************************************** b1pi Steps ****************************************************/
 
 
  //g, p -> X(2000), (p)
 
  locReactionStep = new DReactionStep();
 
  locReactionStep->Set_InitialParticleID(Gamma);
 
  locReactionStep->Set_TargetParticleID(Proton);
 
  locReactionStep->Add_FinalParticleID(Unknown); //x(2000)
 
  locReactionStep->Add_FinalParticleID(Proton);
 
  locReactionStep->Set_MissingParticleIndex(1); //proton missing
 
  locReactionSteps.push_back(locReactionStep);
 
  dReactionStepPool.push_back(locReactionStep); //prevent memory leak
 
 
  //x(2000) -> b1(1235)+, pi-
 
  locReactionStep = new DReactionStep();
 
  locReactionStep->Set_InitialParticleID(Unknown); //x(2000)
 
  locReactionStep->Set_TargetParticleID(Unknown); //no target for this step
 
  locReactionStep->Add_FinalParticleID(b1_1235_Plus);
 
  locReactionStep->Add_FinalParticleID(PiMinus);
 
  locReactionStep->Set_MissingParticleIndex(-1); //none missing
 
  locReactionSteps.push_back(locReactionStep);
 
  dReactionStepPool.push_back(locReactionStep); //prevent memory leak
 
 
  //b1(1235)+ -> omega, pi-
 
  locReactionStep = new DReactionStep();
 
  locReactionStep->Set_InitialParticleID(b1_1235_Plus);
 
  locReactionStep->Set_TargetParticleID(Unknown); //no target for this step
 
  locReactionStep->Add_FinalParticleID(omega);
 
  locReactionStep->Add_FinalParticleID(PiPlus);
 
  locReactionStep->Set_MissingParticleIndex(-1); //none missing
 
  locReactionSteps.push_back(locReactionStep);
 
  dReactionStepPool.push_back(locReactionStep); //prevent memory leak
 
 
  //omega -> pi+, pi-, pi0
 
  locReactionStep = new DReactionStep();
 
  locReactionStep->Set_InitialParticleID(omega);
 
  locReactionStep->Set_TargetParticleID(Unknown); //no target for this step
 
  locReactionStep->Add_FinalParticleID(PiPlus);
 
  locReactionStep->Add_FinalParticleID(PiMinus);
 
  locReactionStep->Add_FinalParticleID(Pi0);
 
  locReactionStep->Set_MissingParticleIndex(-1); //none missing
 
  locReactionSteps.push_back(locReactionStep);
 
  dReactionStepPool.push_back(locReactionStep); //prevent memory leak
 
 
  //pi0 -> gamma, gamma
 
  locReactionStep = new DReactionStep();
 
  locReactionStep->Set_InitialParticleID(Pi0);
 
  locReactionStep->Set_TargetParticleID(Unknown); //no target for this step
 
  locReactionStep->Add_FinalParticleID(Gamma);
 
  locReactionStep->Add_FinalParticleID(Gamma);
 
  locReactionStep->Set_MissingParticleIndex(-1); //none missing
 
  locReactionSteps.push_back(locReactionStep);
 
  dReactionStepPool.push_back(locReactionStep); //prevent memory leak
 
 
/**************************************************** b1pi ****************************************************/
 
 
  locReaction = new DReaction("b1pi");
 
  locReaction->Set_KinFitType(d_P4AndVertexFit); //defined in DKinFitResults.h
 
  for(size_t loc_i = 0; loc_i < locReactionSteps.size(); ++loc_i)
 
    locReaction->Add_ReactionStep(locReactionSteps[loc_i]);
 
 
  //Extremely Loose Mass Cuts
 
  locReaction->Add_AnalysisAction(new DCutAction_MissingMass(locReaction, false, 0.1, 1.6, "Proton_Loose")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DCutAction_InvariantMass(locReaction, Pi0, false, 0.0, 0.5, "Pi0_Loose")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DCutAction_InvariantMass(locReaction, omega, false, 0.2, 1.4, "omega_Loose")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DCutAction_InvariantMass(locReaction, b1_1235_Plus, false, 0.6, 1.8, "b1(1235)+_Loose")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DCutAction_InvariantMass(locReaction, Unknown, false, 1.0, 3.0, "X(2000)_Loose")); //false: measured data
 
 
  //PID
 
  locReaction->Add_AnalysisAction(new DHistogramAction_PID(locReaction));
 
  locReaction->Add_AnalysisAction(new DCutAction_AllPIDFOM(locReaction, 0.01)); //1%
 
  locReaction->Add_AnalysisAction(new DHistogramAction_TruePID(locReaction, "PostPID"));
 
 
  //Initial Mass Distributions
 
  locReaction->Add_AnalysisAction(new DHistogramAction_MissingMass(locReaction, false, 650, 0.3, 1.6, "PostPID")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DHistogramAction_InvariantMass(locReaction, Pi0, false, 500, 0.0, 0.5, "Pi0_PostPID")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DHistogramAction_InvariantMass(locReaction, omega, false, 600, 0.2, 1.4, "omega_PostPID")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DHistogramAction_InvariantMass(locReaction, b1_1235_Plus, false, 600, 0.6, 1.8, "b1(1235)+_PostPID")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DHistogramAction_InvariantMass(locReaction, Unknown, false, 1000, 1.0, 3.0, "X(2000)_PostPID")); //false: measured data
 
 
  //Kinematic Fit Results and Confidence Level Cut
 
  locReaction->Add_AnalysisAction(new DHistogramAction_KinFitResults(locReaction, 0.05)); //5% confidence level cut on pull histograms only
 
  locReaction->Add_AnalysisAction(new DCutAction_KinFitFOM(locReaction, 0.01)); //1%
 
 
  //Constrained Mass Distributions
 
  locReaction->Add_AnalysisAction(new DHistogramAction_MissingMass(locReaction, false, 650, 0.3, 1.6, "PostKinFitConLev")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DHistogramAction_InvariantMass(locReaction, Pi0, false, 500, 0.0, 0.5, "Pi0_PostKinFitConLev")); //false: measured data
 
 
  //omega cut
 
  locReaction->Add_AnalysisAction(new DHistogramAction_InvariantMass(locReaction, omega, false, 600, 0.2, 1.4, "omega_PostKinFitConLev_Measured")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DHistogramAction_InvariantMass(locReaction, omega, true, 600, 0.2, 1.4, "omega_PostKinFitConLev_KinFit")); //true: kinfit data
 
  locReaction->Add_AnalysisAction(new DCutAction_InvariantMass(locReaction, omega, true, 0.6, 1.0, "omega_PostKinFit")); //true: kinfit data
 
 
  //b1(1235)+ cut
 
  locReaction->Add_AnalysisAction(new DHistogramAction_InvariantMass(locReaction, b1_1235_Plus, false, 600, 0.6, 1.8, "b1(1235)+_PostKinFitConLev_Measured")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DHistogramAction_InvariantMass(locReaction, b1_1235_Plus, true, 600, 0.6, 1.8, "b1(1235)+_PostKinFitConLev_KinFit")); //true: kinfit data
 
  locReaction->Add_AnalysisAction(new DCutAction_InvariantMass(locReaction, b1_1235_Plus, true, 1.1, 1.5, "b1(1235)+_PostKinFit")); //true: kinfit data
 
 
  //Signal Mass Hist
 
  locReaction->Add_AnalysisAction(new DHistogramAction_InvariantMass(locReaction, Unknown, false, 1000, 1.0, 3.0, "X(2000)_PostKinFitConLev_Measured")); //false: measured data
 
  locReaction->Add_AnalysisAction(new DHistogramAction_InvariantMass(locReaction, Unknown, true, 1000, 1.0, 3.0, "X(2000)_PostKinFitConLev_KinFit")); //true: kinfit data
 
 
  //Final Track Kinematics & PID Check
 
  locReaction->Add_AnalysisAction(new DHistogramAction_TrackVertexComparison(locReaction, "Final"));
 
  locReaction->Add_AnalysisAction(new DHistogramAction_ParticleComboKinematics(locReaction, true, "Final")); //true: kinfit data
 
  locReaction->Add_AnalysisAction(new DHistogramAction_TruePID(locReaction, "Final"));
 
 
  _data.push_back(locReaction); //save the DReaction
 
 
  return NOERROR;
 
}
 
</syntaxhighlight>
 
 
== User Plugin DEventProcessor ==
 
* The <span style="color:#0000FF">DEventProcessor</span> itself can be extremely minimal in content.
 
* This is from sim-recon/src/programs/Analysis/plugins/b1pi_hists/
 
<syntaxhighlight>
 
// Routine used to create our DEventProcessor
 
extern "C"
 
{
 
  void InitPlugin(JApplication *app)
 
  {
 
    InitJANAPlugin(app);
 
    app->AddProcessor(new DEventProcessor_b1pi_hists());
 
    app->AddFactoryGenerator(new DFactoryGenerator_DReaction());
 
  }
 
} // "C"
 
 
//------------------
 
// evnt
 
//------------------
 
jerror_t DEventProcessor_b1pi_hists::evnt(JEventLoop *locEventLoop, int eventnumber)
 
{
 
  vector<const DAnalysisResults*> locAnalysisResultsVector;
 
  locEventLoop->Get(locAnalysisResultsVector);
 
  return NOERROR;
 
}
 
</syntaxhighlight>
 
 
== Program Output ==
 
* Other than the built-in histograms, you are currently on your own for this.  Output any data you want in either your own <span style="color:#0000FF">DAnalysisAction</span> or in your <span style="color:#0000FF">DEventProcessor</span>::<span style="color:#008000">evnt</span>() method.
 
 
== Tricks for saving time and memory ==
 
* Change the binning and/or range of the built-in histograms after constructing the corresponding <span style="color:#0000FF">DAnalysisAction</span> object.
 
* Because there may be many <span style="color:#0000FF">DParticleCombo</span> objects for an event, perform as many cuts as possible prior to kinematic fitting. 
 
** This includes extremely-loose cuts (well beyond the range at which your final cut will be) on all of the physical quantities of interest (e.g. mass peaks).
 
* To branch an analysis, create a new (but identical) <span style="color:#0000FF">DReaction</span> object (with the same <span style="color:#0000FF">DReactionStep</span> pointers), then simply repeat or change any of the <span style="color:#0000FF">DAnalysisActions</span>.
 
** If the <span style="color:#0000FF">DReactionStep</span> objects are re-used, the framework will realize that the <span style="color:#0000FF">DParticleComboBlueprintStep</span> objects will be the same, and will simply reuse them. 
 
*** Note that the <span style="color:#0000FF">DParticleCombo</span> objects will not be identical since they will contain a pointer to a different <span style="color:#0000FF">DReaction</span>.
 
*** If the kinematic fit type is also the same, it will skip the kinematic fit of the new <span style="color:#0000FF">DParticleCombo</span> objects entirely and just copy the previous results since they will be identical.
 
 
== RF Beam Bunch Selection & PID Details ==
 
* Note: These routines assume high-luminosity running (i.e. too many tagger photons to distinguish the RF bunch).
 
 
=== How RF bunch selection works for an event (creating a single DEventRFBunch object) ===
 
* The measured RF time and variance are assumed to be zero (until actual measured values are introduced).
 
* In <span style="color:#0000FF">DEventRFBunch_factory</span>: loop over <span style="color:#0000FF">DTrackTimeBased</span> objects, determine the matching TOF/BCAL/ST hits, propagate the matching time to the target center and select the closest-matching RF bunch (+/- multiples of the RF bunch frequency).
 
** Note: Hit-use order: use TOF hit if present, else use BCAL hit if present and track momentum > 250 MeV/c. Only use ST hit if present and no tracks have good TOF/BCAL hits to use.
 
*** TOF-hit resolution (80ps) is good enough to pick RF bunch regardless of momentum or if correct PID is used to propagate the time (e.g. won't reconstruct protons below 300 MeV/c anyway, etc.)
 
*** BCAL resolution is ~310ps at 250 MeV/c, pi/K delta-t error is ~40ps (proton too slow): 3sigma + delta-t error = ~970ps < 1.002 ns
 
*** ST resolution projected 350ps - 400ps: not good enough to select RF bunch (OK if enough voting tracks)
 
** Note: tracks with bad vertex-z are ignored, and tracks with low track-reconstruction FOM are ignored unless there's no good tracks.
 
** Note: if there are no TOF/BCAL/ST hits with good tracks, then tracks with low tracking FOM are used.
 
*** If still no good hits, then the track times from time-based tracking is used (first from good-tracking-FOM tracks, then all).
 
* Vote: select the RF bunch that matches the most tracks (tie broken by highest average tracking FOM).
 
 
=== How DChargedTrackHypothesis PID FOM calculation works ===
 
* Determine the track start time:
 
** Try: match the track to its RF bunch using the method described above.
 
** Else try: use the DEventRFBunch RF time if it was matched to other tracks.
 
** Else try: use the measured track t0 time (ST, CDC) (will fail if t0 time = t1 time (e.g. both CDC (e.g. no ST/TOF/etc. hits of any kind)))
 
** Note: each track may match to a different RF bunch: this allows the correct PID to be determined for background tracks originating from nearby beam buckets.
 
* Propagate both the TOF/BCAL/etc. time and the RF time to the track vertex, and compare them to calculate FOM. 
 
 
=== How DNeutralParticleHypothesis PID FOM calculation works ===
 
* Propagate shower times to the target center, compare them to the <span style="color:#0000FF">DEventRFBunch</span> time.
 

Latest revision as of 07:41, 3 November 2017

Reaction Analysis Factories

  • NOTE: Most of these are located in sim-recon/src/libraries/ANALYSIS/

Pre-Selection

  • DNeutralShower_factory_PreSelect: Pre-selects which DNeutralShower objects should be included in analyses.
  • DChargedTrack_factory_PreSelect: Pre-selects which DChargedTrack objects should be included in analyses.

User Input

  • DReaction_factory: Creates DReaction objects to be analyzed. Needs to be created in each analysis plugin.

Combo Construction Factories

  • DTrackTimeBased_factory_Combo: If a charged PID is needed for an analysis for which a corresponding DTrackTimeBased is not present in the data, a new one is created. E.g. if mu+/- are requested. This uses the reconstructed momentum from the DTrackTimeBased object with the closest mass.
  • DDetectorMatches_factory_Combo: Stores the matching between each new DTrackTimeBased object (from the "Combo" factory) and the existing shower/hit objects. No new matching is done, it just uses the matching results from the source object. Also stores the matching results from the default factory.
  • DAnalysisResults_factory: Creates the combos via the DSourceComboer class (detailed below). Loops over the DAnalysisAction objects stored in each DReaction, and executing them on the corresponding DParticleCombo. This creates and fills histograms of the number of events and DParticleCombo objects that survive each cut.

Combo Construction Classes (not factories)

  • DSourceComboer: Finds all combos of charged tracks / neutral showers necessary to make the desired combos. Calls methods in the other DSourceCombo* classes below as needed. Also is responsible for dE/dx and E/p PID cuts.
  • DSourceComboTimeHandler: Responsible for PID timing cuts, binning photons by vertex-z, and RF bunch selection.
  • DSourceComboVertexHandler: Responsible for finding pre-kinfit vertex positions for the combos. If is photoproduction step, the POCA to the beamline of the tracks with θ closest to 90 degrees. Otherwise, is the POCA between the two closest tracks.
  • DSourceComboP4Handler: Responsible for placing invariant mass and missing mass squared cuts on the combos. Also for reconstructing the P4 of decaying particles as needed.
  • DParticleComboCreator: Takes the results from the DSourceComboer and creates DParticleCombo objects from them, along with new DChargedTrackHypothesis and DNeutralParticleHypothesis objects for the tracks (using the combo-specific vertex position for PID, etc.).

Thrown Factories

  • DReaction_factory_Thrown: Creates a DReaction object representing the thrown reaction. Final state particles listed in DMCThrown are ignored if they have decayed from pions, kaons, or other "typical" final state particles (e.g. muons, electrons, pions, and neutrinos are ignored if they decay from a kaon, etc.). Also, particles not defined in sim-recon/src/libraries/include/particleType.h are ignored.
  • DParticleCombo_factory_Thrown: Creates a DParticleCombo object representing the thrown reaction. The DMCThrown objects are used for the particle data, except pure DKinematicData objects are used for the beam particle and target objects (from DMCReaction). Final state particles listed in DMCThrown are ignored if they have decayed from pions, kaons, or other "typical" final state particles (e.g. muons, electrons, pions, and neutrinos are ignored if they decay from a kaon, etc.). Also, particles not defined in sim-recon/src/libraries/include/particleType.h are ignored.
  • DEventRFBunch_factory_Thrown: Creates a DEventRFBunch object for the simulated event.

Analysis Utilities

  • DParticleID: (Located in the PID library) Collection of functions used to match charged tracks to hits in the BCAL, FCAL, SC, and TOF, and to calculate the PID FOM from the TOF and DC dE/dx information.
  • DMCThrownMatching: Matches reconstructed particles to generated particles. Only the best match for each particle is saved.
    • For neutrals, compares the thrown and reconstructed shower momenta and uses the shower covariance matrix to calculate a match FOM. This FOM is NOT cut, so extremely poor matches are included in the results.
    • For tracks, compares the hits on the track to the thrown hits. First, the % of the track hits on each thrown track is computed (in the DTrackTimeBased factory), and the highest total is set in DTrackTimeBased (as well as the corresponding DMCThrown::myid). In the DMCThrownMatching factory, for each DTrackTimeBased, the number of matched hits is weighted (multiplied) by the track hit-fraction (#-hits-on-track-matched-to-MC / #-hits-on-track). Matches are then recorded in order from highest weighted-#-hits to least, such that each DMCThrown is only matched once (other matches are ignored). Hit fractions less than DMCThrownMatching::dMinTrackMatchHitFraction (default 0.5, set-able on command-line via -PMCMATCH:MIN_TRACK_MATCH) are ignored.
    • Also matches thrown and reconstructed BCAL, FCAL, and TOF hits, although currently only the TOF hits have been vetted.
  • DAnalysisUtilities: Collection of utility functions used to facilitate physics analyses. These include methods for calculating invariant mass, missing mass, DOCA, etc.
  • DKinFitter_GlueX: See GlueX Kinematic Fitting