Difference between revisions of "Analysis DReaction"

From GlueXWiki
Jump to: navigation, search
(Summary)
(DReactionStep Notes)
Line 36: Line 36:
 
locReactionStep->Add_FinalParticleID(Proton, true); //missing proton
 
locReactionStep->Add_FinalParticleID(Proton, true); //missing proton
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
* '''IMPORTANT NOTE FOR ANALYZERS''': Resonance PIDs (except for &omega; and &phi;) are not allowed anywhere in a <span style="color:#0000FF">DReactionStep</span>.  This is because you cannot identify on an event-by-event basis which particles decayed from a resonance and which did not.  However, since they are extremely narrow, the &omega; and &phi; resonances are allowed. 
  
 
* '''IMPORTANT NOTE FOR ANALYZERS''': If a PID you need to use for your analysis is not defined by <span style="color:#0000FF">Particle_t</span>, you can use "Unknown" instead (e.g. a rare resonance) (if you don't need its mass or charge). However, only one PID per <span style="color:#0000FF">DReaction</span> can have the <span style="color:#0000FF">Particle_t</span> of "Unknown" (e.g. the resonance you are studying), because the framework will not distinguish between the two.  If you need more than one PID that is not included in <span style="color:#0000FF">Particle_t</span>, then add all of the PIDs you need but one to particleType.h (along with their charges, masses, names, etc.) and check in the update (because other people may need those particles too!).
 
* '''IMPORTANT NOTE FOR ANALYZERS''': If a PID you need to use for your analysis is not defined by <span style="color:#0000FF">Particle_t</span>, you can use "Unknown" instead (e.g. a rare resonance) (if you don't need its mass or charge). However, only one PID per <span style="color:#0000FF">DReaction</span> can have the <span style="color:#0000FF">Particle_t</span> of "Unknown" (e.g. the resonance you are studying), because the framework will not distinguish between the two.  If you need more than one PID that is not included in <span style="color:#0000FF">Particle_t</span>, then add all of the PIDs you need but one to particleType.h (along with their charges, masses, names, etc.) and check in the update (because other people may need those particles too!).

Revision as of 16:55, 13 December 2013

Summary

  • Note: The objects (not the factory) are located in: src/libraries/ANALYSIS/
  • DReactionStep: Contains the particle types for an interaction or decay step in a reaction.
    • The particle types are from the Particle_t enum defined in sim-recon/src/libraries/include/particleType.h
  • DReaction: Contains the DReactionStep objects for a reaction, along with (optional) analysis actions/instructions.
  • DReaction_factory: Users should create the DReaction objects they want to study in this factory, and place it in their plugin.
    • It is recommended that users create their class with a unique name and corresponding tag so that multiple analysis plugins can be run simultaneously.
  • The MakeReactionPlugin.pl perl script can be used to create template code for a new plugin.

DReaction Notes

  • The user should create a DReaction object in their plugin for each analysis they want to perform (can analyze more than one at once). For example, by creating additional DReaction objects you can:
    • Analyze different reactions in the same plugin.
    • Treat different particles as missing in the same reaction (or have no particles missing).
    • Perform different kinematic fits to the same reaction (e.g. compare results from p4-only and vertex-p4 fits)
    • Perform different DAnalysisActions to compare the results from having different cuts.
  • IMPORTANT NOTE FOR DEVELOPERS: Grabbing the DReaction objects from JANA is tricky, because a user may have several factories per plugin, or may be running several plugins at once. See DParticleComboBlueprint_factory::evnt() for an example on how to correctly grab all DReaction objects from JANA.

DReactionStep Notes

  • The DReactionStep objects must be added to the DReaction in the correct order: the decay step for a particle must always be after its production step (it can be anywhere after it, but it must be after it).
    • However, you can study (for example) π0 decays without a π0 production step if you don't care how they're produced. E.g.:
//pi0 -> gamma, gamma
DReaction* locReaction = new DReaction("pi0"); //unique name
DReactionStep* locReactionStep = new DReactionStep();
locReactionStep->Set_InitialParticleID(Pi0);
locReactionStep->Add_FinalParticleID(Gamma);
locReactionStep->Add_FinalParticleID(Gamma);
locReaction->Add_ReactionStep(locReactionStep);
  • To define one of the particles as missing, when adding the particle add the optional "true" flag:
locReactionStep->Add_FinalParticleID(Proton, true); //missing proton
  • IMPORTANT NOTE FOR ANALYZERS: Resonance PIDs (except for ω and φ) are not allowed anywhere in a DReactionStep. This is because you cannot identify on an event-by-event basis which particles decayed from a resonance and which did not. However, since they are extremely narrow, the ω and φ resonances are allowed.
  • IMPORTANT NOTE FOR ANALYZERS: If a PID you need to use for your analysis is not defined by Particle_t, you can use "Unknown" instead (e.g. a rare resonance) (if you don't need its mass or charge). However, only one PID per DReaction can have the Particle_t of "Unknown" (e.g. the resonance you are studying), because the framework will not distinguish between the two. If you need more than one PID that is not included in Particle_t, then add all of the PIDs you need but one to particleType.h (along with their charges, masses, names, etc.) and check in the update (because other people may need those particles too!).

Setting up DReactionStep Example: b1pi

jerror_t DReaction_factory_b1pi_hists::init(void)
{
  DReactionStep* locReactionStep;
 
  DReaction* locReaction = new DReaction("b1pi"); //unique name
 
/**************************************************** 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, true); //proton missing
  locReaction->Add_ReactionStep(locReactionStep);
 
  //x(2000) -> b1(1235)+, pi-
  locReactionStep = new DReactionStep();
  locReactionStep->Set_InitialParticleID(Unknown); //x(2000)
  locReactionStep->Add_FinalParticleID(b1_1235_Plus);
  locReactionStep->Add_FinalParticleID(PiMinus);
  locReaction->Add_ReactionStep(locReactionStep);
 
  //b1(1235)+ -> omega, pi+
  locReactionStep = new DReactionStep();
  locReactionStep->Set_InitialParticleID(b1_1235_Plus);
  locReactionStep->Add_FinalParticleID(omega);
  locReactionStep->Add_FinalParticleID(PiPlus);
  locReaction->Add_ReactionStep(locReactionStep);
 
  //omega -> pi+, pi-, pi0
  locReactionStep = new DReactionStep();
  locReactionStep->Set_InitialParticleID(omega);
  locReactionStep->Add_FinalParticleID(PiPlus);
  locReactionStep->Add_FinalParticleID(PiMinus);
  locReactionStep->Add_FinalParticleID(Pi0);
  locReaction->Add_ReactionStep(locReactionStep);
 
  //pi0 -> gamma, gamma
  locReactionStep = new DReactionStep();
  locReactionStep->Set_InitialParticleID(Pi0);
  locReactionStep->Add_FinalParticleID(Gamma);
  locReactionStep->Add_FinalParticleID(Gamma);
  locReaction->Add_ReactionStep(locReactionStep);

DReaction Control Variables

Kinematic Fit Type

  • Defined by the DKinFitType enum in sim-recon/src/libraries/Analysis/DKinFitResults.h
    • Values: d_NoFit, d_P4Fit, d_VertexFit, d_SpacetimeFit, d_P4AndVertexFit, d_P4AndSpacetimeFit
    • P4 fits include mass constraints
    • The spacetime fits are currently unsupported.

TTree Output

  • Output the results from the analysis of a DReaction is disabled by default, and must be enabled for each desired DReaction. This enabling is in addition to actually writing out the TTree (see Standard TTree for details). To enable TTree output for a DReaction, call:
locReaction->Enable_TTreeOutput("tree_b1pi.root"); //string is output file name (must end in ".root"!!)
  • Note that if you specify more than one DReaction to have the same file name, then they will both be saved in the same file.

Comboing Cuts

  • There are several different cuts the user can place to cut out potential particle combinations that are "obviously" invalid before they are created.
  • These are useful for reducing memory usage spikes and cpu-time, especially in events with many (10+) garbage tracks/showers (in some cases the # of DParticleCombos can exceed 20000)
  • Most of these cuts are disabled by default.
  • The values of these cuts are overridden if specified on the command line.
DReaction set/enable method Command-line parameter Default Comment
Set_MinIndividualPIDFOM(double) COMBO:MIN_INDIVIDUAL_PID_FOM disabled Minimum individual particle PID confidence level. Combined cut preferred.
Set_MinCombinedPIDFOM(double) COMBO:MIN_COMBINED_PID_FOM disabled Minimum combined PID confidence level for all particles in the combo.
Set_MinIndividualTrackingFOM(double) COMBO:MIN_INDIVIDUAL_TRACKING_FOM disabled Minimum individual-track tracking confidence level. Combined cut preferred.
Set_MinCombinedTrackingFOM(double) COMBO:MIN_COMBINED_TRACKING_FOM disabled Minimum combined tracking confidence level for all charged tracks in the combo.
Set_MaxPhotonRFDeltaT(double) COMBO:MAX_PHOTON_RF_DELTAT disabled Maximum photon-RF time difference. For selecting potential beam photon(s) during high-luminosity running.
Set_MinProtonMomentum(double) COMBO:MIN_PROTON_MOMENTUM enabled, 0.3 GeV/c Minimum momentum for a DChargedTrack without a "Proton" hypothesis (e.g. failed tracking: slow pion) to be tested as a proton during comboing (default value from track reconstruction).


Custom Track / Shower Pre-selection

  • Users can place custom cuts to select a subset of the reconstructed DChargedTrack and DNeutralShower objects. To do this, create factories in your plugin(s) that perform the desired cuts. Tracks and showers that survive these cuts should be cloned and saved as data members of those factories. Then, specify which factories you would like to use for each DReaction (or use the command line to set it for all DReactions).
  • Example: A pre-selection factory cutting on the DNeutralShower energy (where "MyShowers" is the factory tag):
jerror_t DNeutralShower_factory_MyShowers::evnt(JEventLoop* locEventLoop, int locEventNumber)
{
  vector<const DNeutralShower*> locNeutralShowers;
  locEventLoop->Get(locNeutralShowers);
  for(size_t loc_i = 0; loc_i < locNeutralShowers.size(); ++loc_i)
  {
    if(locNeutralShowers[loc_i]->dEnergy < 0.02) //e.g. 20 MeV
      continue;
    DNeutralShower* locNeutralShower = new DNeutralShower(locNeutralShowers[loc_i]); //clone the shower
    _data.push_back(locNeutralShower); //save a clone of the shower
  }
  return NOERROR;
}
  • Tell JANA that your factory exists by setting it in your plugin's factory generator:
jerror_t GenerateFactories(jana::JEventLoop *loop)
{
  loop->AddFactory(new DReaction_factory_b1pi_hists());
  loop->AddFactory(new DNeutralShower_factory_MyShowers());
  return NOERROR;
}
  • Enable the usage of these factories for your DReaction:
locReaction->Set_NeutralShowerFactoryTag("MyShowers"); //factory tag
locReaction->Set_ChargedTrackFactoryTag("MyTracks"); //factory tag
  • Flags used to enable the usage of the desired factories for all DReactions via the command line:
-PCOMBO:REACTION_TRACK_SELECT_TAG=MyShowers -PCOMBO:REACTION_SHOWER_SELECT_TAG=MyTracks

Example: b1pi

// continuation of DReaction_factory_b1pi_hists::init()
/**************************************************** b1pi Control Variables ****************************************************/
 
  // Type of kinematic fit to perform:
  locReaction->Set_KinFitType(d_P4AndVertexFit); //enum defined in DKinFitResults.h
 
  // Comboing cuts: used to cut out potential particle combinations that are "obviously" invalid
    // e.g. contains garbage tracks, PIDs way off
  // These cut values are overriden if specified on the command line
  locReaction->Set_MinCombinedChargedPIDFOM(0.001);
  locReaction->Set_MinCombinedTrackingFOM(0.001);
 
  // Enable ROOT TTree Output
  locReaction->Enable_TTreeOutput("tree_b1pi.root"); //string is file name (must end in ".root"!!)

Adding DAnalysisActions to DReaction Example: b1pi

// continuation of DReaction_factory_b1pi_hists::init()
/**************************************************** b1pi Actions ****************************************************/
 
  //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
 
  //PID
  locReaction->Add_AnalysisAction(new DHistogramAction_ParticleComboKinematics(locReaction, false)); //false: measured data
  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); //Register the DReaction
 
  return NOERROR;
}