Difference between revisions of "Mattione GlueX Analysis Factories"

From GlueXWiki
Jump to: navigation, search
(User Plugin DReaction_factory)
Line 44: Line 44:
<br style="clear:both;"/>
<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):
class DParticleComboStep
    const DParticleComboBlueprintStep* dParticleComboBlueprintStep; //contains PIDs, source objects
    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
    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
class DParticleCombo : public JObject
    const DReaction* dReaction;
    const DKinFitResults* dKinFitResults;
    deque<const DParticleComboStep*> dParticleComboSteps;
== User Plugin DEventProcessor ==
== User Plugin DEventProcessor ==

Revision as of 22:17, 17 February 2013


Analysis Procedure Details

Analysis Overview

  • Generate every possible combination of particles (DParticleCombo) that can represent the desired DReaction objects.
    • This can yield many DParticleCombo objects per event.
    • This is regardless of PID, # of remaining tracks, timing, track position or momentum, etc.
      • Only extremely loose cuts are placed by default on PID, track-vertex-z, and beam photon time prior to creating DParticleCombo objects: this is to avoid memory spikes from events with too many particles.
        • These can be changed by modifying the command line parameters defined in DParticleComboBlueprint_factory::brun() and DParticleCombo_factory_PreKinFit::brun().
  • User-specified cuts are then used to eliminate DParticleCombo objects that do not much the desired DReaction objects (e.g. PID, kinematic fit, invariant mass, etc.)
    • This is done by executing DAnalysisActions (e.g. histogramming, cutting) in sequence on each DParticleCombo until it fails a cut.
    • The kinematic fit (if specified) is not performed until the kinematic fit results are required for a DAnalysisAction (DAnalysisAction::Get_UseKinFitResultsFlag() == true). This saves time and memory by letting users cut DParticleCombo objects prior to fitting.
  • Save the results to disk further analysis (currently not built-in (except for histograms)).

Reaction Analysis

  • NOTE: These are located in sim-recon/src/libraries/ANALYSIS/
  • DReaction_factory: Creates DReaction objects to be analyzed. Needs to be created in each analysis plugin.
  • DParticleComboBlueprint_factory: Creates a DParticleComboBlueprint object for each possible track combination, excluding any possible multiplicity from multiple beam photons. These DParticleComboBlueprint objects store pointers to which DChargedTrack and DNeutralShower objects will be used for each particle in the reaction. The beam photon multiplicity is handled in DParticleCombo_factory_PreKinFit.
  • DTrackTimeBased_factory_Reaction: If none of the existing DTrackTimeBased objects for a given reconstructed track have the needed PID for a particle in a DReaction, this creates new DTrackTimeBased objects for them (e.g. e-, or if one of the default PIDs (e.g. π+) fails reconstruction while the others don't (e.g. K+)). This uses the reconstructed momentum from the DTrackTimeBased object with the closest mass, and re-swims the track.
  • DChargedTrackHypothesis_factory_Reaction: Creates DChargedTrackHypothesis objects for the DTrackTimeBased objects created by DTrackTimeBased_factory_Reaction.
  • DParticleCombo_factory_PreKinFit: Creates a DParticleCombo object for each DParticleComboBlueprint, setting the data with the measured DChargedTrackHypothesis, DNeutralParticleHypothesis, and DBeamPhoton objects. A loose timing cut is placed between the DEventRFBunch time and the DBeamPhoton objects, and additional DParticleCombo objects are created if more than one DBeamPhoton object survives the cut.
  • DAnalysisResults_PreKinFit: Loops over the DAnalysisAction objects stored in each DReaction, executing them on the corresponding DParticleCombo objects until the kinematic fit results are needed for an action (DAnalysisAction::Get_UseKinFitResultsFlag() == true). This allows DAnalysisAction 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 DParticleCombo 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 DParticleCombo that survived all of the cuts executed in DAnalysisResults_PreKinFit, perform the kinematic fit specified by the DReaction objects (if desired). See the "DKinFitResults_factory" section of GlueX Kinematic Fitting for more details.
  • DChargedTrackHypothesis_factory_KinFit: Create DChargedTrackHypothesis objects containing the kinematically fit track parameters. New, unique objects are created for each charged particle in each kinematically fit DParticleCombo.
  • DNeutralParticleHypothesis_factory_KinFit: Create DNeutralParticleHypothesis objects containing the kinematically fit track parameters. New, unique objects are created for each neutral particle in each kinematically fit DParticleCombo.
  • DBeamPhoton_factory_KinFit: Create DBeamPhoton objects containing the kinematically fit track parameters. New, unique objects are created for each beam photon in each kinematically fit DParticleCombo.
  • DParticleCombo_factory: Creates a new DParticleCombo object in each DParticleCombo that survived all of the cuts executed in DAnalysisResults_PreKinFit, but containing the kinematically fit track parameters (in addition to the original, measured parameters).
  • DAnalysisResults_factory: Loops over the DAnalysisAction objects stored in each DReaction, skipping those that were executed by DAnalysisResults_PreKinFit, and executing the remaining ones on the corresponding DParticleCombo objects created by DParticleCombo_factory. This creates and fills histograms of the number of events and DParticleCombo objects that survive each cut.

Analysis Utilities

  • 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.
  • DMCThrownMatching: Matches reconstructed particles to generated particles.
  • 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 DParticleCombo is in some ways similar to other DParticleCombo objects (e.g. the same track hypotheses make up a given decay chain) (useful for preventing double-counting when histogramming (e.g. invariant mass)).
  • DKinFitter_GlueX: See GlueX Kinematic Fitting

Factories Tree

  • This tree was generated using the b1pi_hists plugin on December 8, 2012.
Mattione AnalysisFactories b1piFactoryTree.png

User Plugin DEventProcessor

  • The DEventProcessor itself can be extremely minimal in content.
  • This is from sim-recon/src/programs/Analysis/plugins/b1pi_hists/
// Routine used to create our DEventProcessor
extern "C"
  void InitPlugin(JApplication *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;
  return NOERROR;

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 DAnalysisAction or in your DEventProcessor::evnt() method.

Tricks for saving time and memory

  • Change the binning and/or range of the built-in histograms after constructing the corresponding DAnalysisAction object.
  • Because there may be many DParticleCombo 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) DReaction object (with the same DReactionStep pointers), then simply repeat or change any of the DAnalysisActions.
    • If the DReactionStep objects are re-used, the framework will realize that the DParticleComboBlueprintStep objects will be the same, and will simply reuse them.
      • Note that the DParticleCombo objects will not be identical since they will contain a pointer to a different DReaction.
      • If the kinematic fit type is also the same, it will skip the kinematic fit of the new DParticleCombo 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 DEventRFBunch_factory: loop over DTrackTimeBased 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 DEventRFBunch time.