Analysis Actions

From GlueXWiki
Revision as of 17:58, 18 November 2015 by Pmatt (Talk | contribs) (Pre-defined Cut Actions)

Jump to: navigation, search

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.
  • The MakeAnalysisAction.pl perl script can be used to create template code for a new, custom action.
  • For details on how to perform an anti(opposite)-cut, and how to call an action from within another action, see the Analysis_FAQ Analysis FAQ.

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

  • 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.
      • WARNING: If you create two different objects of this type without unique action strings, such as one in each of two plugins and then run with both of those plugins simultaneously, you will double-count in any histograms and trees that are filled.
    • (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.

Execution

  • When these actions are not added to a const DReaction, you should call the Initialize() method before executing it.
  • There are two function-call operators that you can call to execute the action: one with particle combos as input, one without. If the action acts on particle combinations, you MUST use the operator with the combos as input.
  • For the combo-independent function-call operator, the return-type is bool: this is the same bool as returned by the Perform_Action() function. This allows access to the result from combo-independent cuts. This is only true for combo-independent actions.
  • For the combo-dependent function-call operator, the return-type is void: the bools for each combo returned by the Perform_Action() function can be found in the input.
  • 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;
  DHistogramAction_NumReconstructedObjects dHist_NumReconstructedObjects;
 
  //Initialize the actions (e.g. in plugin processor brun() method):
  dHist_TrackMultiplicity.Initialize(locEventLoop);
  dHist_ThrownParticleKinematics.Initialize(locEventLoop);
  dHist_DetectedParticleKinematics.Initialize(locEventLoop);
  dHist_GenReconTrackComparison.Initialize(locEventLoop);
  dHist_NumReconstructedObjects.Initialize(locEventLoop);
 
  //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);
  dHist_NumReconstructedObjects(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. Also fills a tree with strings of the thrown and detected track topologies (excludes decay products of the standard final state particles (e.g. excludes π+'s that decayed from K+'s)).
    • Note: For particle ID of the detected tracks, 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_ReconnedThrownKinematics: Histogram the kinematics of the thrown particles that match to reconstructed particles, including momentum, θ, φ, vertex position, and vertex time.
    • By default, a (modifiable) +/- 5σ cut is placed on the matching FOM.
    • 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.
    • By default, (modifiable) +/- 5σ cuts are placed on the tracking & PID FOMs.
    • 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_NumReconstructedObjects: Histogram the number of reconstructed objects in an event. These include # of tracks of each charge at each stage of the tracking, the number of showers and neutrals, the number of hits in the detectors, and the number of matches between tracks and hit objects.
  • DHistogramAction_Reconstruction: Histograms to study the quality of the reconstructed objects, independent of other detector systems.
  • DHistogramAction_Neutrals: Histograms to study the characteristics of neutral (not-matched-to-tracks) calorimeter showers.
  • DHistogramAction_DetectorMatching: Histograms to study the quality and efficiency of the matching between tracks and hits/showers in different detectors.
  • DHistogramAction_DetectorMatchParams: Histograms to study parameters derivable from the matching between tracks and hits/showers in different detectors, by charge and by PID.
  • DHistogramAction_DetectorPID: Histograms to study beta vs p and dE/dx vs p in various detectors.
  • DHistogramAction_EventVertex: Histogram the reconstructed event vertex position and time, as well as the event RF bunch time. Also histograms the kinematic fit results from the vertex fit.
  • 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.
  • WARNING: NEVER EVER create a reaction-dependent action object that is shared amongst multiple threads. Create a unique object for each thread. Objects that are created within factories (such as DReaction_factory) are fine. Objects that are members of your plugin's processor are not. This will cause race-condition issues between threads (specifically, on the DAnalysisAction::dPreviousParticleCombos member).

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: Histogram the kinematics of the particles at each position in the DReaction, including momentum, θ, φ, vertex position, vertex time, β, and Δβ.
  • DHistogramAction_ParticleComboGenReconComparison: Histogram the comparison between the thrown/reconstructed kinematics of the particles at each position in the DReaction, including Δp/p, Δθ, Δφ, pulls, etc.
  • DHistogramAction_PID: 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.
  • DHistogramAction_TrackVertexComparison: 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)
    • Note: needs to be improved: assumes that the particles at a given vertex cannot span several DReactionStep objects.
    • Note: needs to be improved: uses crude DOCA determination (assumes no magnetic field).
  • DHistogramAction_KinFitResults: 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: 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: Histogram the missing mass of the reaction, using the specified histogram binning. Two other constructors are included for histogramming the missing mass off of a particle or set of particles. See the class definition in DHistogramActions.h for details.
  • DHistogramAction_MissingMassSquared: Histogram the missing mass squared of the reaction, using the specified histogram binning. Other constructors are included for histogramming the missing mass squared off of a particle or set of particles. See the class definition in DHistogramActions.h for details.
  • DHistogramAction_MissingTransverseMomentum: Histogram the missing transverse momentum off of the final state particles, using the specified histogram binning.

Pre-defined Cut Actions

  • Note: These can be found in sim-recon/src/libraries/ANALYSIS/DCutActions.*
  • DCutAction_MaxNumParticleCombos: Cut all of the DParticleCombo objects for an event if there are more than locMaxNumParticleCombos.
  • DCutAction_ThrownTopology: Cut on whether or not the thrown track topology matches the reaction specified in the input const DReaction. The locExactMatchFlag variable can be used to specify whether an exact match is required, or whether the particles/decays in locReaction need only be a subset of the thrown topology.
  • DCutAction_CombinedTrackingFOM: Cut all DParticleCombo objects for which the combined Tracking FOM of the particles is not at least locMinimumConfidenceLevel. If no tracking information is available for any of the particles it is not cut.
  • DCutAction_AllTracksHaveDetectorMatch: Cut if any of the tracks are not matched to any detector hits (ST/TOF/BCAL/FCAL).
  • DCutAction_PIDFOM: 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, unless the ZeroNDF flag is true.
  • DCutAction_EachPIDFOM: Cut all DParticleCombo objects for which the PID FOM of any particle 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, unless the ZeroNDF flag is true.
  • DCutAction_CombinedPIDFOM: Cut all DParticleCombo objects for which the combined PID FOM of the particles is not at least locMinimumConfidenceLevel. If no PID information is available for any of the particles (e.g. no TOF/BCAL/etc. hits) it is not cut.
  • DCutAction_TrueBeamParticle: Cut all DParticleCombo objects that have the wrong beam particle.
  • DCutAction_TrueCombo: Cut all DParticleCombo objects that don't match the thrown data. Cuts on DCutAction_ThrownTopology, DCutAction_TrueBeamParticle, does an identical cut as DCutAction_TruePID, AND requires that the particles come from the same decay chain (removes combinatoric background).
  • DCutAction_BDTSignalCombo: Cut all DParticleCombo objects that would not be signal combos for the BDT. Similar to DCutAction_TrueCombo, except other thrown topologies that decay to the DReaction topology are marked as signal (unless flag is set in constructor).
    • Note that if you have an ω or φ in your DReaction, you will still have to filter your combos prior to BDT input to remove duplicate entries. This is because the omega & phi masses are not constrained in the kinematic fit, nor should they be in the BDT, so you have duplicate entries from the point-of-view of the BDT due to combinatorics (e.g. which pions decayed from the omega, and which ones didn't, are irrelevant to the BDT).
  • DCutAction_TruePID: Cut all DParticleCombo objects for which the DReaction particle(s) specified by locStepPID and locTruePID are mis-identified. The locMinThrownMatchFOM variable is used as the cutoff in determining whether the detected and thrown particles match.
  • DCutAction_AllTruePID: 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. The locMinThrownMatchFOM variable is used as the cutoff in determining whether the detected and thrown particles match.
  • DCutAction_ProductionVertexZ: Cut all DParticleCombo objects for which the vertex-z of the first combo step is outside of the specified range.
  • DCutAction_AllVertexZ: Cut all DParticleCombo objects for which one of the particles has a vertex-z (z-position of POCA to beamline) outside of the specified range.
  • DCutAction_OneVertexKinFit: Kinematic fits all charged tracks in the combo to the same vertex, then cuts on the kinematic-fit FOM and/or the vertex-z position, as specified in the constructor arguments.
  • DCutAction_MaxTrackDOCA: Cut all DParticleCombo objects for which at least one pair of particles within the specified DReactionStep have a distance-of-closest-approach greater than locMaxTrackDOCA.
    • Note: needs to be improved: assumes that the particles at a given vertex cannot span several DReactionStep objects.
    • Note: needs to be improved: uses crude DOCA determination (assumes no magnetic field).
  • DCutAction_KinFitFOM: Cut all DParticleCombo objects for which the kinematic fit confidence level is not at least locMinimumConfidenceLevel. Also cuts all DParticleCombo objects for which the kinematic fit failed to converge.
  • DCutAction_MissingMass: Cut all DParticleCombo objects for which the missing mass is not within the specified range. Two other constructors are included for cutting the missing mass off of a particle or set of particles. See the class definition in DCutActions.h for details.
  • DCutAction_MissingMassSquared: Cut all DParticleCombo objects for which the missing mass squared is not within the specified range. Two other constructors are included for cutting the missing mass squared off of a particle or set of particles. See the class definition in DCutActions.h for details.
  • DCutAction_InvariantMass: Cut all DParticleCombo objects for which the invariant mass of the decay products of the specified particle is not within the specified range.
  • DCutAction_GoodEventRFBunch: Cut all DParticleCombo objects for which the DEventRFBunch is missing/present (as specified).
  • DCutAction_TransverseMomentum: Cut all DParticleCombo objects for which the total measured transverse momentum is greater than locMaxTransverseMomentum.
  • DCutAction_TrackHitPattern: Cut all DParticleCombo objects for which any of the tracks whose hit patterns do not meet the specified requirements.
  • DCutAction_ProtonPiPlusdEdx: Cut all DParticleCombo objects for which the dE/dx in the CDC is below the cut value for protons and above the cut value for π+'s. An optional argument determines whether to cut all high momentum protons in the dE/dx overlap region (and the region can be changed by setting the class member value).
  • DCutAction_TrackHitPattern: Cut all DParticleCombo objects for which the hits on the track don't match the specified pattern. See the header file for details.
  • DCutAction_TrackFCALShowerEOverP: Cut all DParticleCombo objects for which the track FCAL shower energy over the momentum is below the cut value for e+/e-'s and above the cut value for other tracks.
  • DCutAction_PIDDeltaT: Cut all DParticleCombo objects for which the Δt between the track and the RF is greater than the specified value. Can specify a specific PID to cut on (default = All) and/or a specific detector system for the end-track time source (default = All).
  • DCutAction_PIDTimingBeta: Cut all DParticleCombo objects for which the β is outside of the given range. Can specify a specific PID to cut on (default = All) and/or a specific detector system for the end-track time source (default = All).

Details for writing DAnalysisActions

Warnings on Creating Reaction-Independent Actions

  • Note: All of the below warnings apply when multiple threads have access to the same object. The most common case for this is when an action is created in your plugin procressor's header file and you run with more than one thread. Note that some of these warnings apply to any variable that is created as a member of your plugin's processor.
  • WARNING: Outside of the constructor, ALL class member variables should ONLY be modified while within a japp->RootWriteLock().
  • WARNING: All action class member variables that have a run-dependence should not be overwritten when a new run occurs, because another thread may still be on the previous run. Instead, a std::map should be used for the member variable with the key being the run number, and this map should only be accessed (and modified) within a lock.
  • WARNING: If one action object is being shared by multiple threads, multiple threads may enter the Initialize() function before the initialization is completed. This is not great but is OK as long as all class members are modified within a lock, and you check to see if the trees, histograms, etc. are created first before making new ones. This is impossible for DReaction-dependent actions; it typically only applies to actions created within your plugin processor.

Construction

  • Each class deriving from DAnalysisAction should be designed so that no user input is required after calling the constructor.
    • For example, the constructor should contain the DReaction that the action is to be performed on, the values of the cuts to be performed, whether to operate on pre-kinematic-fit or post-kinematic-fit data, etc.
      • Although for reaction-independent actions, non-DReaction constructors should also be provided.
      • However, the user should be allowed to perform "optional" modifications outside of the constructor (e.g. changing the default histogram range and binning).
    • The default DAnalysisAction constructor has been disabled (made private), so each constructor of each class deriving from DAnalysisAction must explicitly call the DAnalysisAction public constructor. This is to enforce proper setup of each DAnalysisAction.
    • Within a DReaction, each DAnalysisAction needs to have a unique name (for safe multi-threaded creation of histograms). This name is composed of a base-name built into the class itself that is unique to that class, and an optional unique identifier string that should be passed into the constructor by the user if more than one instance of a given class is performed in a given DReaction (e.g. make two different invariant mass histograms).

Initialization

  • The Initialize() function is used to create histograms, TTree objects, setup cuts, or any other operations that are needed to prepare the object for performing the desired action.
    • This function needs to be executed manually by the user if the DAnalysisAction is not added to the DReaction.
    • This function must be defined in each class deriving from DAnalysisAction, and should be declared as public.
    • If this is a reaction-independent action, then multiple threads may enter the Initialize() function simultaneously; make sure to only modify class members within a lock.
  • Creating ROOT Objects: In the Initialize() function, the following rules should be followed to create directories, histograms, etc. in the output ROOT file in an organized, thread-safe manner:
    • Acquire and release a JANA ROOT lock before (japp->RootWriteLock()) and after (japp->RootUnLock()) reading/creating/changing directories and creating histograms.
    • Special care should be taken when creating directories in the output file, because they may have already been created by another thread. Follow these rules for creating directories:
      • Call DAnalysisAction::CreateAndChangeTo_ActionDirectory() to create and change-to a directory that is unique to this analysis action (but NOT to this DAnalysisAction (important multi-threading distinction!: each thread will have it's own unique instance of the DAnalysisAction object)), yet is shared between threads. If the directory already exists (created by another thread), it just changes to it. This directory (and any desired sub-directories) should be used to store any histograms, trees, etc. that are created by this analysis action. This is why each DReaction needs to have a unique name, and each DAnalysisAction within a given DReaction needs to have a unique name.
      • Call DAnalysisAction::CreateAndChangeTo_Directory() to create and change-to new sub-directories within the main action directory. If the directory already exists (created by another thread), it just changes to it.
    • Before creating a histogram, check the directory to make sure that it hasn't already been created by another thread (if so, just grab the preexisting pointer from the directory rather than creating a duplicate histogram).

Execution

  • Each DAnalysisAction is executed by calling one of the function-call operators:
    • operator()(JEventLoop*) for DReaction-independent actions and operator()(JEventLoop*, deque<pair<const DParticleCombo*, bool> >&) for DReaction-dependent actions.
      • The deque contains the DParticleCombo objects that the DAnalysisAction should be executed on, and boolean flags that afterwards will indicate if the given DParticleCombo objects passed or failed the cuts performed by that action (if any: should return true if no cut).
    • The Perform_Action() function (see "Perform Action") is called on each of the input DParticleCombo objects (or just once if executed with operator()(JEventLoop*)).

Perform Action

  • The Perform_Action() function is called by the function-call operator and is used to execute the action on a given DParticleCombo. It returns true/false if the DParticleCombo passes/fails the action.
    • This function must be defined in each class deriving from DAnalysisAction, and should be declared as private.
  • The DParticleCombo objects that have already been acted upon by this action for this event can be retrieved with Get_PreviousParticleCombos(deque<pair<const DParticleCombo*, bool> >&). The boolean flags indicate whether they passed or failed the action.
  • Since each particle can be in several particle combinations, be careful about double-counting in your histograms. The best way to check this is to keep track of which particles you've used already and check against it. This can be done by comparing source objects and particle IDs for each particle between combos. For an example on how to do this, see how DHistogramAction_ParticleComboKinematics::dPreviouslyHistogrammedParticles is used in DHistogramAction.*
  • Filling ROOT Objects: In the Perform_Action() function, a JANA ROOT lock should be acquired before (japp->RootWriteLock()) and released after (japp->RootUnLock()) filling any ROOT TTree objects or histograms.
    • To reduce bottlenecks, the lock should be held for the minimum amount of time possible: perform all calculations prior to acquiring the lock, and release it immediately after filling everything.
    • To reduce overhead, try to acquire the lock only once per action if possible.