batphasimerr HEADAS help file

NAME

batphasimerr - estimate statistical errors for simulated BAT spectrum

USAGE

batphasimerr infile exposure bkgfile eboundfile

DESCRIPTION

batphasimerr transforms an XSPEC "fake" BAT spectrum into a more realistic estimate of the instrument response. This is especially useful for making proposals or estimating the feasibility of a BAT project. Since the BAT is a background-dominated instrument, it is important to use this tool to get a better handle on the statistical uncertainties.

batphasimerr operates on the spectrum file "in-place." It converts a counts spectrum to a rate spectrum, if necessary. It estimates the background rate using the user-specified background file, and then the statistical uncertainty. Finally, it randomizes the rate, using that the statistical uncertainty.

The user should first make an XSPEC "fake" spectrum. Please use the procedure described below. There are really only three differences: randomization should be set to "NO"; the exposure should be set to "1E9"; and the batphasimerr task should be run to adjust the spectrum after the fakeit step.

Here are the step by step instructions.

Within XSPEC, choose the desired model and parameters as you would for any spectral simulation.
Enter:
fakeit none
Enter the name of the response matrix. For simulations, you can use the sample response matrix in the BAT CALDB area. There is no need to enter an ARF file, since BAT does not use ARFs.
To the prompt, Use randomization, answer NO. batphasimerr will perform the randomization at a later step.
Enter whatever prefix and/or output file name that you wish.
For the exposure and correction norm prompt, enter "1e9, 1".
Execute the following command:
batphasimerr fake_spect.fak exposure bkg_det.pha response_matrix.rsp
where fake_spect.fak is your fake spectrum, exposure is your desired exposure, and response_matrix.rsp is the response matrix used to make the fake spectrum.
After processing, you should be able to load the fake spectrum with the command:
data fake_spect.fak

PARAMETERS

infile [filename]: Input/output spectral file. The file should be an OGIP-standard type I spectral file produced by XSPEC/fakeit as described above. The file is modified in place. Note that if necessary, any COUNTS column will be converted to RATE, and additional columns will be added.
exposure [real]: Exposure time in seconds. Note that this is the field where you enter the desired BAT exposure; the exposure you enter in XSPEC should be a token large number like 1 billion seconds.
bkgfile = "CALDB" [string]: Background file. This file should give the approximate background count rate conditions. The file should have a BKG_DET column, containing the average background count rate per detector, and an EBOUNDS extension giving the energy binning. The string "CALDB" is allowed, to use the "typical" BAT background spectrum.
eboundfile [file]: Name of the response matrix used to produce the fake spectrum. Only the EBOUNDS extension is used.
(pcodefr = 1.0) [real]: Partial coding fraction of the source. Any number between 0.0 and 1.0. Small numbers indicate a source farther off axis.
(alpha = 0.28) [real]: BAT imaging efficiency factor. This depends on the detector geometry, and is for expert use only.
(chatter = 2) [integer, 0 - 5]: Controls the amount of informative text written to standard output.

EXAMPLES

Here is an example XSPEC session showing how a power law model can be simulated (photon index 2.05, normalization 10.5). The desired exposure is 10 ks. The response matrix was taken from CALDB. The background rates were taken from bkg_det.fits.

1. Create the model in XSPEC.

XSPEC>model pow
  Model:  powerlaw<1>
Input parameter value, delta, min, bot, top, and max values for ...
                   1      0.01        -3        -2         9        10
1:powerlaw:PhoIndex>2.05
                   1      0.01         0         0     1E+24     1E+24
2:powerlaw:norm>10.5
  ---------------------------------------------------------------------------
  ---------------------------------------------------------------------------
  Model:  powerlaw<1>
  Model Fit Model Component  Parameter  Unit     Value
  par   par comp
    1    1    1   powerlaw   PhoIndex            2.05000     +/-   0.00000
    2    2    1   powerlaw   norm                10.5000     +/-   0.00000
  ---------------------------------------------------------------------------
  ---------------------------------------------------------------------------

2. Make a fake spectrum.

XSPEC>fakeit none
For fake data, file #   1 needs response file: swbresponse20030101v007.rsp 
              ... and ancillary response file: (blank)
Use randomization in creating fake data? (y) NO
Input optional fake file prefix (max 4 chars): xxx
 Fake data filename (xxxswbresponse20030101v007.fak) [/ to use default]: crab.fak
 Exposure time, correction norm  (1, 1): 1E9, 1
 Net count rate (cts/s) for file   1  7.8508E-02+/-  8.8605E-06
   using response (RMF) file...       swbresponse20030101v007.rsp
 Chi-Squared =     1.5999669E-04 using    80 PHA bins.
 Reduced chi-squared =     2.0512396E-06 for     78 degrees of freedom
 Null hypothesis probability =  1.00

3. Estimate BAT uncertainties.

XSPEC>batphasimerr crab.fak 10000.0 bkg_det.pha swbresponse20030101v007.rsp
batphasimerr 1.0
--------------------------------------------------------
           Spectrum file: crab.fak
--------------------------------------------------------
  File modified in place: crab.fak
--------------------------------------------------------

4. Load the simulated spectrum back into XSPEC.

XSPEC>data crab.fak
 Net count rate (cts/s) for file   1  7.8351E-02+/-  8.4527E-05
   using response (RMF) file...       swbresponse20030101v007.rsp
   1 data set is in use
 Chi-Squared =      71.96701     using    80 PHA bins.
 Reduced chi-squared =     0.9226540     for     78 degrees of freedom
 Null hypothesis probability = 0.671

5. Proceed with your simulation.

LAST MODIFIED