If you are using the event list option to provide the data quality selection which bursts in a data set are to be analyzed, Hanna so far did not provide the possibility to count the luminosity from the 'good' bursts only. The user function user_burstinit(...) is called at the beginning of every new record (i.e. burst or part of a split burst) in the input file, regardless of whether it matches an entry in the event list or not. Hence you can't sum up the luminosity at every call of user_burstinit(...).
The fact that the routine user_event(...) is only called for events which match an entry in the event list might tempt you to check whether this event belongs to a new burst at the beginning of this routine and count the luminosity accordingly. However, this is not a correct treatment! Especially if you are running on filtered data sets like the nano DSTs there is always a finite probability that 0 events occur during one burst. You certainly have to count the luminosity of these 'empty' bursts, too. Yet the routine user_event(...) is never called when processing an empty burst and your code will count too little luminosity.
Since version 3.0 the Hanna user function user_burstinit(...) provides a fifth parameter int burstgood which is set to 1 if the run and burst number of a new record in the input file match an entry in the event list. Else this parameter is set to 0. Note that the event number field of the event list is ignored for setting the parameter int burstgood!
In order to count the collected luminosity of 'good' bursts correctly you have to use Hanna version 3.0 or later and modify the interface of your user_burstinit(...) routine and only sum up the luminosity of this new burst if the parameter int burstgood is equal to 1.
Hanna provides the command line option --events to read an ASCII file with up to five columns to select events from the input file(s) for analysis. The format of the event list file is described here. Hanna decides on the match of the triplet (eventnum, burstnum, runnum) of the next event from the input file with an entry from the event list whether or not to analyze the event. Any of the fields eventnum, burstnum, runnum can be replaced by the wildcard symbols -1 or *.
A quite popular application for event lists is to generate burst lists with data quality information from the large lists in a given data set provided by the g1 analysis group. The burst lists for Hanna are much smaller as they only contain lines for bursts with 'good' data quality in up to 5 columns. As a typical example, a few lines from a burst list used by the semi-inclusive analysis group for the 97b2 data production are shown here:
(event burst run DST_cntr polbit) -1 9339 15492 6 4 -1 9340 15492 7 4 -1 9341 15492 8 4 -1 9341 15492 10 8 -1 9342 15492 11 8 -1 9343 15492 12 8
Using the above event list, Hanna will only analyze events from run number 15492 and burst numbers 9339 - 9343. Note that Hanna does not cut on the information in columns 4 and 5 of the above list which contain additional information, namely the DST record number and the target polarization state. Burst number 9341 in this example is split into three parts (DST records 8, 9 and 10) when the target was in the parallel / undefined / anti-parallel state, respectively. The experiment was fully operational during this burst, hence the two parts of this split burst with well defined target polarization state (polbit==4 or polbit==8) and marked as 'good' and foreseen for analysis.
Multiple identical entries in event lists
The above example contains from Hanna's
point of view two identical lines! As Hanna ignores columns 4 and 5,
burst number 9341 appears twice in this list and three times in the
input file. Consider the case when the anti-parallel target polarization
state would have been marked as 'bad'. Then the above list would rather
look like:
(event burst run DST_cntr polbit) -1 9339 15492 6 4 -1 9340 15492 7 4 -1 9341 15492 8 4 -1 9342 15492 11 8 -1 9343 15492 12 8Again, burst number 9341 appears in this list but only the first part of this burst is now considered to have 'good' data quality.
Hanna is not able to distinguish between the two above example burst lists other than on the fact that in the first example the line with burst number 9341 seems to appear twice. For this reason Hanna will terminate running after generating an error message if it detects multiple identical entries in event lists. In the next section a method is proposed how to make sure that parts of split bursts are never analyzed with the wrong data quality information.
Historically, multiple entries were first identified as originating from bugs in the code used to generate the g1-style burst lists. However, since the introduction of split bursts in the HERMES data stream in 1996, the tuple (burstnum,runnum) is not sufficient any longer to unambiguously identify the smallest fraction of the data set with common data quality information.
Provided with all the above information, nevertheless you still might wish to use burst lists with multiple identical entries (even though it's highly probable that you are analyzing data with 'bad' data quality information provided you are using this event list based data quality scheme). To force Hanna to continue running over multiple entries in event lists, use the --evsloppy command line option. Hanna will then run silently over these multiple entries assuming the user is aware of the consequences. If you still wish to receive warnings from Hanna on multiple entries, you have to set the debug level of the event list module to a value of 1 (or greater).
Please note that this handling of multiple identical entries in event lists has only been introduced in Hanna version 3.0! If you are/were using earlier versions of Hanna in your analysis you probably will have suffered from the problems laid out above...
How to generate event lists suited for Hanna
This section is very imcomplete as it does not present anything but two proposals how to avoid the problem described above ...