Using Eventlist Files
Last update: July 8, 2003

This memo describes how to create and use eventlist files. An eventlist file is used to speed up the accumulation of events. It contains a list of time tagged events in a format that does not require unpacking, in contrast to reading data from the Level-0 data files. The increased speed is mainly because we store the eventlist in the same streaming format that we use in the spectrogram process.

Furthermore, an additional speed increase comes from the second feature of the event list files. Events relevant for a specific analysis can be selected in advance and all others can be excluded. This reduces the number of photons that the software has to read for the analysis.

The following only refers to usage from the command line. The ability to write and read eventlist files will be added to the HESSI GUI soon.

How to use it

The idea is to

(1) create the file using personal selection criteria such as the energy and time ranges ( energy_band and time_range) , calling the write method and

(2) use the eventlist file in the hsi_image, hsi_lightcurve or hsi_spectrum object.

Datagap Experts only:
Another personal choice is the value of the DP_CUTOFF (currently 0.03 seconds by default). This is a parameter used for datagap discrimination, datagaps shorter than this duration will not be stored and not be considered when the file is used in the future.

1. Create an eventlist file

Eventlist files are created either from the simulations or from the Level-0 data. The creation of the eventlist files is unsurprisingly associated with the eventlist object. Thus, an eventlist object must either be created with

o = hsi_eventlist()

or it must be retrieved from an already existing object, such as hsi_image hsi_spectrum or hsi_lightcurve, e.g.

    s = hsi_spectrum()
    s->set, ....
    o = s->get(/source)

Create eventlist files from simulations

Here is an example of eventlist file creation from simulations:

; this is required to get into the simulation mode:

hsi_switch, /sim
o = hsi_eventlist()
; here any simulation parameter can be set:
aa = o->getdata( sim_energy_band $
=[6.00, 100.0], sim_background=1.0 )
; setting time_range and energy_band to [0,0]

; is equivalent to selecting the whole range:
o->write, 'hsi_0.fits', time_range $
=[0, 0], energy_band=[0, 0]
; when done, destroy the object to free the memory obj_destroy, o

Create eventlist files from Level-0 files

Here is an example of eventlist file creation from Level-0 data files

; switch to the flight mode
hsi_switch, /flight

; create the eventlist object
o = hsi_eventlist()
; set the observing time interval
o->set, obs_time = '2002/02/20' $
+ ['11:05', '11:15']
; reset the time range to [0,0]. it is set to [0,4] as a default
; to avoid selecting an umanagable amount of data
; set some energy band
o->set, time_range = [0, 0]
o->set, energy_band = [10,20]

; write the file. the default filename

; is used when no filename is given.

; here it would be : hsi_eventlist_20020220_1105_20020220_1115_0_0.fits
o->write
; when done:
obj_destroy, o

2. Using eventlist files

Any object can use the eventlist file, in particular, hsi_image, hsi_spectrum , and hsi_lightcurve . For example, here is how to make an image of the 20 Feb. flare, 4-8 seconds after 11:05, in the energy band 10 to 15 keV.

o = hsi_image( ev_filename $
= 'hsi_eventlist_20020220_1105 $
_20020220_1115_0_0.fits' )

o->set, time_range = [4, 8]
o->set, energy_band = [10,15]
o->set , xyoff = [-950,-220], $
image_dim =64, pixel_size =2
im = o->getdata()

Note:
Do not set OBS_TIME_INTERVAL when using the eventlist file. That will cause the object to read from the Level 0 files instead.

The use of eventlist files containing simulated events is exactly the same, assuming however, that the simulation database files are used, i.e the command hsi_switch, /sim has been issued before.

Important note:
the file covers a predetermined time interval and energy interval. If the energy or time range used for the event accumulation does not lie within this given energy and time interval, the software goes along and does the requested data product, considering the energies and times outside the energy and time interval as without events. In the future the software will issue a warning to the user that the requested data is outside of the range stored in the file.

3. Going back to normal mode

To go back to normal mode, you can set ev_filename to '', or a blank string, or setting the obs_time_interval. This will turn the eventlist file mode off and set the normal mode on again. Switching from simulated data to real data always require the hsi_switch command

4. Advantages in using the eventlist file.

As an example consider the recent gamma ray line flare on 17 June 2003. We prepared two eventlist files, the first including all possible photon energies and the second only including the range from 400 keV to 2.5 MeV. Accumulating a spectrum from 22:56:20 UT to 22:58:00 UT took 13.7 seconds using the restricted energy range eventlist file, 30.1 seconds using the unrestricted eventlist file, and 57 seconds using the Level 0 files. In the best case, the speed increase more than a factor of 4 and at least nearly a factor of 2. The eventlist file will provide a substantial time savings when you make repeated accumulations from the same time and energy range.

Andre Csillaghy
csillag@ssl.berkeley.edu

Richard Schwartz
richard.schwartz@gsfc.nasa.gov