STScI Logo

bkfac_make xray.xspatial.eintools


NAME · USAGE · DESCRIPTION · PARAMETERS · ALGORITHM ·  · TIME_REQUIREMENTS
BUGS · SEE_ALSO

NAME

bkfac_make -- create background factors table from Einstein QPOE file

USAGE

bkfac_make qpoefile bkfacfile pi_band

DESCRIPTION

The task bkfac_make is the first step in creating a complete background factors table for an Einstein IPC QPOE file. This task will read in the BLT information from the QPOE file and group together aspect records which are "close" and write them out to the table. The task will take into account any time filter placed on the QPOE file.

Because the aspect may have a high variance, the default option is to first find the average aspect for each OBI (i.e., HUT) of the QPOE file. For Revision 1 IPC QPOE files, each good time interval (in the ALL_GTI extension) stores the OBI number it is associated with. For Revision 0 IPC QPOE files, there is no OBI information, so this task will simply consider each GTI record as a separate OBI. (Note: The command qplist will not display the OBI information in the ALL_GTI extension. The user can use qp2fits and strfits to look at all the extensions within a QPOE file.)

The average aspects are then grouped together (using the tolerance parameter max_off_diff), then written out to the table in a WCS format. The columns this task fills in are as follows:

LIVTI: The livetime for this group of aspects.

RCRVL1,RCRVL2,RCROT2: WCS information describing the aspect. (See the "explain_bkfac" help file for more information.)

PI_CTS: The number of image counts in the specified PI band for this row.

This task will leave the BEFAC and DSFAC columns undefined, to be filled in by the task calc_factors .

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 = output bkfac table [root_bkfac.tab]

The output background factors table. If no root is given, the output 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 to use for generating the PI_CTS column. 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.).

(use_obi = yes) [boolean]

Should this algorithm generate an average aspect for each OBI?

If "yes", this task will first find the average aspect for each OBI, then attempt to group "close" average aspects together to form the rows of the BKFAC table. There should be little aspect information lost with this method, since most of the OBI is spent at the same location.

If "no", this task will use all of the aspect records when grouping. This second method will be more accurate, but also more time-consuming during be_ds_rotate since more rows for the BKFAC table will be created. (See below for more information on how this parameter affects the algorithm.)

(gti_ext = "") [string]

The GTI extension to use with the OBI information. (This parameter is only needed if the use_obi parameter is "yes".) If the string is empty, this task will use the default extensions: "GTI" for Revision 0 files, "ALLGTI" for others.

(obi_name = "obi_num") [string]

The name of the OBI field in the GTI extension. If this field can not be found in the GTI, then each GTI will be considered a separate OBI. The field is expected to be an integer, where two good time intervals in the same OBI will have the same OBI value.

(br_edge_filt = "detx=287:738,dety=287:738")

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 .

(max_off_diff = 1.) [double]

This is the total number of pixels allowed when considering grouping together aspect offsets. For example, if this parameter is set to 1.0 pixels and two aspect offsets are aspx,aspy=(0.8,1.3) and aspx,aspy=(0.1,2.1), those two aspect records would definitely be in different groups. The aspect roll offset is also used in this calculation -- see the parameter "dist_to_edge".

(dist_to_edge = 150.0) [double]

The distance from the center to the edge of the field, in pixels. This is used to determine approximately how many pixels the edge of the field is moved by a small rotational change in the field. For instance, a change of 0.0067 radians in aspect roll offset produces a difference of at least one pixel at the edge of the field (assuming the distance to the edge is 150.0 pixels).

(clobber = no) [boolean]

OK to overwrite the existing output file?

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

ALGORITHM

The aspect information within the BLT records contains four relevant quantities: aspect x offset (aspx), aspect y offset (aspy), aspect roll offset (aspr), and nominal roll (roll). These aspect values are averaged and grouped together, following an algorithm similar to one used by the Einstein Level One Processing file ibkgd_map/group_huts.f.

First, all BLT records are time filtered using the current deffilt of the QPOE and any time filters added on the command line.

If "use_obi" is set to "yes", we then calculate the average aspect for each OBI. We read in the time intervals corresponding to each OBI from the proper GTI extension. (For Revision 0 QPOE files there is no OBI information; we thus assign each GTI record to be an OBI.) For each OBI we find the "good" BLT records intersecting the OBI time intervals and find the weighted average of aspect offsets. A "good" BLT record is one with quality 1 or 2. If there are no "good" BLT records within the OBI, the average aspect offsets are set to zero. (The nominal roll is expected to not change during the OBI; if it does, an error will result.)

We then group "close" average aspect records together. If "use_obi" is set to "no", we simply treat each BLT record as a separate aspect record. Two sets of aspect offset records are considered "close" if they meet the following two conditions. The nominal rolls (roll[1] and roll[2]) must match exactly, and the following expression must be true:

 (( aspx[1]-aspx[2] )**2 + ( aspy[1]-aspy[2] )**2) + 
      abs( dist_to_edge * tan( aspr[1]-aspr[2] ))  <= max_off_diff

Each group is assigned to have the aspect offset of the first aspect record which was placed in the group. To determine if an aspect record falls into this group, it is compared against the group's assigned aspect. If an aspect record doesn't fall into any group, a new group is formed.

The final livetime of a group (LIVTI) is calculated by summing the aspect records' durations and multiplying by the QPOE's dead time correction (DTCOR). The QPOE counts for each group (PI_CTS) is defined by finding the number of photons within the specified PI range and within the bright edge filter which fell during the time intervals of the group. We also apply any further filtering placed on the QPOE on the command line.

Note that we are performing several intersections of time intervals: the BLT records, the QPOE deffilt, the user-specified time filter, and the GTI record used to find the OBI intervals. The sums of the PI_CTS counts should add up to the total counts in the QPOE (in the PI band and with the bright edge filter any other user-specified filters). Similarly, the sum of the group livetimes should be close to the exposure time of the QPOE (including any user- specified filters) multiplied by the dead time correction. Differences may come from discrepencies between the BLT records and GTI records. (For instance, for Revision 0 IPC QPOE files, each BLT record is missing .32 seconds. Other BLT records in both Revision 0 and Revision 1 files may be missing up to 41 seconds.)

Each row is then converted into a WCS-style format, describing the map between PROS detector coordinates and the final sky coordinates described by the aspect row and the QPOE WCS information.

EXAMPLES

1. Use bkfac_make to calculate the background factors table for the broad band of a QPOE file from an Einstein unscreened file.

ei> bkfac_make
input QPOE file [root.qp]: i196.qp
output background factor table [root_bkfac.tab] (.): 
PI band (all): broad

Created bkfac table ./i196_bkfac.tab with 2 rows.
ei> tprint i196_bkfac.tab prparam+
  Table i196_bkfac.tab  Tue 15:25:59 01-Mar-94

RA_NOM   r 11.52499       
DEC_NOM  r 1.099999       
RCTYP1   t RA--TAN
RCTYP2   t DEC-TAN
RCRPX1   d 512.                     
RCRPX2   d 513.0000000000006        
RCDLT1   d -0.002222222276032004    
RCDLT2   d 0.002222222276032004     
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: i196.qp -> ./i196_bkfac.tab

(row)           BEFAC           DSFAC           LIVTI          RCRVL1
                                                  sec             pix

    1           INDEF           INDEF      2174.34979        11.52686
    2           INDEF           INDEF      3484.40408        11.52666

(row)          RCRVL2          RCROT2          PI_CTS
                  pix             deg          counts

    1         1.09748        66.89448         2752.00
    2         1.09956        64.52344         3742.00

2. Use bkfac_make to calculate the background factors table for the PI range "3:5" for a screened Einstein file.

ei> bkfac_make
input QPOE file [root.qp]: xdata$snr.qp
output background factor table [root_bkfac.tab] (.): 
PI band (all): 3:5

Created bkfac table ./snr_bkfac.tab with 1 row(s).

TIME REQUIREMENTS

This task takes under 10 seconds on a Sparc to create a background factors table from a QPOE file with 9 BLT records. It takes about 20 seconds for a QPOE file with 94 BLT records.

BUGS

Time filters might not be applied properly on the command line. It is safest to use qpcopy on the QPOE file before calling bkfac_make .

Very large QPOE files may cause bkfac_make to run out of memory. The user might try setting use_obi to no to workaround this bug.

The WCS information in the BKFAC table depends on the WCS information in the QPOE file. If this file has had its WCS information altered (i.e., with qplintran or wcsedit ) the BKFAC table may be inaccurate.

SEE ALSO

See calc_factors for information on how the bright Earth and deep survey factors are calculated for the background factors table.

See rbkmap_make for information on how this task is used to generate rotated background maps.

Use "help explain_bkfac" for more details on the contents of the background factors table.


Source Code · Search Form · STSDAS