| calc_factors | xray.xspatial.eintools | calc_factors |
calc_factors -- calculate the background factors for a BKFAC table
calc_factors qpoefile bkfacfile pi_band src_cts [defmaps bemap dsmap]
The task calc_factors fills in the BEFAC and DSFAC columns of a background factors table (output from bkfac_make ). These values represent the bright Earth and deep survey weights to use in creating a final rotated background map.
Each row of the background factors table represents a group of times during which the aspect was considered constant. The deep survey weight for that group is simply the ratio of the livetime of that group with the livetime of the deep survey map:
DSFAC = (GP_LT / DS_LT)
The bright Earth factor for a particular group is as follows:
1 GP_LT
BEFAC = ------ { GP_CTS - ------- * SRC_CNTS - DSFAC * DS_CTS }
BE_CTS LIVE_TM
Here, BE_CTS and DS_CTS are the bright Earth and deep survey map counts, GP_LT and LIVE_TM are the livetimes of the group and of the input image, SRC_CNTS is the number of counts in the image due to sources, and GP_CTS is the number of counts which arrived during that group (stored as PI_CTS in the BKFAC). If the group livetime is short (under "min_grp_time" seconds), this task will recalculate GP_CTS to be as follows:
GP_CTS = (GP_LT/LIVE_TM)*IM_CTS
Here, IM_CTS is the number of counts in the input image in the specified PI band and with the bright edge filter and any other user-specified filters applied. This calculation is used to remove potential statistical anomolies in the photon counts. (Note: this will not actually change the table.) The bright Earth factor might be negative.
If the PI band in use is one of soft, hard, or broad, the user may opt to use the default bright Earth and deep survey maps appropriate for that band. Otherwise, the user must enter pathnames for the input bright Earth and deep survey maps. (See "help making_be_ds_maps".)
The input qpoe file name. The extension ".qp" will be added to the file if there is no extension.
The background factors table to modify. If no root is given, the file name will be the root of the reference QPOE file followed by the "_bkfac.tab" suffix. If the user supplies a name without an extension, the default extension will be "_bkfac.tab".
The PI band which was used during bkfac_make. This can be any of "all", "soft", "hard", "broad", or some range of values, such as "1:5" or "4:6,12:14". The bands correspond to the following ranges: soft=2:4, hard=5:10, broad=2:10, all=0:15. The bands can be abbreviated ("s", "h", etc.).
The number of counts in the image due to sources. This can be calculated with the task src_cnts .
If the PI band is one of "hard", "soft", or "broad", and if this parameter is YES, the task will use the appropriate default bright Earth and deep survey maps from the eintoolsdata$ directory. (Note: the default deep survey map is the sum of three maps at different BALs, with an average BAL of 15.2.)
If not using the default bright Earth map, the user must provide the pathname of the appropriate bright Earth map.
If not using the default deep survey map, the user must provide the pathname of the appropriate bright Earth map.
Pathname for the default bright Earth map for the hard band.
Pathname for the default deep survey map for the hard band.
Pathname for the default bright Earth map for the soft band.
Pathname for the default deep survey map for the soft band.
Pathname for the default bright Earth map for the broad band.
Pathname for the default deep survey map for the broad band.
The bright edge region to be applied to BE and DS images. This is meant to screen out the bright edges in unscreened data. This region must describe the identical area as the bright edge filter parameter below, br_edge_filt.
The bright edge filter to be applied to the QPOE file. The default corresponds to the standard "screened" area (3/4 degrees), and will screen out the bright edges in unscreened data. If you modify this filter, be sure to also modify the br_edge_reg parameter in any other tasks run in eintools .
If the livetime of a row in the background factors table is above this threshold, we are confident of the PI_CTS column. Otherwise, the counts for this group are recalculated as described above.
The display level. A setting of 0 should output no display (besides warnings), while settings above 3 are only useful for debugging.
This task may produce warnings about the background factors table.
The PI band used to create the BKFAC table differs from the one requested.
The bright Earth map is for a different PI band than the one requested.
The QPOE used to make the BKFAC table had a different nominal RA & DEC than the current QPOE file.
The deep survey map is for a different PI band than the one requested.
The sum of the LIVTI values in the BKFAC table should be close to the exposure time of the QPOE file times the dead-time correction. This warning is given if the difference is larger than 1.0 seconds. There are several causes for this difference.
Revision 0 QPOE files are missing .32 seconds for each BLT record; thus these missing seconds will accumulate and form minor differences.
Revision 0 and 1 QPOE files have small discrepencies between BLT and GTI records on the order of 41.0 seconds. For very long QPOE files, this accumulated difference may be quite large (over 1000 seconds).
On the other hand, the user may have created the BKFAC table for a different QPOE file or with a different time filter. If there is a large difference here, the user should check this possibility.
The sum of the PI_CTS counts in the BKFAC table should be close to the image counts in the QPOE file (with the PI band requested and the bright edge filter). This warning is given if the difference is larger than one count. If the previous warning (about livetime) is displayed, then probably this difference is caused by photons which fell during the missing times. The user may also have created the BKFAC table with a different filter on the QPOE than was used for this task. Having different PI bands will cause this warning as well.
Use calc_factors to add BEFAC and DSFAC columns to a previously made background factors table.
ei> bkfac_make
input QPOE file [root.qp]: xdata$snr.qp
output background factor table [root_bkfac.tab] (.):
PI band (all): broad
Created bkfac table ./snr_bkfac.tab with 1 row(s).
ei> calc_factors
input QPOE file [root.qp]: xdata$snr.qp
background factor table [root_bkfac.tab] (.):
PI band (all): broad
input source counts: 3691.25
use default bright Earth and deep survey maps? (yes):
WARNING: Total counts in the background factors table (20417.00000)
do not match the number of counts in the qpoe file (20420.00000).
Added background factors to table ./snr_bkfac.tab.
ei> tprint snr_bkfac.tab prparam+
Table snr_bkfac.tab Wed 11:13:04 06-Apr-94
RA_NOM r 344.7319
DEC_NOM r 58.61319
RCTYP1 t RA--TAN
RCTYP2 t DEC-TAN
RCRPX1 d 512.
RCRPX2 d 512.9999999999999
RCDLT1 d -0.002222222000000002
RCDLT2 d 0.002222222000000002
PIBAND t 2:10
COMMENT1 t This background factors table is an intermediate file used
COMMENT2 t in creating a rotated background image in the EINTOOLS
COMMENT3 t package. See the help page for BKFAC_MAKE for more
COMMENT4 t information.
HISTORY t BKFAC_MAKE: xdata$snr.qp -> ./snr_bkfac.tab
BECTS d 4766130.999999999
DSCTS d 664711.9626464844
DSTIME d 501591.0000000001
(row) BEFAC DSFAC LIVTI RCRVL1
sec pix
1 0.0023262 0.0084827 4254.85852 344.74826
(row) RCRVL2 RCROT2 PI_CTS
pix deg counts
1 58.61328 51.48015 20417.00
This task takes under 5 seconds on a Sparc for a background factors table with one row. It takes under 30 seconds for a table with 30 rows.
See bkfac_make for information on how the background factors table is generated.
See src_cnts for a task on calculating the counts due to sources in the image.
See rbkmap_make for information on how this task is used to generate rotated background maps.
Use "help making_be_ds_maps" for more information on creating deep survey and bright Earth maps for a specified band.
Use "help explain_bkfac" for more details on the contents of the background factors table.