HEADAS help file for burstbkgevt

NAME

burstbkgevt - Generate simulated background events based on input background lightcurve and spectra.

USAGE

burstbkgevt infile prespec postspec outroot

DESCRIPTION

burstbkgevt reads the background rate from a lightcurve and background spectra and generates an event file to span the interval sampled by the lightcurve where the energy channels to each event are assigned based on the background spectra. The event file may be used to extract the background spectrum within the burst interval.

The input lightcurve needs to have a time column, a background rate, and an error column. By default the task searches for columns named TIME, BKGRATE and ERROR, otherwise the parameters timecol, ratecol and errcol maybe used to specify the names of the columns. The lightcurve header must contain the keywords PHALCUT and PHAHCUT to specify the minimun and maximum channels over which the background rates where derived. If they are not found, the tasks assumes that the rates are derived from the all channels in the input spectra. The output lightcurve from burstfinder is compatible to the input lightcurve of burstbkgevt.

The spectral files are used to derive the channel number associated to an event. The task accepts up to two spectra that are input using parameters prespec and postspec. They may represent the pre-burst and post-burst background spectra and they are average within the task. A single spectrum may be input by setting either parameter to NONE (or blank). The spectral file has to have two columns with integer values corresponding to CHANNEL and COUNTS and must contain the full original channel range for a given detector.

The task assigns the number of events based on the bin rate and its error of the input lightcurve. If the user provides a positive value for the parameter stdv, this fixed value replaces the error column, and can be used if there is no error column. The error is also scaled by a multiplying factor stdv_mult. The time of each event is assigned randomly within the time bin. The channel for each event is assigned by randomly chosing from the weighted spectra and weight and the channel corresponding to that weight.

The output is an event file with the name outroot_simback.evt. If the input light curve has a GTI extension, this is copied to the output event file.

PARAMETERS infile [filename] Input lightcurve with columns for time and background rate. prespec [filename] Input for 1st spectral file, typically a pre-burst spectra. May be set to NONE (or blank) if no spectra file is defined. However, at least one of prespec or postspec must be set. If both are set, the task makes an averge of the two. postspec [filename] Input fro 2nd spectral file, typically a post-burst spectra. May be set to NONE (or blank). outroot [string] The root name of the output event file outroot_simback.evt. (timecol = "TIME") [string] The name of the column containing time intervals in infile. Default is TIME. (ratecol = "BKGRATE") [string] The name of the column containing the background rate in infile. Default is BKGRATE. (errcol = "ERROR") [string] The name of the column containing the background subtracted rate error in infile. Default is ERROR. Ignored if stdv is set to a positive value. (chancol = "CHANNEL") [string] The name of the column containing the channel number in the input spectra. Default is CHANNEL. (cntcol = "COUNTS") [string] The name of the column containing the counts in each spectral channel in the input spectra. Default is COUNTS. (destcol = "PI") [string] The name of the destination column for events, corresponding to the chancol input. Typical values might be PI (default) or PHA. Set to match chancol if left blank or set to NONE. (stdv=-999) [real] Set to a negative value (default is -999) to ignore and use scatter defined by errcol. If set to a positive value, this fixed value is used to define scatter in the background subtracted rate when generating simulated events. (stdv_mult=1) [real] A multiplicative factor to apply to the error when determining the amount of scatter. The default value is 1. (clobber = no) [boolean] Overwrites the existing output file if set to yes (yes/[no]). (chatter = 1) [integer, 0 - 3] Chatter level for output. Set to 0 to suppress output, or to 1 (default), 2, or 3 for increasing the chatter of the output. (debug = no) [boolean] Diagnostic output is printed out on the screen if set to yes (yes/[no]). (logfile = !DEFAULT [string]) Log filename. If set to DEFAULT, it uses the name of this task (i.e. burstbkgevt.log) and, if preceded by "!" will overwrite the file if it already exists. If set to NONE, no log file is created. (history = no) [boolean] If set to yes, add HISTORY keywords to the output FITS files that record the parameters used to create these files. Default is NO. (mode = ql) [string ql|hl|q] Mode to query the parameter file. Acceptable values include: "ql" (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden). EXAMPLES Use a lightcurve cgbm_20180411_sgm_083733_1h_user.lc which contains columns TIME, BKGRATE, and ERROR to define the time-dependent component of modeled events. Use a pre-burst spectra file cgbm_20180411_sgm_083733_1h_pre.pi and a post-burst spectra file cgbm_20180411_sgm_083733_1h_post.pi to define the spectral shape of the modeled background events. These spectra files contain columns CHANNEL and COUNTS. Record the results in cgbm_20180411_sgm_083733_1h_simback.evt, which has columns TIME and PI (the default value for destcol) and include HISTORY keywords to record the parameters used to generate the output FITS file. The GTI in cgbm_20180411_sgm_083733_1h_user.lc (if any) is copied to the output event file. Record a log file cgbmbackevt_20180411_sgm_083733_1h.log. If the log file exists, clobber it. burstbkgevt infile="cgbm_20180411_sgm_083733_1h_user.lc" prespec="cgbm_20180411_sgm_083733_1h_pre.pi" postspec="cgbm_20180411_sgm_083733_1h_post.pi" outroot="cgbm_20180411_sgm_083733_1h" ratecol="BKGRATE" errcol="ERROR" chancol="CHANNEL" cntcol="COUNTS" chatter=3 history=yes logfile="\!cgbmbackevt_20180411_sgm_083733_1h.log" SEE ALSO burstfinder, cgbm_speclc, cgbm_bstgti, extractor LAST MODIFIED October 2024 (burstbkgevt 0.6b)