Difference between revisions of "ReactionFilter"

From GlueXWiki
Jump to: navigation, search
(Combos)
(Kinematic Fitter)
 
(24 intermediate revisions by 4 users not shown)
Line 2: Line 2:
 
The basic concept of the ReactionFilter Plugin is to use a defined physics reaction, usually described in a configuration file, to analyze the reconstructed data (REST files) event by event testing the hypothesis of the proposed reaction. It creates an output root file referred to as  [https://halldweb.jlab.org/wiki/index.php/Analysis_TTreeFormat '''''Physics Analysis Root Tree''''' ('''PART''')] which in turn will be analyzed by other code like the DSelector.
 
The basic concept of the ReactionFilter Plugin is to use a defined physics reaction, usually described in a configuration file, to analyze the reconstructed data (REST files) event by event testing the hypothesis of the proposed reaction. It creates an output root file referred to as  [https://halldweb.jlab.org/wiki/index.php/Analysis_TTreeFormat '''''Physics Analysis Root Tree''''' ('''PART''')] which in turn will be analyzed by other code like the DSelector.
  
The plugin applies [https://halldweb.jlab.org/wiki/index.php/Spring_2017_Analysis_Launch_Cuts '''''basic PID selection criteria (time, mass, and dEdx)'''''] and by default a [https://halldweb.jlab.org/wiki/index.php/Kinematic_Fitting '''''Kinematic Fitter'''''] to the reconstructed charged track and/or neutral showers of each event and applies the '''Kinematic Fitter''' based on the chosen reaction requirements.
+
The plugin applies [https://halldweb.jlab.org/wiki/index.php/Spring_2017_Analysis_Launch_Cuts '''''basic PID selection criteria (time, mass, and dEdx)'''''] and by default a [https://halldweb.jlab.org/wiki/index.php/Mattione_GlueX_Kinematic_Fitting '''''Kinematic Fitter'''''] to the reconstructed charged track and/or neutral showers of each event and applies the '''Kinematic Fitter''' based on the chosen reaction requirements.
  
 
== Plugin ==
 
== Plugin ==
The ReactionFilter plugin is located in [https://github.com/JeffersonLab/halld_recon/tree/master/src/plugins/Analysis/ReactionFilter '''''ReactionFilter plugin on github '''''] and depends heavily on the [https://github.com/JeffersonLab/halld_recon/tree/master/src/libraries/ANALYSIS '''''Analysis Library'''''] all part of the [https://github.com/JeffersonLab/halld_recon '''''halld_recon package'''''].
+
The ReactionFilter plugin is located in [https://github.com/JeffersonLab/halld_recon/tree/master/src/plugins/Analysis/ReactionFilter '''''ReactionFilter plugin on github '''''] and depends heavily on the [https://github.com/JeffersonLab/halld_recon/tree/master/src/libraries/ANALYSIS '''''Analysis Library'''''] all of which are part of the [https://github.com/JeffersonLab/halld_recon '''''halld_recon package'''''].
  
While the analyzers will usually not need to run this plugin by themselves, since this is generally done by the responsible operator running an analysis launch with all requested reactions from all analyzers at once, it is useful for any analyzer to understand the concept of the ReactionFilter plugin and its functionality, also in view of the fact that the analyzer is responsible to provide the definition of the reaction to the operator of the analysis launch.
+
While the analyzers will usually not need to run this plugin by themselves, since this is generally done by the responsible operator who runs an analysis launch with all requested reactions from all analyzers at once for the sake of efficient use of computing resources.  However, it is useful for any analyzer to understand the concept of the ReactionFilter plugin and its functionality, particularly since an analyzer needs to to provide the definition of the reaction to the operator of the analysis launch.
  
* An introduction to the '''ReactionFilter''' plugin can be found in this [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=3407 '''''DocDB document'''''] (at presentation) and some information on the wiki in [[Analysis DReaction | '''''Analysis DReaction''''']]. Note that most of this documentation is 5 years old and no updates have been made since then.
+
* An introduction to the use of the '''ReactionFilter''' plugin can be found in this [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=3407 '''''DocDB document'''''] (at presentation). Its code is based on information that can be found in [[Analysis DReaction | '''''Analysis DReaction''''']]. This latter link also serves as a guide to write your '''own''' ''analysis reaction plugin'' if so desired or needed.
* Examples of how such a configuration files may look like, examine the online submission form: [https://halldweb.jlab.org/analysis/SubmitReaction.html '''''Create a Reaction Config File''''']
+
* The use of the Reaction Filter requires the definition of a reaction. For examples of reaction definitions and an easy form to define them, examine the online submission form: [https://halldweb.jlab.org/analysis/SubmitReaction.html '''''Create a Reaction Config File''''']
 
** [[The particle selection criteria can be changed in the configuration file.]]
 
** [[The particle selection criteria can be changed in the configuration file.]]
 
** [[Selection criteria can be applied to the reaction considered in the configuration file.]]
 
** [[Selection criteria can be applied to the reaction considered in the configuration file.]]
 
** The [[Kinematic fit constraints]] can be changed  in the configuration file or the kinematic fit can also not be used at all.
 
** The [[Kinematic fit constraints]] can be changed  in the configuration file or the kinematic fit can also not be used at all.
* '''''Important:''''' Generally an analysis reaction is submitted to the global analysis system administrator, by the above link, who will run the reaction over the specified data set for all submitted reactions in one go. So the user will be provided with the resulting '''PART''' files. These files will have the specified reaction in their file name.
+
* '''''Important:''''' Generally an analysis reaction request is submitted to the global analysis system administrator using the above link, who will run the reaction over the specified data set for all submitted reactions in one go. So the user will be provided with the resulting '''PART''' files. These files will have the specified reaction in their file name.
 
* This step by the administrator is called an '''Analysis Launch''' and details can be found here: [https://halldweb.jlab.org/data_monitoring/launch_analysis/index.html '''''Analysis Launch and Monitoring''''']
 
* This step by the administrator is called an '''Analysis Launch''' and details can be found here: [https://halldweb.jlab.org/data_monitoring/launch_analysis/index.html '''''Analysis Launch and Monitoring''''']
* The output data ('''PART''') will be located on the cache disk system of the jlab computing system. An example of such a location is ''/cache/halld/RunPeriod-2018-01/analysis/ver19/''. The data is discriminated by '''Run-Period''' and '''version''' the latter referring to the software version begin used.
+
* The output data ('''PART''') will be located on the cache disk system of the jlab computing system. An example of such a location is ''/cache/halld/RunPeriod-2018-01/analysis/ver19/''. This file system is backed by tape storage - if the PART files are not on the cache disks, they may have been retrieved from tape.  The data is discriminated by '''Run-Period''' and '''version''' the latter referring to the number of the analysis launch that was performed.  Note that each launch usually uses the latest version of the analysis software.
 
+
  
 
== Reaction Definition ==
 
== Reaction Definition ==
Line 25: Line 24:
 
Reaction1:Flags B2_T1_S1_M7_M17
 
Reaction1:Flags B2_T1_S1_M7_M17
 
</pre>
 
</pre>
* The first line "Reaction1" defines the reaction in this case reaction number 1. The first part before the "__" represents the initial state, in this case 1(gamma) on 14(proton target). The second part (after "__") represents the final state, in this case 7(pi0), 8(pi+), 9(pi-), 17(eta) and 14(proton). The number coding of the particles is defined in [https://github.com/JeffersonLab/halld_recon/blob/master/src/libraries/include/particleType.h particleType.h].
+
* The first line "Reaction1" defines the reaction in this case reaction number 1. The first part before the "__" represents the initial state, in this case 1(&gamma;) on 14(proton target). The second part (after "__") represents the final state, in this case 7(&pi;<sup>0</sup>), 8(&pi;<sup>+</sup>), 9(&pi;<sup>-</sup>), 17(&eta;) and 14(proton). The number coding of the particles is defined in [https://github.com/JeffersonLab/halld_recon/blob/master/src/libraries/include/particleType.h particleType.h].
 +
* If a particle is assumed but not detected, it can be specified with 'm' (e.g. a missing pi0 is m7). A missing 'unknown' particle m0 can be used for fully inclusive reactions. The missing particle type is used for the loose missing mass cuts and kinematic fit constraints applied in the analysis library.
 
* The second line "Reaction1:Flags" defines the flags associated with this reaction.
 
* The second line "Reaction1:Flags" defines the flags associated with this reaction.
** B2 : include beam photons from two beam bunches on either side of the prompt peak
+
** B2 : include beam photons from two beam bunches on either side of the prompt peak (default B1)
** T1 : include events with one additional reconstructed charged track if present.
+
** T1 : exclude events with more than one additional reconstructed charged track (default T3)
** S1 : include events with on additional reconstructed shower if present.
+
** S0 : exclude events with any additional showers in time with the reconstructed reaction (events with time pileup are excluded)
** M7 : do NOT constrain the pi0 mass in the kinematic fit
+
** S1 : exclude events with more than one additional reconstructed shower in time the reconstructed reaction (default 999 and events with time pileup are not excluded)
** M17: do NOT constrain the eta mass in the kinematic fit
+
** M7 : do NOT constrain the &pi;<sup>0</sup> mass in the kinematic fit
 +
** M17: do NOT constrain the &eta; mass in the kinematic fit
 
* Other Flags are:
 
* Other Flags are:
** F# : Kinematic Fit type; 1, 2, 3, 4(default), 5
+
** F# : Kinematic Fit type; 0 (none), 1, 2, 3, 4 (default).  For the definitions of these numbers, see the "Kinematic Fitter" section below.
** U# : Number of unused Hypotheses to be saved in the output root tree file (will increase output root file!)
+
** U1 : Save all unused particles in the output root tree file (will increase output root file size!)
* By default a pi0 will decay into two photons and similarly the eta. A full list of default decay channels of various particles can be found in the code of the [https://github.com/JeffersonLab/halld_recon/blob/master/src/plugins/Analysis/ReactionFilter/DReaction_factory_ReactionFilter.cc ''''' Reaction Filter Factory'''''] (line #34).
+
* By default a &pi;<sup>0</sup> will decay into two photons and similarly the &eta;. A full list of default decay channels of various particles can be found in the code of the [https://github.com/JeffersonLab/halld_recon/blob/master/src/plugins/Analysis/ReactionFilter/DReaction_factory_ReactionFilter.cc ''''' Reaction Filter Factory'''''] (line #34).
* Explicit decay modes can be specified for particles. For example, requesting the eta to decay into pi0, pi+, pi-:
+
* Explicit decay modes can be specified for particles. For example, requesting the &eta; to decay into &pi;<sup>0</sup>, &pi;<sup>+</sup>, &pi;<sup>-</sup>:
 
** <pre>Reaction1:Decay1 17__7_8_9</pre>
 
** <pre>Reaction1:Decay1 17__7_8_9</pre>
 
** The "1" at the end of "Decay" is a counter, this allows for more than one Decay definition in a reaction.
 
** The "1" at the end of "Decay" is a counter, this allows for more than one Decay definition in a reaction.
** All particles of the same type (in a reaction) will decay into the same channel. So if there would be two etas in the reaction both would be treated to decay into the same channel.
+
** All particles of the same type (in a reaction) will decay into the same channel. So if there would be two etas in the reaction both would be reconstructed in their decay into the same channel.
  
 
== Combos ==
 
== Combos ==
This section shortly touches the concept of what a '''Combo''' is. Each event has a certain number of reconstructed charged particle tracks and neutral particle showers based on the data recorded in the GlueX detector. The combination of these particles form the final state. In addition the data from the tagger detectors provide reconstructed beam photons representing options for the initial state. For each event the Reaction Filter will test all possible combinations of initial and final state reconstructed particles that match the defined reaction and uses the kinematic fitter to apply energy and momentum conservation criteria as well as other criteria like timing to test the validity of each such combination called '''Combo'''.
+
This section shortly touches on the concept of what a '''Combo''' is. Each event has a certain number of reconstructed charged particle tracks and neutral particle showers based on the data recorded in the GlueX detector. The combination of these particles form the final state. In addition the data from the tagger detectors provide reconstructed beam photons representing options for the initial state. For each event the Reaction Filter will test all possible combinations of initial and final state reconstructed particles that match the defined reaction.  We call these combinations '''Combos'''.  The Reaction Filter, through the standard reconstruction and analysis code, also applies loose quality and particle identification criteria on the final state particles and uses the kinematic fitter to apply energy and momentum conservation criteria.
  
Any combination with which the kinematic fitter does converge will be saved to the output tree together with the results from the kinematic fitter.
+
Any combos that passes these selections and has a converged kinematic fit will be saved to the output tree together with the results from the kinematic fitter.
  
 
== Kinematic Fitter ==
 
== Kinematic Fitter ==
 +
 +
Kinematic fitting is a mathematical procedure in which one uses the physical laws governing a particle interaction or decay to improve the measurements of the process. A kinematic fit to experimental data can set constraints on four-momentum conservation, decaying particle invariant mass, and common particle vertices, and improve the measured particle 4-vectors using a fit including these constraints. All of these constraints can be applied simultaneously for any, arbitrarily complex, physics reaction. Both detected and decaying particles can be used to constrain common vertices. In constrained-vertex fits, the measured paths of charged particles are used to constrain the event vertex(vertices), while the photons 4-vectors are updated based on the common vertex from the fit and the measured calorimeter showers. The uncertainty of all measurements is taken into account via covariance matrices.
 +
 +
In the ReactionFilter plugin, 4 different settings are commonly used:
 +
# F0: no kinematic fit is applied, only the measured quantities for the particles are saved
 +
# F1: 4-Momentum constraints, which includes momentum and energy conservation between initial and final state and invariant mass constraints for narrow resonances (&pi;<sup>0</sup>, &eta;, &Lambda;, ...)
 +
# F2: Vertex constraints, which takes into account primary and all secondary vertices from long-lived decaying particles
 +
# F4: 4-Momentum and Vertex contraints '''(default)'''
 +
 +
For FX and X>0, by default, only events with a converged fit are saved. To save events when the fit is not converging this option should be added: ANALYSIS:KINFIT_CONVERGENCE 0. There are more options, but they are not properly tested. Detailed information about the implementation can be found in [https://halldweb.jlab.org/doc-private/DocDB/ShowDocument?docid=2112 GlueX-doc-2112].

Latest revision as of 18:19, 14 April 2022

Purpose

The basic concept of the ReactionFilter Plugin is to use a defined physics reaction, usually described in a configuration file, to analyze the reconstructed data (REST files) event by event testing the hypothesis of the proposed reaction. It creates an output root file referred to as Physics Analysis Root Tree (PART) which in turn will be analyzed by other code like the DSelector.

The plugin applies basic PID selection criteria (time, mass, and dEdx) and by default a Kinematic Fitter to the reconstructed charged track and/or neutral showers of each event and applies the Kinematic Fitter based on the chosen reaction requirements.

Plugin

The ReactionFilter plugin is located in ReactionFilter plugin on github and depends heavily on the Analysis Library all of which are part of the halld_recon package.

While the analyzers will usually not need to run this plugin by themselves, since this is generally done by the responsible operator who runs an analysis launch with all requested reactions from all analyzers at once for the sake of efficient use of computing resources. However, it is useful for any analyzer to understand the concept of the ReactionFilter plugin and its functionality, particularly since an analyzer needs to to provide the definition of the reaction to the operator of the analysis launch.

  • An introduction to the use of the ReactionFilter plugin can be found in this DocDB document (at presentation). Its code is based on information that can be found in Analysis DReaction. This latter link also serves as a guide to write your own analysis reaction plugin if so desired or needed.
  • The use of the Reaction Filter requires the definition of a reaction. For examples of reaction definitions and an easy form to define them, examine the online submission form: Create a Reaction Config File
  • Important: Generally an analysis reaction request is submitted to the global analysis system administrator using the above link, who will run the reaction over the specified data set for all submitted reactions in one go. So the user will be provided with the resulting PART files. These files will have the specified reaction in their file name.
  • This step by the administrator is called an Analysis Launch and details can be found here: Analysis Launch and Monitoring
  • The output data (PART) will be located on the cache disk system of the jlab computing system. An example of such a location is /cache/halld/RunPeriod-2018-01/analysis/ver19/. This file system is backed by tape storage - if the PART files are not on the cache disks, they may have been retrieved from tape. The data is discriminated by Run-Period and version the latter referring to the number of the analysis launch that was performed. Note that each launch usually uses the latest version of the analysis software.

Reaction Definition

The definition of a reaction in a configuration file will look something like this:

Reaction1 1_14__7_8_9_17_14
Reaction1:Flags B2_T1_S1_M7_M17
  • The first line "Reaction1" defines the reaction in this case reaction number 1. The first part before the "__" represents the initial state, in this case 1(γ) on 14(proton target). The second part (after "__") represents the final state, in this case 7(π0), 8(π+), 9(π-), 17(η) and 14(proton). The number coding of the particles is defined in particleType.h.
  • If a particle is assumed but not detected, it can be specified with 'm' (e.g. a missing pi0 is m7). A missing 'unknown' particle m0 can be used for fully inclusive reactions. The missing particle type is used for the loose missing mass cuts and kinematic fit constraints applied in the analysis library.
  • The second line "Reaction1:Flags" defines the flags associated with this reaction.
    • B2 : include beam photons from two beam bunches on either side of the prompt peak (default B1)
    • T1 : exclude events with more than one additional reconstructed charged track (default T3)
    • S0 : exclude events with any additional showers in time with the reconstructed reaction (events with time pileup are excluded)
    • S1 : exclude events with more than one additional reconstructed shower in time the reconstructed reaction (default 999 and events with time pileup are not excluded)
    • M7 : do NOT constrain the π0 mass in the kinematic fit
    • M17: do NOT constrain the η mass in the kinematic fit
  • Other Flags are:
    • F# : Kinematic Fit type; 0 (none), 1, 2, 3, 4 (default). For the definitions of these numbers, see the "Kinematic Fitter" section below.
    • U1 : Save all unused particles in the output root tree file (will increase output root file size!)
  • By default a π0 will decay into two photons and similarly the η. A full list of default decay channels of various particles can be found in the code of the Reaction Filter Factory (line #34).
  • Explicit decay modes can be specified for particles. For example, requesting the η to decay into π0, π+, π-:
    • Reaction1:Decay1 17__7_8_9
    • The "1" at the end of "Decay" is a counter, this allows for more than one Decay definition in a reaction.
    • All particles of the same type (in a reaction) will decay into the same channel. So if there would be two etas in the reaction both would be reconstructed in their decay into the same channel.

Combos

This section shortly touches on the concept of what a Combo is. Each event has a certain number of reconstructed charged particle tracks and neutral particle showers based on the data recorded in the GlueX detector. The combination of these particles form the final state. In addition the data from the tagger detectors provide reconstructed beam photons representing options for the initial state. For each event the Reaction Filter will test all possible combinations of initial and final state reconstructed particles that match the defined reaction. We call these combinations Combos. The Reaction Filter, through the standard reconstruction and analysis code, also applies loose quality and particle identification criteria on the final state particles and uses the kinematic fitter to apply energy and momentum conservation criteria.

Any combos that passes these selections and has a converged kinematic fit will be saved to the output tree together with the results from the kinematic fitter.

Kinematic Fitter

Kinematic fitting is a mathematical procedure in which one uses the physical laws governing a particle interaction or decay to improve the measurements of the process. A kinematic fit to experimental data can set constraints on four-momentum conservation, decaying particle invariant mass, and common particle vertices, and improve the measured particle 4-vectors using a fit including these constraints. All of these constraints can be applied simultaneously for any, arbitrarily complex, physics reaction. Both detected and decaying particles can be used to constrain common vertices. In constrained-vertex fits, the measured paths of charged particles are used to constrain the event vertex(vertices), while the photons 4-vectors are updated based on the common vertex from the fit and the measured calorimeter showers. The uncertainty of all measurements is taken into account via covariance matrices.

In the ReactionFilter plugin, 4 different settings are commonly used:

  1. F0: no kinematic fit is applied, only the measured quantities for the particles are saved
  2. F1: 4-Momentum constraints, which includes momentum and energy conservation between initial and final state and invariant mass constraints for narrow resonances (π0, η, Λ, ...)
  3. F2: Vertex constraints, which takes into account primary and all secondary vertices from long-lived decaying particles
  4. F4: 4-Momentum and Vertex contraints (default)

For FX and X>0, by default, only events with a converged fit are saved. To save events when the fit is not converging this option should be added: ANALYSIS:KINFIT_CONVERGENCE 0. There are more options, but they are not properly tested. Detailed information about the implementation can be found in GlueX-doc-2112.