Difference between revisions of "Analysis Actions"

From GlueXWiki
Jump to: navigation, search
(Warnings on Creating Reaction-Independent Actions)
(Details for writing DAnalysisActions)
 
Line 72: Line 72:
 
** 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.
 
** 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.
 
* '''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 <span style="color:#0000FF">DReaction_factory</span>) are fine.  Objects that are members of your plugin's processor are not.  This will cause race-condition issues between threads.
 
* '''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 <span style="color:#0000FF">DReaction_factory</span>) are fine.  Objects that are members of your plugin's processor are not.  This will cause race-condition issues between threads.
 
== Details for writing DAnalysisActions ==
 
* See the built-in DHistogramActions and DCutActions for examples, as well as: [[Analysis_Examples | More Analysis Examples]]
 
* The <span style="color:#0000FF">MakeAnalysisAction.pl</span> perl script (it is installed to $PATH) can be used to create template code for a new, custom action.
 
** Run it with no arguments for instructions.
 
 
=== 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).
 
 
=== Initialization ===
 
* The <span style="color:#008000">Initialize</span>() function 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 needs to be executed manually by the user if the <span style="color:#0000FF">DAnalysisAction</span> is not added to the <span style="color:#0000FF">DReaction</span>.
 
** This function must be defined in each class deriving from <span style="color:#0000FF">DAnalysisAction</span>, 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 (<span style="color:#008000">japp</span>-><span style="color:#008000">RootWriteLock</span>()) and after (<span style="color:#008000">japp</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).
 
 
=== 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).
 
** 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>*)).
 
 
=== 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.
 
 
* 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 <span style="color:#0000FF">DHistogramAction_ParticleComboKinematics</span>::<span style="color:#008000">dPreviouslyHistogrammedParticles</span> is used in DHistogramAction.*
 
 
* '''Filling ROOT Objects''': In the <span style="color:#008000">Perform_Action</span>() function, a JANA ROOT lock should be acquired before (<span style="color:#008000">japp</span>-><span style="color:#008000">RootWriteLock</span>()) and released after (<span style="color:#008000">japp</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.
 

Latest revision as of 07:48, 3 November 2017

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 (it is installed to $PATH) can be used to create template code for a new, custom action.
    • Run it with no arguments for instructions.
  • 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);

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.