TBURST Users Guide
EGRET/NGC/EJS/TBURSTUG/97/JAN
TBURST - USER'S GUIDE
NASA CONTRACT NAS5-29335
Prepared for
Goddard Space Flight Center
by
Northrop Grumman Corporation
Prepared by
Edward J. Schneid
User's Guide ---------- 3/26/97
ABSTRACT
This document provides information on how to use the TBURST program. Section 1
contains a general description of the program. Section 2 lists the steps to
execute the program. Section 3 describes the program I/O interface.
TABLE OF CONTENTS
- GENERAL DESCRIPTION
- Program Purpose
- Program Description
- Applicable Documents
- RUNNING TBURST
- Preliminary Requirements
- Program Execution
- I/O INTERFACE
- Main Panel Inputs
- Solar Burst Analysis Option Panel Inputs
- BATSE Burst Analysis Option Panel Inputs
- Anti-coincidence and TASC Housekeeping Rate Option Panel Inputs
- Spectral File Panel Inputs
- Plot Generation
- Solar Burst Analysis Option
- Console Display Outputs
- Solar Analysis Outputs
- BATSE Burst Analysis Option
- Console Display Outputs
- BATSE Analysis Outputs
The EGRET instrument has the standard elements of a high-energy gamma-ray
telescope based on electron-positron pair conversion and charged-particle
detection. It consists of a multilevel spark chamber triggered by a
directional scintillator coincidence system, and has a large scintillator dome
used in anticoincidence to veto charged particles. There is a large (76 x 76 x
20 cm.) NaI(Tl) Total Absorption Shower Counter (TASC) used as its principal
energy-measuring device. The TASC calorimeter analog signal is fed into a pair
of pulse height analyzers, one for high energy (20 MeV to 30 GeV) and one for
low-energy (1 to 200 MeV). The high-energy results are telemetered
individually for each triggered event. The low energy results are accumulated
continuously onboard in a spectrum of 32.76 seconds and telemetered separately
when the spectrum is completed.
The TASC calorimeter is located at the base of the high-energy telescope and is
not covered by the anticoincidence scintillator dome or any other active
shield. The amount of material surrounding the TASC is a minimum in the
telescope direction and therefore the TASC has its highest sensitivity in that
direction, but it is sensitive to gamma rays incident from any direction. The
backgrounds in the TASC are due to incident gamma rays (including atmospheric,
gamma rays from onboard radioactive sources or induced radioactivity), SAA
activation, and charged particles passing through the TASC. In flight,
gamma-ray lines are observed in the low-energy spectra and are useful energy
calibration standards. The two lines are produced by materials in the
instrument: radioactive 40K (1.46 MeV) from the spark chamber
material and the neutron capture lines in iron (7.6 MeV).
The accumulation of a low-energy spectrum is the normal or solar mode of data
acquisition. However when a gamma-ray burst occurs, The Burst And Transient
Source Experiment (BATSE) provides a trigger that initiates a special burst
mode of accumulation that acquires four sequential spectra in addition the
normal acquisition spectra. The time intervals for the BATSE related spectra
are programmable and are usually 1, 2, 4, 16 seconds. The BATSE related
spectra are telemetered separately over the next one half hour period. When
all the data packets corresponding to the four spectra are accumulated on the
ground, these spectra are inserted into the Primary Data Base (PDB) file.
Therefore the BATSE related data spectra are found in the PDB file among the
normal TASC spectra approximately one half hour after the corresponding normal
spectra. The TASC record in the PDB file contains an indication whether the
spectrum is a normal spectrum or a BATSE triggered spectrum. An alternate
database, called the TASC Burst (TBDB) contains the same TASC spectral records,
as the PDB, and it includes essential housekeeping and rate data. It is
smaller and consequently more convenient for analysis.
The low-energy spectra are accumulated and telemetered in a compressed format.
The low energy signals are digitized with the pulse height analyzer over a
range of 8196 channels but are stored onboard only as a 256 channel spectrum.
For the compressed spectrum, the first 64 channels have a compression factor of
two with the compression factor doubling for every set of 32 channels after the
initial 64. Therefore the channel energy and channel bin width for the
spectrum must take into account these compression factors.
Analyses of gamma-ray bursts and solar flares showed that data accumulation and
telemetry errors occurred in the TASC spectral records. Some spectra had
missing or low values in the live time counter. TBURST computes the live time
for all spectra and compares it to the hardware times. Generally, the two
values closely agree within a few percent. The analysis uses the computed
times for all its calculations. Several other errors were identified in the
spectral records. Some examples of errors are: shifted spectrum (that is, the
compression breaks were found in the wrong channels), data found in channels
below the PHA thresholds, and missing or erroneous data. Results derived from
these spectra were found to give inconsistent results. After the onboard tape
recorder failure, data dropouts in the spectra were found to increase due to
lack of continuous telemetry coverage. This is often noticed in the BATSE
spectra which take a long time to read out so that there is a significant
chance of a telemetry gap. Special efforts have been made in the TBURST
program to screen the data in the PDB or TBDB files for errors and to reject
the data from the analysis. In some cases the spectrum is only flagged as
having a potential problem so that the user can be made aware of the problem
during the analysis.
The purpose of the TBURST program is to analyze the TASC low-energy spectral
data for the presence of gamma-ray burst or solar flare related signals.
TBURST locates the BATSE spectra or normal spectra for the period of the burst
or flare event and the normal spectra for the time periods immediately before
and after the event. The spectra before and after the event are used to
provide an estimate of the background during the burst or flare event.
Before the spectral data can be analyzed, TBURST reads either the PDB or TBDB
file or files that cover the time period in the burst or flare and extracts
only those records that contain the TASC spectral data. These spectral records
are written to a program defined default file that is used by the data analysis
routines. During the reading of the input files, the records are screened for
the known errors. Records that contain known serious errors are rejected and
not written to the default file. Less serious errors are flagged, and if those
records are attempted to be used during an analysis, warning messages are given
to the program user. If the user is analyzing the same input file as used in
the previous analysis, the input file does not have to be read again. In that
case, the program uses the default file for the TASC spectral data.
The purpose of the TBURST program is to accomplish two separate, but related
tasks:
1. The analysis of TASC BATSE triggered spectra acquired during BATSE burst
mode data acquisition for burst or flare signals. The program locates the
BATSE triggered spectra and the spectra acquired immediately before and after
the event. These spectra are used to estimate the backgrounds during the
event. The backgrounds are subtracted from the BATSE triggered spectra in
order to establish the presence of any residual signal due to the burst or
flare.
2. The analysis of the TASC spectra acquired during the normal mode of
operation for burst or flare signals. The program locates the normal spectra
for the user specified time interval for the burst or flare and the spectra
acquired immediately before and after the event. These spectra are used to
estimate the backgrounds during the event. The backgrounds are subtracted from
the burst or flare period spectra to establish the presence of any residual
signal due to the burst or flare.
TBURST has three additional options that can be useful in the analysis of
burst or flare data. The third option in the panel allows the user to obtain
the anticoincidence shield and TASC housekeeping rates around the time of the
gamma-ray burst or solar flare. This option helps to establish for the user
the total time period of the burst or flare event so that proper selection of
backgrounds before and after the event can be made. The fourth option
generates a separate file containing dead-time corrected spectral data along
with spacecraft position information. This file has two purposes. First, this
file allows the user to examine all the spectra that are used in the analysis
in order to ensure the quality of the data. This file is also useful in other
analyses by programs requiring data from multiple orbits for the analysis of an
event. The last option provides plots of the analyses of the first three
options that can be viewed and also stored in postscript files. The ability to
view the spectral allows for interactive adjustments of the time or energy
ranges for the analysis.
The TBURST program runs in the following sequence:
- A set of panels appears that are used to establish all the parameters
required for the execution of the program. A main panel will appear containing
an area displaying the selection of the five program options, and an area
containing a listing of all the files in the directory available for the
analysis in either of the selected PDB of TBDB databases. The user selects one
of the program options, and the file or files that cover the period of time
containing the gamma-ray burst or flare event. Selection of a program option
will result in a second panel appearing specific to the running of that program
option. For the solar or BATSE burst options, this panel contains the
following inputs: user adjustable analysis parameters with their default
values, specific start time and or duration for the burst or flare being
analyzed, and an option to save the results to a files. When both panels are
completed, the user selects the "run" option on the main panel and the program
will proceed.
- The program then reads the PDB or TBDB file or files indicated by the panel
selection. The program copies only the relevant TASC spectral records into
another program-defined default file to permit efficient program execution.
During this process, all TASC records are checked for errors and only
acceptable records are saved to the default file.
- Selection of the Solar burst option analyzes the normal or solar 32.76 s
records for the presence of gamma ray burst or flare signals within the input
time interval.
- Selection of the BATSE burst option analyzes the four BATSE triggered
spectral records for the presence of gamma-ray burst or flare signals.
Selection of the Solar burst analysis option.
S1. The default file is searched for the records that contain the time interval
of interest. A table containing information on selected records for
backgrounds and burst or flare interval is provided to the user.
S2. Using a time-weighted averaging of the background records listed in the
table, the program subtracts the background from the burst or flare records.
Results are obtained for the spectra and selected energy regions. The spectral
records can be output to the results file if desired. The results of the
energy regions are displayed to the user in summary tables in terms of sigma
values (signal/noise) or in residual counts. During the analysis, if there are
any flags that would indicate corrupted or suspect data, error messages are
displayed to the user who might want to repeat the analysis without the suspect
record.
S3. The user is returned to the main panel and the user can repeat the analysis
with different analysis parameters or selection of spectral records.
Selection of the BATSE burst analysis option:
B1. The program then starts a search of the input default file and locates the
BATSE triggered spectral records. The program then locates the records that
correspond to the solar records acquired immediately before and after the
interval covered by the BATSE spectra. Note that for bursts that last longer
than the time interval for the BATSE triggered spectra, the user should use the
background offset option in the panel to select background records that are
acquired after the burst. A table of all the BATSE burst records and the
corresponding backgrounds records are displayed to the user.
B2. The program performs a time-weighted linear background subtraction of the
four BATSE burst related records. Results are obtained for the spectra and
selected energy regions. The results of the energy regions are displayed to
the user in summary tables in terms of sigma values (signal/noise) or in
residual counts. During the analysis, if there are any flags that would
indicate corrupted or suspect data, error messages are displayed to the user
who might want to repeat the analysis without the suspect record.
B3. The user is returned to the main panel and is given the option of repeating
the analysis with different analysis parameters.
For more information, the user may consult the following documents.
- TBURST - Program Definition Manual
- EGRET Telemetry and Data Formats, #82-3-5
- The Gamma-Ray Observatory Science Plan, Sept. 1981.
-
TBURST runs on a SUN UNIX system under FORTRAN. Three environment variables
are used to control the input and output file locations. These should be
defined before attempting execution. The first environment variable,
$PDB_DIR, defines the directory that contains subdirectories, /pd,
and/or /tb that in turn contain the PDB and/or TBDB input data files. The
second environment variable, $TBURST_LOG, defines the directory that
will contain the output files that are elected in the input panels when the
program is executed. The third environment variable, $REPORT_DIR, is
the location where details of the program execution are written.
To begin execution of the program the user types "tburst"
The TBURST program uses panels to establish all parameters required for the
analysis. During execution of a program analysis option, program-generated
messages and a summary of the analysis results are displayed on the user
console and are written to a file in the $REPORT_DIR directory named
"tburst_report.yyyymmdd_hhmmss" where yyyy, mm, dd, hh, mm, and ss are the
year, month, day, hour, minute, and second when the program was executed.
Program analysis outputs can be saved in the files defined by the panel
options. These files are written in the $TBURST_LOG directory and are named
according to the type of analysis and output type and a time stamp based on the
date of the data.
A brief description of the TBURST input panels is given in section 3.1. A
description of the program messages generated during program execution for the
two analysis options, Solar burst and BATSE burst, are found in section 3.2 and
3.3 respectively.
Figure 1 gives an example of the TBURST main panel. The user selects one of
the five options to be run and selects the PDB file or files that cover the
period of time for the analysis. The user would scroll through the list of PDB
or TBDB files and click on those files that cover the desired period of time.
The name of the file contains the information on the period of time covered by
the file. In the example of Figure 1, data is selected for 09/09/1996 from
09:00:19 to 12:00:31. More than one file can be chosen if the event spans files.
Figure 2 gives an example of the panel that appears when the Solar burst
analysis option is selected. This panel contains inputs that relate to the
parameters used in the analysis, the time range to be analyzed and an option to
save the analysis results to output files. The analysis parameters are same as
those used in the BATSE burst analysis.
The default number of TASC solar records to be used as background immediately
before and after the burst is 2 (each background record contains a TASC
spectrum acquired for 32.768 seconds). A value of 1 may be too small in order
to obtain a good average background before or after the event. Over a large
time the background is not linear with time. Therefore selection of a large
value will cause an erroneous average that can lead to incorrect results in the
analysis.
This panel gives the user an option to move the background regions relative to
the gamma-ray burst of flare event. This option may be more important during
the BATSE burst analysis if the gamma-ray burst is not over when the last BATSE
triggered spectrum is completed.
The energy spectrum's gain (MeV/Channel before channel compression) and offset
(MeV) are required to calibrate the spectra. These values should be changed
when the user has determined the values for the system. The value for
parameter 6 (24) appears not to be drifting with time. The value for parameter
5 does show a drift in time. The position of the 40K peak at 1.46
MeV in the background spectrum can be used to determine the value of this
parameter. The apparent position of this peak must be multiplied by 2 in order
to obtain its position in the uncompressed spectrum.
The region energy limits can be selected to sum a large portion of the spectrum
in order to enhance the signal statistics during the analysis. This is useful
in the initial analyses to determine if there is any signal from the burst or
flare.
The user can select up to 5 energy regions of interest. Different energy
intervals may be overlapping. For each energy interval desired and the low and
high energy boundary for each interval must be entered. Channels values
corresponding to the input energy range are calculated using the calibration
values. The subsequent signal calculations will then be performed for each of
the selected energy intervals. The results of the energy region analyses are
presented in the summary output that contains the results in terms of a
signal/noise ratio. The light curve results present the same information for
the energy regions but in terms of residual counts.
The program provides the opportunity to save the analysis results to several
output files. One file contains the results of the spectral analyses. The
other files are files for the analysis of the selected energy regions allowing
the user to readily determine if there is any residual signal associated with
the burst or flare.
The spectral analysis file is organized into three parts:
- The first part contains the list for the channel number, energy, and counts
for the sum of the background spectra before the event, the sum of the burst or
flare spectra, and the sum of the background spectra after the event.
- The second part lists the individual burst or flare spectrum in sequence.
It gives the spectrum number, and midpoint time of the spectrum in seconds,
followed by the list of the channel number, energy, and counts.
- The third part lists the background subtracted results for each of the burst
or flare records. It gives the spectrum number and midpoint time in seconds,
followed by the list of the channel number, energy, residual counts (cts/MeV),
and standard deviation (cts/MeV).
The summary file contains the signal/noise value and the standard deviation
value for each selected energy region is listed for each record associated with
the gamma-ray burst or flare interval.
The light curve file contains the calculated residual signal and the standard
deviation for each selected energy region in all the records used in the
analysis. It starts from the first record of the background before the
gamma-ray burst or flare interval to the last record of the background after
the interval.
Figure 3 gives an example of the panel that appears when the BATSE burst
analysis option is selected. This panel contains inputs for the parameters
used in the analysis, the time of the BATSE burst, and the selection to save
the analysis results to output files. The definitions for the analysis
parameters are the same as those used for the Solar burst analysis and
discussed in section 3.1.1.
The BATSE burst time interval is defined by the BATSE spectra. However, it is
possible to have more than one set of BATSE spectra in a given PDB or TBDB file
or set of files. Therefore the time to be input in this panel is the time just
before the BATSE trigger so the program can select the burst of interest for
analysis.
The BATSE burst analysis has one additional output file. This file contains
the BATSE triggered spectra. In the reading of the PDB file, the BATSE
triggered spectra are not automatically rejected if record errors are found.
This raw spectra output file allows the user to examine and verify the quality
of the BATSE triggered spectra used in the analysis.
The other output files have the same definition as those generated during a
solar burst analysis.
Figure 4 gives an example of the panel that appears when the anti-coincidence
and TASC housekeeping rate option is selected. This option allows the
anti-coincidence shield rates and the TASC housekeeping rates around the time
of a burst or flare to be stored in a file for off-line plotting and
inspection. The program requests the time of the burst or flare event along
with a time period on each side of the event.
Figure 5 gives an example of the panel that appears when this option is
selected. No additional inputs are required from the user. The output file is
used for additional off-line analyses or inspection of the data records around
the time of the analysis. This file contains the following information: the
midpoint time of the accumulation, the summed counts in two regions (channels
31-50 and 31-114, approximately 1-2 MeV and 1- 10 MeV respectively), and the
spacecraft position and orientation, and the spectrum.
The last analysis option shown on the main panel is for generating plots of
analyses generated in the previous four options either for the current session
or earlier sessions of the TBURST. Selecting the "Generate plots" options
activates the "Exec_plot" button at the top of the panel and produces two
additional panels that are shown in Figure 6. The first of these specifies the
file with the analysis results, and the second offers a choice of plot type.
After selections have been made, press the "Exec_plot" key to generate the
plot. Output postscript files are an option in the plot panel, Figure 6b.
Note that in the case of the Anticoincidence and TASC rates plots that the
choices of Figure 6b are not used. Samples of the output plots are shown in
Figures 7 through 10.
The program uses the times input by the panel to select the records
corresponding to the burst/flare interval and backgrounds before and after.
The program selection is displayed in the burst/flare selection table.
START TIME BURST/FLARE RECORD UT = (time corresponding to start of rec 25)
END TIME BURST/FLARE RECORD UT = (time corresponding to end of rec 27)
The records may be changed in subsequent analysis when a different set of
background records is desired.
Because of telemetry errors and other "glitches" found to occur in the data,
any data used by the analysis are checked for error flags and any found error
messages are listed to the user on the console display. Results using any
record having an error message should suspect. The user should reanalyze the
event by selecting different records if possible.
The only analysis results displayed to the user during the execution are the
results the analyses of the selected energy regions. The displayed summary
table gives the signal/standard deviation value for each energy region
Inspection of this table helps to establish if there is any signal present and
if changes in the analysis parameters such as selecting different backgrounds
or extending the event period are desired.
The spectral results are saved in a file if the user used to option in the
input panel to save this file.
The program searches for the requested BATSE triggered spectral data
acquisitions and then locates the appropriate backgrounds before and after the
BATSE accumulations. The results of the search are presented in the burst
indicator table.
This is an example
THERE ARE 195 RECORDS IN THIS FILE
BATSE BURST AT RECORD 178, JULIAN DATE 7349, JULIAN TIME 64790563
The burst indicator table lists for the BATSE burst, the record numbers for the
BATSE spectra and the selected background records.
The analysis of the event proceeds and if any telemetry errors and other
"glitches" found to occur in the data, an error message is displayed to the
user. Analysis results using any record having an error messages should
suspect. The user should reanalyze the event by selecting different records if
possible.
The program can save the analysis results to several output files. One file
contains the results of the spectral analyses. The other files contain the
results for the selected energy regions. The only results displayed to the
console are for the analysis of the selected energy regions. The program
displays a summary of the analysis results for the selected energy regions
allowing the user to readily determine if there is any residual signal
associated with the burst or flare. The summary table listing the signal/noise
value for each selected energy region is displayed for each record associated
with the gamma-ray burst or flare. The light curve table presents the
calculated residual signal for each selected energy region in all the records
used in the analysis. It starts from the first record of the background before
the event to the last record for the backgrounds. The associated standard
deviation value is not displayed but these results are saved in the light curve
file.