How to work with the eventlist object and with eventlist files

Last update: October 16, 2004

This document describes how to create and use the eventlist object. The main goal in using this object is to create eventlist files to speed up the accumulation of events. An eventlist file 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.

As an example of the advantage of using eventlist files, 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.

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.

The general idea is to first create the file using personal selection criteria such as energy range and time range; second call the write method; and third use the eventlist file in the hsi_image, hsi_lightcurve or hsi_spectrum objects, instead of specifying an observing time interval or an imaging time interval.

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.

Here is a first example on how to create an event list file. This case will be then discussed in the next sections:

o = hsi_eventlist()
o->set, obs_time_interval = '2002/07/23 ' + ['00:27:20', '00:43:20']
o->set, energy_band=[2218,2228]
o->set, det_index_mask = [0,0,0,0,0,0,0,0,1]
o->set, time_range = [0,0]
o->write

1. Create an eventlist object

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

o = hsi_eventlist()

creates a new eventlist object. Alternatively, the eventlist object can be accessed from an already existing object, say oo, such as hsi_image hsi_spectrum or hsi_lightcurve:

o = oo->get( class = 'hsi_eventlist', /object_reference )

2. Set the parameters for the events stored in the event list file

Parameters that control the event list fle generation are the observing time interval, the energy band, and the detectors. The parameters are equivalent to those used in imaging. The first command sets the observing time interval for which the the eventlist must be generated.

o->set, obs_time_interval = '2002/07/23 ' + ['00:27:20', '00:43:20']

The second command sets the energy band, in this example, only the photons in the 2.2 MeV line will be stored.

o->set, energy_band=[2218,2228]

The third command selects the detectors, in this example only photons of the detector #9 will be stored in the file:

o->set, det_index_mask = [0,0,0,0,0,0,0,0,1]

Finally, the time_range parameter need to be reset, as it is set by default to [0,4] to protect against selection of unmanageable amounts of data in the imaging software. Without doing this, only the photons in the first four seconds would be stored in the file.

o->set, time_range = [0,0]

3. Write the event list file

o->write
Writes the file. A default filename is used when nof filename is given, in this example the filename is hsi_eventlist_20020723_0027_20020723_0043_2218_2228.fits. Any filename can be used, by passing it to the write method:

o->write, 'your_file_name.fits'
    

4. Destroy the object

When the eventlist file is written, destroy the object to free the meomry used by the object:

obj_destroy, o

5. Creating eventlist files with simulated data

The output of simulations is also stored in eventlist files. Simulations is described in the document xxx. For simulations, you must first switch to the  corresponding mode:

hsi_switch, /sim

Them you can create teh eventlist as described above:

o = hsi_eventlist()

After the object is created, any simulation parameter can be set:

event_list = o->getdata( sim_energy_band=[6.00, 100.0], sim_background=1.0 )

See the list of parameters for more information about simulation parameters. In case of simulations,  time_range and energy_band must be set to [0,0] to ensure that the whole simulated time/energy range is actually written to the file:

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

6. Using eventlist files

Any object can use the eventlist file, in particular, hsi_image, hsi_spectrum, and hsi_lightcurve. It is very important to note  that 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. Therefore, selecting an energy band of [10,15] keV, for instance, while the events stored in the file are in the range [2218,2228], will return an empty image (0 counts).  Here is an example on how to make a back projection of the 2.2 MeV line of the 23rd of July flare, accumulating 5 minutes of data.

First create the object, and specify that the source of the data is the eventlist file previously generated:

o =  hsi_image( ev_filename='hsi_eventlist_20020723_0027_20020723_0043_2218_2228.fits' )

Then set the time range of the image, here for instance 5 minutes:

o->set, time_range = '2002/07/23 ' + ['00:27:20', '00:32:20']

Note again here that this time range must be included withing the time range of the eventlist file. If this time range is larger, then it will consider that 0 counts have been observed in the excluded domain.

Set the energy band, or set it to [0,0] if you want the entire range stored in the file:

o->set, energy_band = [0,0]

Set the detector index mask to whatever is needed

o->set, det_index_mask = [0,0,0,0,0,0,0,0,1]

Set additional imaging parameters

o->set , xyoff = [-886,-233], image_dim =64, pixel_size =2

Get the data:

im = o->getdata()

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. If the time range used for the event accumulation does not lie within this give time interval, the software issues a warning but goes along and does the requested data product, considering the times outside the time interval as without events.

7. Going back to normal mode

To go back to normal mode, you can set ev_filename to '', (empty string). This will turn the eventlist file mode off an set the normal mode on again. Switching from simulated data to flight data always require the hsi_switch,/flight command

 
André Csillaghy csillag@ssl.berkeley.edu
Richard Schwartz richard.schwartz@gsfc.nasa.gov