THE BATSE FLARE PLOT PROGRAM Kim Tolbert May 30, 1991 Revised: February 12, 1992 Revised: July 22, 1992 Revised: December 11, 1995 The Flare Plot Program plots BATSE Large Area Detector (LAD) Discriminator (DISCLA) data for time intervals and detector/channel combinations selected by the user. The DISCLA rates are available every 1.024 s for 8 detectors, in 4 energy channels, 25-50, 50-100, 100-300, and >300 keV. `Channels' 4 and 5 contain the NaI and CPD counts respectively. (As of December 11, 1995, Channel 4 has been changed to a differential channel from 15-25 keV by subtracting the other channels from Channel 4.) The 8 detectors are placed on the corners of the GRO spacecraft with the orientation of the faces being those of a regular octahedron. The area of each detector is 2025 cm^2. In addition to the DISCLA data, there are also CONT data available at 2.048 second resolution from the same LADs covering 16 energy channels from 20 keV - > 2 MeV for each of the 16 detectors. There are also data available from the smaller Spectroscopy (SPEC) detector discriminator channels (DISCSP) also every 2.048 seconds. The data are used here in their differential form and cover 4 channels of which only the lowest two are useful for flare measurements. The gains of the SPEC detectors are set over a wide range and usually at least two detectors will be of use with their lowest energy channel having an effective response from 10-15 keV and another channel with an effective response centered near 20-25 keV. We also have included a link to GOES data which covers the soft X-ray bands with data every ~3 seconds in two channels. To generate the plot, DISCLA data is accumulated at 1.024 s resolution, corrected for overflows, divided by the livetime, channels requested are added together, samples are averaged to the time resolution requested, and detectors requested are averaged. If background is subtracted (as in the PLOTFLARE command), the detector rates are scaled by the detector's effective area before averaging. The CONT and DISCSP are treated analogously at their native sampling time of 2.048 seconds. The user chooses the screen and printer graphics formats through menu options. The choices for screen output are Tektronix, X windows, and Regis; the choices for printer output are Tektronix and PostScript. X windows can be selected only if the user supplied the display node when prompted during the login procedure. If Tektronix screen output is selected on a VAX/VMS machine, the terminal must be set to NOWRAP via the SET TERM/NOWRAP command. In each case it is the user's responsibility to choose formats compatible with his hardware. Remote users can copy the Tektronix or PostScript printer plot files to their node for displaying or printing. On entering the program, the user is presented with a menu displaying the current settings of parameters and the available commands. The user either accepts the default value of a parameter, or changes the value by typing the first 3 letters of the parameter description, comma, the new value. When the parameters are set as desired, the user issues a command (again, the first 3 letters are sufficient). Upper or lower case may be used for input. A detailed description of the parameters and commands is given below. Typically, a user selects an input file via the INP parameter, specifies a time interval via the STA and END or TOT parameters, and issues the ACC command. Subsequent plots of the same time interval displaying different detectors, channels, sample average, etc. can be generated by issuing the GRA command, which is much faster than ACC. When a different time interval is specified, the user must issue the ACC command so that the new data will be read in. Some handy commands are: LIS - Displays the menu. MAR - Draws horizontal bars near the top of the plot displaying any flare or background regions in catalog within the time interval of the plot. OVE - Overlays a trace on an existing plot. PLO - Finds the file containing the requested flare, accumulates the data and plots it. User doesn't need to select an input file. TYP - Prints the cataloged values (start time, duration, peak rate, total counts, and background intervals) for a flare quickly. SAV - Save accumulated data in an IDL save/restore file. --------------------------------------------------------------------------- A. Flare Plot Program Parameters: Note: All times are entered in the format YY/MM/DD,HHMM:SS.XXX Seconds and fraction of seconds (SS.XXX) are never necessary, and year, month, and day (YY/MM/DD) aren't necessary when entering subsequent times on the same day. INPUT FILE - Name of input DISCLA (FDB), CONT, DISCSP, GOES file (see DATA parameter description). Use the FILELIST command to get a list of available files. No default value; input file must be explicitly selected by user unless using the PLOTFLARE command. There are 3 selection methods: INP,FILENAME - enter file name directly. INP,T,TIME - enter a time (date or date and time) contained in desired file. Example: INP,T,91/4/30,0900 INP,F,FLARE# - enter a flare number contained in the desired file. Example: INP,F,233 DATA TYPE - Selects DISCLA, CONT, DISCSP, or GOES database. Additionally, by selecting ALL4, a single plot can be made showing all 4 data types over the same time interval. Example: DAT,DISCLA START TIME OF PLOT - Defaults to the start time of the input file when a file is selected. (See note above for format of times.) Example: STA,91/04/21,1230 or STA,1230 TOTAL TIME - Duration of interval of data to plot in seconds. Defaults to the duration of the input DISCLA(FDB) file. Example: TOT,300 (sets duration to 5 minutes) END TIME OF PLOT - Defaults to the end time of the FDB file. (See note above for format of times.) Example: END,91/04/21,1235 or END,1235 SAMPLE AVERAGE - Number of 1.024 s data samples to be averaged before plotting. Default is 1 (1.024 s resolution). Example: SAM,4 (selects 4.096 s resolution for plot) CHANNELS SELECTED - Channels to plot (if more than one, the channels will be summed). Separate by commas or a hyphen. For DISCLA, Channels 0-3 have energy ranges 25-50, 50-100, 100-300, and >300 keV respectively, and channels 4 and 5 contain the NaI and CPD counts. Default is channels 0 and 1. For CONT, there are 16 channels available and channel 1 is the default for detectors 1 and 2. For DISCSP, there are 4 channels available, with 0 and 1 the default for only detector 1. Example: CHA,2,3 (selects channels 2 and 3) DETECTORS SELECTED - Detectors to plot (if more than one, they will be averaged). Separate by commas or a hyphen. The meaning of the detector numbers depends on whether ASPECT ORDERED DETECTORS option, below, is enabled or not. Default is detectors 1 and 2, and default for ASPECT ORDERED is ENABLE, so detectors 1 and 2 refer to the two most sunward facing detectors. If aspect ordering is disabled, detectors are defined as 0-7. For DISCSP data the detectors cannot be combined. Example: DET,1-4 (selects four most sunward facing detectors if ASPECT ORDERED is ENABLED, physical detectors 1-4 otherwise.) ASPECT ORDERED DETECTORS - Selects whether detector numbers are absolute or ordered by decreasing angle to sun. Options are ENABLE or DISABLE. ENABLE - Detector number 1 refers to the most sunward facing detector, detector 2 refers to the second most sunward facing detector, and so on. Detectors 5-8 are the anti-sunward detectors. For DISCSP data the detector selection is made by estimating the detector with the maximum sensitivity based on aspect and the effective photon energy. DISABLE- Detector numbers 0-7 are fixed and always refer to the same physical detector. Default is ENABLE. Example: ASP,ENA (detector numbers will be ordered by angle to sun) HISTOGRAM - Selects whether to draw histogram or point plot. Options are ENABLE or DISABLE. Defulat is ENABLE. Example: HIS,DIS YAXIS - Selects whether Y axis is logarithmic. Options are LOG or LINEAR. Default is LINEAR. Example: YAX,LIN (Y axis will be linear) XMIN, XMAX - Range of X axis to plot. Defaults are 0.0 (autoscale). To plot only a portion of the accumulated data, set XMIN and/or XMAX to the times desired. Also, PRINT command only prints data between the times specified by XMIN and XMAX (if nonzero). Example: XMI,1205:10 (sets lower limit of X axis to the time 1205 and 10 seconds) YMIN, YMAX - Range of Y axis to plot. Defaults are 0.0 (autoscale). If YMIN is set to a non-zero value, then YMAX must also be set, and vice versa. Example: YMA,2000. (sets upper limit of Y axis to 2000.) MULTIPLE PLOTS - Selects number of plots to draw on one page. Specify mxn where m is the number of plots across the page and n is the number of plots down the page. Keeping the same aspect ratio as a single plot (i.e. 2x2 or 3x3) will result in properly reduced plots. To clear the page before all mxn plots are drawn, type MUL,mxn again. Default is 1x1 (single plot). Example: MUL,2x2 MUL,1 CREATE PLOT FILE - Selects whether to send the plot information to a file in addition to the screen. Screen graphics is faster when no plot file is made, but a plot file is necessary if you plan to make a hardcopy of the plot or mail it to yourself. (The format of the plot file depends on the printer device selected in the SelectDevices command.) Options are ENABLE or DISABLE. Default is DISABLE. Example: CRE,ENA TRIGGERTIME XAXIS - Selects whether to display seconds relative to the burst trigger time on the upper x axis (instead of universal time). The lower x axis will continue to show the universal time labels. If there were no burst trigger associated with the data being plotted, the upper x axis will show the universal time labels. Options are ENABLE or DISABLE. Default is DISABLE. Example: TRI,ENA FIDUCIAL MARK AT TRIGGERTIME - Selects whether to draw a vertical line on the plot at the time a BATSE burst trigger occurred. Options are ENABLE or DISABLE. Default is DISABLE. Example: FID,ENA OUTPRINT - Output device for PRINT command. Options are TERMINAL or PRINTER. Default is the terminal. Example: OUT,PRI (direct PRINT output to the Talaris 2090 printer) EMAIL ADDRESS - Address for mailing ASCII output. This parameter only appears after the user has issued the PRINT command and opted to mail the file to him/herself. On subsequent mailings for the PRINT command, this address will be used instead of prompting the user for an address each time. To mail to a different address, reset this parameter. Example: EMA,SDAC::KIM --------------------------------------------------------------------------- B. Flare Plot Program Commands: ACCUMULATE - Reads the input file selected and accumulates and plots the DISCLA data according to the parameter values selected by user. Saves arrays of input data at the finest time resolution, so subsequent plots of the same time interval, but different detectors, channels, sample average, log/linear option, etc. can be displayed using the GRAPH command which is much faster. ARCHIVEPLOT - Draw archive flare plot(s). This is quick because it uses the archive flare plot files rather than accumulating the data from the FDB file. The user is prompted for flare(s) to plot and can specify either a single flare or a range of flares. Format for screen plot (and plot file if CREATE is ENABLED) depends on selections made in the SelectDevices command. EXIT - Exit Flare Plot Program. FILELIST - Displays a list of the available BDB or FDB files depending on user's selection of DATABASE parameter. FLARELIST - Enters the BATSE Flare List Program to allow user to list flares in a selected time range. Type HELP in Flare List Program for help. GRAPH - Plot the (previously accumulated) DISCLA data according to the parameter values selected by the user. User must reACCUMULATE if a new start or end time is set, but can reGRAPH after changing detector, channel, log/linear, etc. options. HELP - Display this help file on screen. You will prompted for whether to mail the help file to yourself. HARDPLOT - Produces a hardcopy of the current DISCLA plot on the Talaris 800 laser printer. LIST - Display the menu. LOGFLARE - Allows user to enter a new flare into the BATSE flare catalog. Not available to remote users. MARKFLARE - Draws horizontal bars near the top of the current plot displaying any flare or background regions defined (as recorded in the BATSE flare catalog) within the time interval of the plot. MAILPLOT - Mail the last plot drawn. You will be prompted for your email address if you haven't already supplied it. OVERLAY - Allows user to overlay a trace on an existing plot. After displaying a graph via the ACCUMULATE or GRAPH command, the user may change detector, channel, and/or sample average options and OVERLAY the new data on the existing plot. The plot limits of the original plot will be used, so if the data doesn't fall between those limits, it will not be plotted. An alternate form of the command permits scaling of the overlaid data. Issue the command OVE,x. For linear plots, x will be added to the trace; for logarithmic plots, the trace will be multiplied by x. Example: OVE,2000. PLOTFLARE - User is prompted for flare number to plot. Finds input file containing this flare, accumulates the DISCLA data, and plots the background- subtracted aspect-corrected average of the two most sunward detectors (sum of channels 0-1) at a resolution of 1.024 s, and displays the flare and background time intervals recorded in the BATSE flare catalog. POINT - Allows user to determine the coordinates of a point on a plot. User positions the crosshairs at the desired location and presses one of the following: Tektronix: X - the X and Y values of the point are displayed. T - the time and Y value of the point are displayed. F - Exits point command. X Windows: Mouse button 1 - the X and Y values of the point are displayed. Mouse button 2 - the time and Y value of the point are displayed. Mouse button 3 - Exits point command. Regis: Not available. PRINT - Lists the times and Y values of the data displayed in the current plot for data points between times specified in XMIN and XMAX parameters. Output is directed to device specified in OUTPRINT parameter. The user has the option of mailing this information to him/herself. SAVE - Saves accumulated data in an IDL save/restore file called "discla_XXX.dat", "cont_XXX.dat", or "discsp_XXX.dat" on their top directory or [anonymous.input.batse] for users of the BATSE account. This file can be retrieved by remote users by using FTP into their account or through anonymous FTP (username: anonymous, and password: address). To bring the data into your IDL session, type RESTORE,'FSPLOT_SAVE'. The data saved in the file for DISCLA data are: SECONDS(n) - R*8 array containing seconds since 79/1/1,0 for each data point in DISCLA array. DISCLA(6,8,n) - R*4 array containing livetime-corrected counts/sec for 6 channels, 8 LAD's, and n time intervals. MAXINDEX - Highest index into SECONDS and DISCLA array used. COS8(8) - R*4 array containing the cosine of the angle between each LAD and the Sun. SELECTDEVICES - Enters a menu that allows user to select screen and printer output device formats. Options for screen format are X Windows, Tektronix, and Regis. Your machine must be capable of handling the format you choose. You may select X Windows only if you supplied the display node when prompted at the beginning of this session. Options for printer format are Tektronix and PostScript. The selected format will be used for the plot file if CREATE is set to ENABLE before drawing the plot. TYPEFLARE - User is prompted for flare number. Information on this flare is extracted from the BATSE flare catalog and printed on the terminal. XY0 - Resets the XMIN, XMAX, YMIN, and YMAX plotting limits to 0.0 for autoscaling. ZOOM - Allows user to zoom in on smaller section of the current plot. User positions the crosshairs at desired lower left corner, presses X (for Tektronix, mouse button 1 for X windows and Regis), then positions the crosshairs at desired upper right corner, and presses X (for Tektronix, mouse button 1 for X windows and Regis). This zoomed-in box is then graphed. The coordinates of the corners are stored in the XMIN, XMAX, YMIN, and YMAX parameters. --------------------------------------------------------------------------- (This information is stored in file BATSE_DATA:HELP_FSPLOT.TXT)