Difference between revisions of "Analysis Actions"

Revision as of 19:41, 17 February 2013

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 = "") (used for specifying the optional signal-mass region).

• DHistogramAction_TrackVertexComparison(const DReaction* locReaction, string locActionUniqueString = ""): Histogram the comparison between the track trajectories, and between the track and reconstructed spacetime positions. It uses the kinematically fit spacetime if available, else calculates values (average time, midpoint of the DOCA line between the two closest particles)

• DHistogramAction_KinFitResults(const DReaction* locReaction, double locPullHistConfidenceLevelCut, string locActionUniqueString = ""): Histogram the confidence level and pulls for of the kinematic fits. The pulls are only histogrammed for DParticleCombo objects with confidence level greater than the specified cut (recommended: 0.05).

• DHistogramAction_InvariantMass(const DReaction* locReaction, Particle_t locInitialPID, bool locUseKinFitResultsFlag, unsigned int locNumMassBins, double locMinMass, double locMaxMass, string locActionUniqueString = ""): Histogram the invariant mass of the decay products of the decaying particle specified by locInitialPID, using the specified histogram binning.
  • Remember to use locActionUniqueString if histogramming more than one invariant mass peak!

• DHistogramAction_MissingMass(const DReaction* locReaction, bool locUseKinFitResultsFlag, unsigned int locNumMassBins, double locMinMass, double locMaxMass, string locActionUniqueString = ""): Histogram the missing mass of the reaction, using the specified histogram binning.

• DHistogramAction_MissingMassSquared(const DReaction* locReaction, bool locUseKinFitResultsFlag, unsigned int locNumMassBins, double locMinMassSq, double locMaxMassSq, string locActionUniqueString = ""): Histogram the missing mass squared of the reaction, using the specified histogram binning.

Pre-defined Cut Actions

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

• DCutAction_MaxNumParticleCombos(const DReaction* locReaction, unsigned int locMaxNumParticleCombos, string locActionUniqueString = ""): Cut all of the DParticleCombo objects for an event if there are more than locMaxNumParticleCombos.

• DCutAction_PIDFOM(const DReaction* locReaction, Particle_t locStepPID, Particle_t locParticleID, double locMinimumConfidenceLevel, string locActionUniqueString = ""): Cut all DParticleCombo objects for which the PID FOM of the particle(s) specified by locStepPID and locParticleID is not at least locMinimumConfidenceLevel. If no PID information is available for the particle (e.g. no TOF/BCAL/etc. hits), it is not cut.
  • Note: The multi-dimensional DCutAction_AllPIDFOM action is preferred over this cut.

• DCutAction_AllPIDFOM(const DReaction* locReaction, double locMinimumConfidenceLevel, string locActionUniqueString = ""): Cut all DParticleCombo objects for which the overall PID FOM of the charged particles (neutral disabled for now) is not at least locMinimumConfidenceLevel. If no PID information is available for one of the particles (e.g. no TOF/BCAL/etc. hits), it is not cut.

• DCutAction_TruePID(const DReaction* locReaction, Particle_t locTruePID, Particle_t locInitialPID, string locActionUniqueString = ""): Cut all DParticleCombo objects for which the DReaction particle(s) specified by locStepPID and locTruePID are mis-identified.

• DCutAction_AllTruePID(const DReaction* locReaction, string locActionUniqueString = ""): Cut all DParticleCombo objects for which the particles have not been assigned the correct PID. This also rejects all combos that contain (garbage) particles that are not matched to any generated particles.

• DCutAction_AllVertexZ(const DReaction* locReaction, double locMinVertexZ, double locMaxVertexZ, string locActionUniqueString = ""):

• DCutAction_MaxTrackDOCA(const DReaction* locReaction, Particle_t locInitialPID, double locMaxTrackDOCA, string locActionUniqueString = ""):

• DCutAction_KinFitFOM(const DReaction* locReaction, double locMinimumConfidenceLevel, string locActionUniqueString = ""):

• DCutAction_MissingMass(const DReaction* locReaction, bool locUseKinFitResultsFlag, double locMinimumMissingMass, double locMaximumMissingMass, string locActionUniqueString = ""):

• DCutAction_MissingMassSquared(const DReaction* locReaction, bool locUseKinFitResultsFlag, double locMinimumMissingMassSq, double locMaximumMissingMassSq, string locActionUniqueString = ""):

• DCutAction_InvariantMass(const DReaction* locReaction, Particle_t locInitialPID, bool locUseKinFitResultsFlag, double locMinimumInvariantMass, double locMaximumInvariantMass, string locActionUniqueString = ""):