Analysis Actions

Summary

• It is often desirable to place cuts and make histograms of the data in JANA prior to making a ROOT TTree.
  • For example: data monitoring, cuts to reduce the # of kinematic fits, cuts on the pid or kinematic fit confidence levels, comparison of mass distributions before/after the kinematic fit, skim cuts, etc.
• DAnalysisAction objects enable users to easily integrate these tasks into an analysis: they encapsulate the setup and execution of a given action.
• These actions can be executed directly, but if they are added to the DReaction they will be executed sequentially by the DAnalysisResults_factory.
  • Actions will be executed on a given DParticleCombo object until it fails a cut, after which the remaining actions won't be executed on that object.
• All analysis action objects inherit from DAnalysisAction.
  • Many common actions have been pre-defined in DHistogramActions.* and DCutActions.*, located in sim-recon/src/libraries/ANALYSIS/
  • Additional, custom actions can be created in any plugin.

Reaction-Independent Actions

• Reaction-independent actions are actions that can be executed independently from the rest of the analysis framework. They do not depend on DReaction or DParticleCombo in any way.
  • These actions (should) have a default (void) constructor, distinguishing them from reaction-dependent actions (which do not).
• However, they can be added to DReaction objects and executed in sequence with the other DAnalysisAction objects.
  • This can be used to histogram reaction-independent quantities for events that satisfy cuts on your DReaction.
  • E.g.: Histogram the track multiplicity for events that satisfy a kinematic fit confidence level cut.

Setup and Execution

• There are (or should be) three different constructors for reaction-independent objects:
  • (const DReaction* locReaction, string locActionUniqueString = ""): Use this constructor if you want to add the action to a DReaction.
  • (void) and (string locActionUniqueString): Use these constructors when executing completely independently of any DReaction.

• The "locActionUniqueString" is used to distinguish the histograms between different instances of the same action.
  • For example, you may wish to create two sets of DHistogramAction_DetectedParticleKinematics histograms and have them filled under different scenarios.
  • locActionUniqueString should only be left unspecified (== "") up to one time (per thread), and other instances should be assigned a unique, distinguishing string.

• Example:

  //Define the actions (e.g., in plugin proccessor header file):
  DHistogramAction_TrackMultiplicity dHist_TrackMultiplicity;
  DHistogramAction_ThrownParticleKinematics dHist_ThrownParticleKinematics;
  DHistogramAction_DetectedParticleKinematics dHist_DetectedParticleKinematics;
  DHistogramAction_GenReconTrackComparison dHist_GenReconTrackComparison;
 
  //Execute the actions (e.g., in plugin processor evnt() method):
    //The histograms are created upon first-execution
  dHist_TrackMultiplicity(locEventLoop);
  dHist_ThrownParticleKinematics(locEventLoop);
  dHist_DetectedParticleKinematics(locEventLoop);
  dHist_GenReconTrackComparison(locEventLoop);

Pre-defined Actions

• Note: These can be found in sim-recon/src/libraries/ANALYSIS/DHistogramActions.*
• DHistogramAction_TrackMultiplicity: Histogram how many protons, pions, kaons, neutrals, etc. are reconstructed in each event.
  • Note: For particle ID, it uses the matching to the thrown tracks if available (from DMCThrownMatching), and the PID FOM if not available.
  • Note: You can histogram for different particle types by modifying the public dFinalStatePIDs variable before calling the function-call operator.
• DHistogramAction_ThrownParticleKinematics: Histogram the kinematics of the thrown particles, including momentum, θ, φ, vertex position, and vertex time.
  • Note: You can histogram for different particle types by modifying the public dFinalStatePIDs variable before calling the function-call operator.
• DHistogramAction_DetectedParticleKinematics: Histogram the kinematics of the detected particles, including momentum, θ, φ, vertex position, vertex time, β, Δβ, and tracking FOM.
  • Note: For particle ID, it uses the matching to the thrown tracks if available (from DMCThrownMatching), and the PID FOM if not available.
  • Note: You can histogram for different particle types by modifying the public dFinalStatePIDs variable before calling the function-call operator.
• DHistogramAction_GenReconTrackComparison: Histogram the difference between the reconstructed and thrown track kinematics, including momentum, θ, φ, vertex position, and vertex time.
  • Note: You can histogram for different particle types by modifying the public dFinalStatePIDs variable before calling the function-call operator.
• DHistogramAction_TOFHitStudy: Histogram the difference between the reconstructed and thrown TOF point information, including hit position, energy, and time.
  • Note: This action does not work on REST data, as the generated TOF hits are no longer available.

Reaction-Dependent Actions

• Reaction-dependent actions are actions that are designed to be executed on a given reaction's DParticleCombo objects.
  • They should be added to DReaction and executed by DAnalysisResults_factory's.
  • All of the constructors for these actions (should) require a DReaction* argument, distinguishing them from reaction-independent actions (which can have default constructors).
• The actions are executed sequentially, in the order they are added to the DReaction, by the DAnalysisResults_factory's.
  • Actions will be executed on a given DParticleCombo object until it fails a cut, after which the remaining actions won't be executed on that object.

Pre-defined Histogram Actions

• Notes:
  • These can be found in sim-recon/src/libraries/ANALYSIS/DHistogramActions.*
  • Note: All of these actions protect against double-counting. Only unique particles/combinations are histogrammed.
    • For example, when histogramming the Λ invariant mass in γ, p → K⁺, Λ, multiple DParticleCombo objects can have the same Λ invariant mass but different particles for the photon or K^⁺.
  • If locUseKinFitResultsFlag = true/false, the kinematically-fit/measured data is used to fill the histograms.
  • The "locActionUniqueString" is used to distinguish the histograms between different instances of the same action.
    • For example, you may wish to create two sets of DHistogramAction_DetectedParticleKinematics histograms and have them filled under different scenarios.
    • locActionUniqueString should only be left unspecified (== "") up to one time (per thread), and other instances should be assigned a unique, distinguishing string.

• DHistogramAction_ParticleComboKinematics(const DReaction* locReaction, bool locUseKinFitResultsFlag, string locActionUniqueString = ""): Histogram the kinematics of the particles at each position in the DReaction, including momentum, θ, φ, vertex position, vertex time, β, and Δβ.

• DHistogramAction_PID(const DReaction* locReaction, string locActionUniqueString = ""): Histogram the PID information for the particles at each position in the DReaction, including the overall, TOF, and DC dE/dx FOM, β and Δβ, and the p vs. θ distributions of tracks that low of NaN confidence level. If analyzing simulated data, the overall FOM for the particle type for each thrown type is also histogrammed.

• DHistogramAction_TruePID: Separately histograms the momentum and p vs. θ distributions for the particles at each position in the DReaction based on whether they have been assigned the correct/incorrect PID. Also, histogram whether every particle in the combo has the correct PID, and separately for combos with mass within the (optionally) specified signal mass region.
  • There are two constructors for this action: (const DReaction* locReaction, string locActionUniqueString = "") and (const DReaction* locReaction, Particle_t locInitialPID, double locMinMassSq, double locMaxMassSq, string locActionUniqueString = "")

• DHistogramAction_TrackVertexComparison(const DReaction* locReaction, string locActionUniqueString = ""):
• DHistogramAction_KinFitResults:
• DHistogramAction_InvariantMass:
• DHistogramAction_MissingMass:
• DHistogramAction_MissingMassSquared:

Pre-defined Cut Actions

• Note: These can be found in sim-recon/src/libraries/ANALYSIS/DCutActions.*