GlueX Analysis Software

Documentation Notice

This documentation is updated as code is checked into the svn trunk, so it may contain information that is untrue for the latest tagged release.

In his/her plugin, a user specifies the reaction(s) he/she wants to study (DReaction), along with the histograms and cuts to perform (if any) (DAnalysisAction), then just asks JANA for the results (DAnalysisResults).
These results can then be saved to a ROOT TTree (DEventWriterROOT), or can be used to make a REST skim (DEventWriterREST).
Through this process, the program creates all possible track combinations for the desired reaction (DParticleCombo, tag "PreKinFit"), kinematic fits the event to the reaction (DKinFitResults), and updates the tracks with the new kinfit information (DParticleCombo, no tag).
The DAnalysisAction objects encapsulate the setup and execution of an action (e.g. cut, histogram) into a single object.
- Many common actions are predefined in DANA (see libraries/ANALYSIS/DHistogramActions.h and libraries/ANALYSIS/DCutActions.h), but the user can write custom ones for their analysis in their plugin.
The DAnalysisResults objects indicate which DParticleCombo objects have passed/failed the DAnalysisAction cuts for each DReaction.

Use the MakeReactionPlugin.pl perl script to create a new plugin for your analysis.
- Execute the script with no arguments for usage instructions. A minimum of one argument is required (the plugin name).
- It is recommended that you run the script with unique names as the arguments. That way this plugin can be executed with other analysis plugins simultaneously.

Use the MakeAnalysisAction.pl perl script to create any desired custom DAnalysisAction objects for your analysis.
- See existing analysis actions in sim-recon/src/libraries/ANALYSIS/DHistogramActions.h and sim-recon/src/libraries/ANALYSIS/DCutActions.h for examples.

In DReaction_factory::init(void), create a DReaction object (with a unique name!) for each analysis you want to perform, specify the kinematic fit type for it, specify the DAnalysisActions for each, and add them to _data.
- The DAnalysisAction objects are executed sequentially for each possible particle combination (DParticleCombo) matching the given DReaction, until it fails a cut.
- If more than one DAnalysisAction object of a given type is used in a DReaction, all of their constructors must be called with a unique identifier string (including the default "").
- More details on analysis actions in sim-recon/src/libraries/ANALYSIS/: DAnalysisAction.*, DHistogramActions.*, DCutActions.*

No uncertainties are reported for the DTOFPoint object. It needs a full covariance matrix.
For DBCALShower and DFCALShower: only the diagonal elements of the covariance matrices are reported; the full covariance matrix is needed.
For DFCALShower: the position uncertainty in z is often way too large, causing a spike in its pull distribution when kinematic fitting.
Sometimes the neutral shower variances are 0 and NaN.

Kinematic fitting with vertex constraints that contain only one detected particle do not converge very often.
- e.g. The Λ production vertex in γ, p → K⁺, Λ; Λ → p, π^-
  - Normally can include the beam photon in the vertex fit, but not if the uncertainties are all zero (MC).
- Technically the kinematic fitter works, but the analysis framework currently does not give an accurate enough initial guess for the vertex position. You can fit this case manually if your input guess is accurate enough.
Kinematic fits with spacetime constraints don't work yet.
Neutron reconstruction is not yet supported.
Missing beam particle is not yet supported.

For PID, hard-coded values are used for the uncertainties, rather than the covariance matrices.
The target center is hard-coded as the position of the DBeamPhoton in DEventSourceHDDM.cc, and in the DMCReaction contents in both event sources.
Pulls of neutral shower parameters in b1pi are too wide (~1.3)
PID Confidence levels for the BCAL and FCAL(?) systems are too high.
Covariance matrix of decaying particles is not set after kinematic fitting.
The DParticleComboStep::dSpacetimeVertex member is set to the target center & t=0 if it is not kinematically fit (and this is reflected in the ROOT output as well).
Generated / Detected object matching is not ideal:
- A FOM is used to determine the best match, but there is no minimum FOM: if the true track was not reconstructed, you may match the thrown track to a reconstructed ghost track.
- The FOM calculation is rough but adequate: it could be improved.
- The matching between true and reconstructed BCAL & FCAL showers has not been tested.
ROOT TTree Output:
- Reconstructed (non-kinfit) locations/times of each vertex are bad.
Resonances decayed in genr8 are not saved to the genr8 output, so they don't appear in JANA.