Programmable Tests: The FLTR Bank

The filter request banks (FLTR) work in almost exactly the same way as ntuple requests (NTPRs) as demonstrated by the following example:-

*DO   FLTR  200  -i(35I 1F 3I -H)             #. FLTR: Big event inside 4m
#.
#.    Standard Database Header
#.
19750101    0 20380516  223319  #.  1..4  Intrinsic validity
       0    0        0          #.  5..7  Data type, Task type, Format no.
       0    0        0          #.  8..10 Creation Date, Time, Source Id.
19750101    0 20380516  223319  #. 11..14 Effective validity
       0    0                   #. 15..16 Entry Date Time
4*0                             #. 17..20 Spare
10*0                            #. 21..30 Temporary data (not in database)
#.
#.    User Data
#.
3*0                     #.   3 Reserved words (don't touch!).
0                       #.   Enable flag: =0 Disable, =1 Enable.
5000                    #.   Primary allocation (not critical).
-999999.                #.   "Undefined" value.
1                       #.   Discard partial entry: =0 No, =1 Yes.
0                       #.   Scan D/S: =0 No, =1 AND scan, = 2 OR scan.
0                       #.   Call NTP_PACK_USER: =0 No, =1 Yes
'fltdata; '             #.   Ntuple name.
#.
#.    There now comes the FLTR test definition. The test is true if the
#.    last variable has a non-zero value.
#.
#.    Variable   Function        Parameter(s)
#.    Name
#.
'     nhits      float_equals    EV+$KEV_NPM;            '
'     rfit       magnitude       FTTV+$KFTXV_X;          '
'     nhit_cut   gt              nhits,50.;              '
'     r_cut      lt              rfit,400.;              '
'     test       and             nhit_cut, r_cut;        '
#.
'  END_OF_NTUPLE; '     #.  This marks the end of the ntuple.

The lines above would appear in a titles file (loaded into SNOMAN with the command titles filename). Test 200 is defined, which checks for greater than 50 hits and a fitted vertex inside 4m. Bank numbers above 100 are free to be used for new tests (the special set of banks 1-99 are discussed in the next section). The layout follows that of an ntuple request (see section 6.1) with a database header, a set of control words and then a series of text fields delimited by semi-colons. In this last section, filter variables are defined in terms of derived quantity functions (DQFs) acting on a set of parameters (datastructure words, variables, or constants).

The event passes the test if the last variable (in this case `test') has a non-zero value, but fails if it is zero or if no filter entry is generated. An entry is not generated if one of the banks referenced is not present (and Discard Partial Entry switch is on) or if a variable is out of bounds. The latter case allows tests to be constructed with a single line such as this one for ( $50\leq N_{hit}\leq999$):

' nhits float_equals EV+$KEV_NPM: 50 999; '

but this construction should not be used if AND scanning is involved as explained below. It is better to play safe and use a logical DQF, for example, the above test is better written as:-

' nhits float_equals EV+$KEV_NPM; '
' nhits_ok in_range 50, nhits, 999; '

although this now costs the an extra line, getting the number of hits and converting it to floating point before applying the test.

There are a few subtle differences between ntuple requests and filter requests. Firstly, it must be remembered that filter variables are never stored (that's what HBOOK ntuples are for!). Secondly, the idea of scanning the data structure takes on a different meaning. When scanning is switched on in an ntuple request (scan D/S = 1), any banks referenced in the ntuple definition with multiple occurrences in the datastructure (eg MCVX) will generate a separate ntuple entry. With the filter, such banks are scanned according to the same rules but instead generate individual tests which are treated in one of three ways:-

Scan D/S	Meaning
0	No scan - take the first bank reached for the test.
1	Form the logical AND of the tests.
2	Form the logical OR of the tests.

If AND scanning it is better not to apply cuts, for entries which fail them will be discarded and not analysed by the filter. If all the failures are thrown away and only the success passed on, then the AND scan will suceed even though there are failures!