Tests and Cuts¶

Controlling data analysis flow with cuts¶

To define tests/cuts to be evaluated at each stage of the analysis, test definitions are placed in a plain-text input file, the "cut definition file". The file name must be given to the analyzer via a call to SetCutFile(). Example:

analyzer [24] THaAnalyzer* analyzer = new THaAnalyzer;
analyzer [25] analyzer->SetCutFile("demo.cuts")

The format of the file is illustrated in the following example:

# Demo cut definition file demo.cuts
#
Block: RawDecode

evtyp1            g.evtyp==1          // Event type 1 (=HRSR main trigger)
poshel            g.helicity==1
neghel            g.helicity==-1
goodhel           poshel||neghel
RawDecode_master  evtyp1

Block: Decode

NoisyU1           R.vdc.u1.nhit>50
NoisyV1           R.vdc.v1.nhit>50
NoisyU2           R.vdc.u2.nhit>50
NoisyV2           R.vdc.v2.nhit>50
NoisyVDC          NoisyU1||NoisyV1||NoisyU2||NoisyV2
EnoughShowerHits  R.sh.nhit>10
Decode_master     !NoisyVDC

If a test with the name "blockname"_master is defined (example "Decode_master"), then if this test is false for a given event, further analysis of that event will be skipped.

A summary of the test results is printed to the screen at the end of the analysis. A copy of the printout ("cut summary") can be written to a file if the name of the file is set via a call to SetSummaryFile() before starting the analysis.

See the "examples" directory and the Quickstart Guide for more examples.

Notes on the format of the definition file:

• Comments start with "#" or "//". Inline comments are allowed. Empty lines (all whitespace) are ignored.
• Blocks of tests are introduced with a line containing "Block: name". The block names must correspond to the predefined names of the analysis stages. Each block will be evaluated at the end of the respective stage. The following stages are defined in the standard analyzer THaAnalyzer:
  • "RawDecode": After THaEvData::LoadEvent().
  • "Decode": After Decode() of all detectors in all apparatuses.
  • "CoarseTracking": After CoarseTrack() of all detectors of all apparatuses.
  • "CoarseReconstruct": After CoarseProcess() of all detectors of all apparatuses.
  • "Tracking": After FineTrack() of all detectors of all apparatuses.
  • "Reconstruct": After FineProcess() of all detectors of all apparatuses.
  • "Physics": After Process() of all physics modules, i.e. right before writing the output.
• Test definitions start with the name of the test (which may not contain any whitespace) followed by the definition separated by whitespace. Unlike the name, the definition may contain arbitrary whitespace. Test names must be unique.
• The length of the block name, test name, and test definition strings is limited to 255 characters each.
• Tests will be defined exactly in the order in which they appear in the file. Within each block, tests will be evaluated exactly in the order in which they are defined. The blocks will be evaluated in the order the analysis stages occur.
• At present, the program does not check whether variables used in a certain test block are actually valid when the block is evaluated. The user must ensure that his/her test definitions make sense. For instance, variables filled by Physics Modules, such as "R.gold.dp", will not be valid in any test block other than "Physics". In particular they will be invalid (usually = 1e38) in the "Reconstruct" test block.

See also THaCutList::Load().

Using tests as conditions in THaOutput¶

Tests defined in the cut definition file as well as separately-defined tests can be used as conditions for filling histograms. For details, please see the documentation of THaOutput.

Programming documentation¶

Technical details about the test/cut classes and how to use them directly can be found the test/cut programming documentation.