STScI Logo

calc_factors xray.xspatial.eintools


NAME · USAGE · DESCRIPTION · PARAMETERS · WARNINGS · EXAMPLES
TIME_REQUIREMENTS · SEE_ALSO

NAME

calc_factors -- calculate the background factors for a BKFAC table

USAGE

calc_factors qpoefile bkfacfile pi_band src_cts [defmaps bemap dsmap]

DESCRIPTION

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".)

PARAMETERS

qpoefile = "" prompt = input QPOE file [root.qp]

The input qpoe file name. The extension ".qp" will be added to the file if there is no extension.

bkfacfile = "" prompt = input bkfac table [root_bkfac.tab]

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".

pi_band = "all" prompt = PI band

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.).

src_cnts = 0. prompt = input source counts

The number of counts in the image due to sources. This can be calculated with the task src_cnts .

defmaps = yes prompt = use default BE and DS maps?

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.)

bemap = "" prompt = input bright Earth map

If not using the default bright Earth map, the user must provide the pathname of the appropriate bright Earth map.

dsmap = "" prompt = input deep survey map

If not using the default deep survey map, the user must provide the pathname of the appropriate bright Earth map.

(def_be_hard = "eintoolsdata$bemaph") [string]

Pathname for the default bright Earth map for the hard band.

(def_ds_hard = "eintoolsdata$dsmaph") [string]

Pathname for the default deep survey map for the hard band.

(def_be_soft = "eintoolsdata$bemaps") [string]

Pathname for the default bright Earth map for the soft band.

(def_ds_soft = "eintoolsdata$dsmaps") [string]

Pathname for the default deep survey map for the soft band.

(def_be_broad = "eintoolsdata$bemapb") [string]

Pathname for the default bright Earth map for the broad band.

(def_ds_broad = "eintoolsdata$dsmapb") [string]

Pathname for the default deep survey map for the broad band.

(br_edge_reg = "box 256.256.5 226 226") [string]

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.

(br_edge_filt = "detx=287:738,dety=287:738") [string]

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 .

(min_grp_time = 1000.) [double]

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.

(display = 1) [int]

The display level. A setting of 0 should output no display (besides warnings), while settings above 3 are only useful for debugging.

WARNINGS

This task may produce warnings about the background factors table.

"WARNING: BKFAC table PI band differs"

The PI band used to create the BKFAC table differs from the one requested.

"WARNING: Bright Earth PI band differs"

The bright Earth map is for a different PI band than the one requested.

"WARNING: Nominal RA & DEC don't match between BKFAC & QPOE"

The QPOE used to make the BKFAC table had a different nominal RA & DEC than the current QPOE file.

"WARNING: Deep Survey Earth PI band differs"

The deep survey map is for a different PI band than the one requested.

"WARNING: Total livetime in the BKFAC table does not match qpoe..."

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.

"WARNING: Total counts in the BKFAC table does not match qpoe..."

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.

EXAMPLES

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

TIME REQUIREMENTS

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 ALSO

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.


Source Code · Search Form · STSDAS