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
|
