View source for 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. 
* <span style="color:#0000FF">DAnalysisAction</span> 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 <span style="color:#0000FF">DReaction</span> they will be executed sequentially by the <span style="color:#0000FF">DAnalysisResults_factory</span>.  
** Actions will be executed on a given <span style="color:#0000FF">DParticleCombo</span> object until it fails a cut, after which the remaining actions won't be executed on that object. 
* All analysis action objects inherit from <span style="color:#0000FF">DAnalysisAction</span>.
** 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 <span style="color:#0000FF">DReaction</span> or <span style="color:#0000FF">DParticleCombo</span> in any way.  
** These actions (should) have a default (<span style="color:#0000FF">void</span>) constructor, distinguishing them from reaction-dependent actions (which do not). 
* However, they can be added to <span style="color:#0000FF">DReaction</span> objects and executed in sequence with the other <span style="color:#0000FF">DAnalysisAction</span> objects. 
** This can be used to histogram reaction-independent quantities for events that satisfy cuts on your <span style="color:#0000FF">DReaction</span>. 
** 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:
** (<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Use this constructor if you want to add the action to a <span style="color:#0000FF">DReaction</span>. 
*** '''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. 
** (<span style="color:#0000FF">void</span>) and (<span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span>): Use these constructors when executing completely independently of any <span style="color:#0000FF">DReaction</span>. 

* The <span style="color:#008000">locActionUniqueString</span> is used to distinguish the histograms between different instances of the same action. 
** For example, you may wish to create two sets of <span style="color:#0000FF">DHistogramAction_DetectedParticleKinematics</span> histograms and have them filled under different scenarios.  
** <span style="color:#008000">locActionUniqueString</span> should only be left unspecified (== "") up to one time (per thread), and other instances should be assigned a unique, distinguishing string.   

* The function-call operator return-type is bool: unless improperly setup, it is the same bool as returned by the Perform_Action() function.  This allows access to the result from reaction-independent cuts.  This is only true for reaction-independent actions.  

* Example: 
<syntaxhighlight>
  //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);
</syntaxhighlight>

=== 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 &pi;<sup>+</sup>'s that decayed from K<sup>+</sup>'s)).  
** Note: For particle ID of the detected tracks, it uses the matching to the thrown tracks if available (from <span style="color:#0000FF">DMCThrownMatching</span>), and the PID FOM if not available.
** Note: You can histogram for different particle types by modifying the public <span style="color:#008000">dFinalStatePIDs</span> variable before calling the function-call operator. 
* '''DHistogramAction_ThrownParticleKinematics''': Histogram the kinematics of the thrown particles, including momentum, &theta;, &phi;, vertex position, and vertex time. 
** Note: You can histogram for different particle types by modifying the public <span style="color:#008000">dFinalStatePIDs</span> variable before calling the function-call operator. 
* '''DHistogramAction_DetectedParticleKinematics''': Histogram the kinematics of the detected particles, including momentum, &theta;, &phi;, vertex position, vertex time, &beta;, &Delta;&beta;, and tracking FOM. 
** Note: For particle ID, it uses the matching to the thrown tracks if available (from <span style="color:#0000FF">DMCThrownMatching</span>), and the PID FOM if not available.
** Note: You can histogram for different particle types by modifying the public <span style="color:#008000">dFinalStatePIDs</span> variable before calling the function-call operator. 
* '''DHistogramAction_GenReconTrackComparison''': Histogram the difference between the reconstructed and thrown track kinematics, including momentum, &theta;, &phi;, vertex position, and vertex time. 
** Note: You can histogram for different particle types by modifying the public <span style="color:#008000">dFinalStatePIDs</span> 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 <span style="color:#0000FF">DParticleCombo</span> objects. 
** They should be added to <span style="color:#0000FF">DReaction</span> and executed by <span style="color:#0000FF">DAnalysisResults_factory</span>'s. 
** All of the constructors for these actions (should) require a <span style="color:#0000FF">DReaction</span>* 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 <span style="color:#0000FF">DReaction</span>, by the <span style="color:#0000FF">DAnalysisResults_factory</span>'s.
** Actions will be executed on a given <span style="color:#0000FF">DParticleCombo</span> 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 &Lambda; invariant mass in &gamma;, p &rarr; K<sup>+</sup>, &Lambda;, multiple <span style="color:#0000FF">DParticleCombo</span> objects can have the same &Lambda; invariant mass but different particles for the photon or K<sup>+</sup>.  
** If <span style="color:#008000">locUseKinFitResultsFlag</span> = true/false, the kinematically-fit/measured data is used to fill the histograms. 
** The <span style="color:#008000">locActionUniqueString</span> is used to distinguish the histograms between different instances of the same action. 
*** For example, you may wish to create two sets of <span style="color:#0000FF">DHistogramAction_DetectedParticleKinematics</span> histograms and have them filled under different scenarios.  
*** <span style="color:#008000">locActionUniqueString</span> should only be left unspecified (== "") up to one time (per thread), and other instances should be assigned a unique, distinguishing string.   

* '''DHistogramAction_ParticleComboKinematics'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">bool</span> <span style="color:#008000">locUseKinFitResultsFlag</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Histogram the kinematics of the particles at each position in the DReaction, including momentum, &theta;, &phi;, vertex position, vertex time, &beta;, and &Delta;&beta;. 

* '''DHistogramAction_PID'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Histogram the PID information for the particles at each position in the DReaction, including the overall, TOF, and DC dE/dx FOM, &beta; and &Delta;&beta;, and the p vs. &theta; 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. &theta; 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: (<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = "") and (<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">Particle_t</span> <span style="color:#008000">locInitialPID</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMinMassSq</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMaxMassSq</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = "") (used for specifying the optional signal-mass region).

* '''DHistogramAction_TrackVertexComparison'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): 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 <span style="color:#0000FF">DReactionStep</span> objects. 
** Note: needs to be improved: uses crude DOCA determination (assumes no magnetic field).

* '''DHistogramAction_KinFitResults'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locPullHistConfidenceLevelCut</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Histogram the confidence level and pulls for of the kinematic fits.  The pulls are only histogrammed for <span style="color:#0000FF">DParticleCombo</span> objects with confidence level greater than the specified cut (recommended: 0.05).  

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

* '''DHistogramAction_MissingMass'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">bool</span> <span style="color:#008000">locUseKinFitResultsFlag</span>, <span style="color:#0000FF">unsigned int</span> <span style="color:#008000">locNumMassBins</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMinMass</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMaxMass</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Histogram the missing mass of the reaction, using the specified histogram binning. 

* '''DHistogramAction_MissingMassSquared'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">bool</span> <span style="color:#008000">locUseKinFitResultsFlag</span>, <span style="color:#0000FF">unsigned int</span> <span style="color:#008000">locNumMassBins</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMinMassSq</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMaxMassSq</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): 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'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">unsigned int</span> <span style="color:#008000">locMaxNumParticleCombos</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Cut all of the <span style="color:#0000FF">DParticleCombo</span> objects for an event if there are more than <span style="color:#008000">locMaxNumParticleCombos</span>. 

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

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

* '''DCutAction_TruePID'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">Particle_t</span> <span style="color:#008000">locTruePID</span>, <span style="color:#0000FF">Particle_t</span> <span style="color:#008000">locInitialPID</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Cut all <span style="color:#0000FF">DParticleCombo</span> objects for which the <span style="color:#0000FF">DReaction</span> particle(s) specified by <span style="color:#008000">locStepPID</span> and <span style="color:#008000">locTruePID</span> are mis-identified. 

* '''DCutAction_AllTruePID'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Cut all <span style="color:#0000FF">DParticleCombo</span> 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'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMinVertexZ</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMaxVertexZ</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Cut all <span style="color:#0000FF">DParticleCombo</span> objects for which one of the particles has a vertex-z (z-position of POCA to beamline) outside of the specified range. 

* '''DCutAction_MaxTrackDOCA'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">Particle_t</span> <span style="color:#008000">locInitialPID</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMaxTrackDOCA</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Cut all <span style="color:#0000FF">DParticleCombo</span> objects for which at least one pair of particles within the specified <span style="color:#0000FF">DReactionStep</span> have a distance-of-closest-approach greater than <span style="color:#008000">locMaxTrackDOCA</span>. 
** Note: needs to be improved: assumes that the particles at a given vertex cannot span several <span style="color:#0000FF">DReactionStep</span> objects. 
** Note: needs to be improved: uses crude DOCA determination (assumes no magnetic field).

* '''DCutAction_KinFitFOM'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMinimumConfidenceLevel</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Cut all <span style="color:#0000FF">DParticleCombo</span> objects for which the kinematic fit confidence level is not at least <span style="color:#008000">locMinimumConfidenceLevel</span>.  Also cuts all <span style="color:#0000FF">DParticleCombo</span> objects for which the kinematic fit failed to converge. 

* '''DCutAction_MissingMass'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">bool</span> <span style="color:#008000">locUseKinFitResultsFlag</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMinimumMissingMass</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMaximumMissingMass</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Cut all <span style="color:#0000FF">DParticleCombo</span> objects for which the missing mass is not within the specified range.  

* '''DCutAction_MissingMassSquared'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">bool</span> <span style="color:#008000">locUseKinFitResultsFlag</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMinimumMissingMassSq</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMaximumMissingMassSq</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Cut all <span style="color:#0000FF">DParticleCombo</span> objects for which the missing mass squared is not within the specified range.  

* '''DCutAction_InvariantMass'''(<span style="color:#0000FF">const DReaction</span>* <span style="color:#008000">locReaction</span>, <span style="color:#0000FF">Particle_t</span> <span style="color:#008000">locInitialPID</span>, <span style="color:#0000FF">bool</span> <span style="color:#008000">locUseKinFitResultsFlag</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMinimumInvariantMass</span>, <span style="color:#0000FF">double</span> <span style="color:#008000">locMaximumInvariantMass</span>, <span style="color:#0000FF">string</span> <span style="color:#008000">locActionUniqueString</span> = ""): Cut all <span style="color:#0000FF">DParticleCombo</span> objects for which the invariant mass of the decay products of the specified particle is not within the specified range.

== Details for writing DAnalysisActions ==
* See the built-in DHistogramActions and DCutActions for examples, as well as: [[Analysis_Examples | More Analysis Examples]]
* '''WARNING''': Outside of the constructor, ALL class member variables should ONLY be modified while within a <span style="color:#0000FF">DAnalysisAction</span>::<span style="color:#008000">Get_Application</span>()-><span style="color:#008000">RootWriteLock</span>().  This is because someone could create the action as a member of their plugin's processor, resulting in one object being shared by all threads.  
* '''WARNING''': If one action object is being shared by multiple threads, multiple threads may enter the <span style="color:#008000">Initialize</span>() 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.  

=== Construction ===
* Each class deriving from <span style="color:#0000FF">DAnalysisAction</span> should be designed so that no user input is required after calling the constructor.  
** For example, the constructor should contain the <span style="color:#0000FF">DReaction</span> 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-<span style="color:#0000FF">DReaction</span> 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 <span style="color:#0000FF">DAnalysisAction</span> constructor has been disabled (made private), so each constructor of each class deriving from <span style="color:#0000FF">DAnalysisAction</span> must explicitly call the <span style="color:#0000FF">DAnalysisAction</span> public constructor.  This is to enforce proper setup of each <span style="color:#0000FF">DAnalysisAction</span>.  
** Within a <span style="color:#0000FF">DReaction</span>, each <span style="color:#0000FF">DAnalysisAction</span> 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 <span style="color:#0000FF">DReaction</span> (e.g. make two different invariant mass histograms).

=== Execution ===
* Each <span style="color:#0000FF">DAnalysisAction</span> is executed by calling one of the function-call operators:
** <span style="color:#008000">operator()</span>(<span style="color:#0000FF">JEventLoop</span>*) for <span style="color:#0000FF">DReaction</span>-independent actions and <span style="color:#008000">operator()</span>(<span style="color:#0000FF">JEventLoop</span>*, deque<pair<const <span style="color:#0000FF">DParticleCombo</span>*, bool> >&) for <span style="color:#0000FF">DReaction</span>-dependent actions.  
*** The deque contains the <span style="color:#0000FF">DParticleCombo</span> objects that the <span style="color:#0000FF">DAnalysisAction</span> should be executed on, and boolean flags that afterwards will indicate if the given <span style="color:#0000FF">DParticleCombo</span> objects passed or failed the cuts performed by that action (if any: should return true if no cut).
** If the <span style="color:#0000FF">DAnalysisAction</span> has not yet been initialized, the function-call operator will first call the <span style="color:#008000">Initialize</span>() function (see "Initialization"). 
** The <span style="color:#008000">Perform_Action</span>() function (see "Perform Action") is called on each of the input <span style="color:#0000FF">DParticleCombo</span> objects (or just once if executed with <span style="color:#008000">operator()</span>(<span style="color:#0000FF">JEventLoop</span>*)).

=== Initialization ===
* The <span style="color:#008000">Initialize</span>() function is called by the function-call operator and is used to create histograms, <span style="color:#0000FF">TTree</span> objects, setup cuts, or any other operations that are needed to prepare the object for performing the desired action. 
** This function must be defined in each class deriving from <span style="color:#0000FF">DAnalysisAction</span>, and should be declared as private. 

* '''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 (<span style="color:#0000FF">DAnalysisAction</span>::<span style="color:#008000">Get_Application</span>()-><span style="color:#008000">RootWriteLock</span>()) and after (<span style="color:#0000FF">DAnalysisAction</span>::<span style="color:#008000">Get_Application</span>()-><span style="color:#008000">RootUnLock</span>()) 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 <span style="color:#0000FF">DAnalysisAction</span>::<span style="color:#008000">CreateAndChangeTo_ActionDirectory</span>() to create and change-to a directory that is unique to this analysis action (but NOT to this <span style="color:#0000FF">DAnalysisAction</span> (important multi-threading distinction!: each thread will have it's own unique instance of the <span style="color:#0000FF">DAnalysisAction</span> 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 <span style="color:#0000FF">DReaction</span> needs to have a unique name, and each <span style="color:#0000FF">DAnalysisAction</span> within a given <span style="color:#0000FF">DReaction</span> needs to have a unique name.  
*** Call <span style="color:#0000FF">DAnalysisAction</span>::<span style="color:#008000">CreateAndChangeTo_Directory</span>() 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). 

=== Perform Action ===

* The <span style="color:#008000">Perform_Action()</span> function is called by the function-call operator and is used to execute the action on a given <span style="color:#0000FF">DParticleCombo</span>.  It returns true/false if the <span style="color:#0000FF">DParticleCombo</span> passes/fails the action. 
** This function must be defined in each class deriving from <span style="color:#0000FF">DAnalysisAction</span>, and should be declared as private.

* The <span style="color:#0000FF">DParticleCombo</span> objects that have already been acted upon by this action for this event can be retrieved with <span style="color:#008000">Get_PreviousParticleCombos</span>(deque<pair<const <span style="color:#0000FF">DParticleCombo</span>*, bool> >&).  The boolean flags indicate whether they passed or failed the action. 
** The previous combos can be used (for example) to determine whether or not the quantities to be histogrammed are identical to those from a previous <span style="color:#0000FF">DParticleCombo</span> and should be skipped to prevent double-counting (e.g. when histogramming the momentum of K<sup>+</sup> candidates, two different <span style="color:#0000FF">DParticleCombo</span> objects can have the same track used as the K<sup>+</sup> candidate (but be unique otherwise)). 
*** There are methods in <span style="color:#0000FF">DAnalysisUtilities</span> (via <span style="color:#008000">Get_AnalysisUtilities()</span>) that can be used to help identify when double-counting is about to happen.  

* '''Filling ROOT Objects''': In the <span style="color:#008000">Perform_Action</span>() function, a JANA ROOT lock should be acquired before (<span style="color:#0000FF">DAnalysisAction</span>::<span style="color:#008000">Get_Application</span>()-><span style="color:#008000">RootWriteLock</span>()) and released after (<span style="color:#0000FF">DAnalysisAction</span>::<span style="color:#008000">Get_Application</span>()-><span style="color:#008000">RootUnLock</span>()) filling any ROOT <span style="color:#0000FF">TTree</span> 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.