STScI Logo

rbkmap_make xray.xspatial.eintools


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

NAME

rbkmap_make -- create rotated background map for Einstein IPC QPOE file

USAGE

rbkmap_make qpoefile rbkmap pi_band srcfile src_cnts expfile defmaps [bemap...]

DESCRIPTION

The task rbkmap_make is the main task which will create a rotated background map for an Einstein IPC QPOE file using an algorithm derived from the Level One Processing code.

If a source file is given, it will use the task src_cnts to calculate the number of counts due to the sources, using the input exposure file as a spatial filter. If the exposure file does not exist, this task will create one using the task exp_make . If NONE is given for the source file, the user is prompted for the number of source counts.

This task then creates a background factors table (via bkfac_make and calc_factors ) and uses this table to determine how to weight and rotate the input bright Earth and deep survey maps (using be_ds_rotate ).

The creation of the background map will take into consideration any command line filtering of the QPOE file.

The script RBKMAP_MAKE runs the following tasks:

        EXP_MAKE   (if source file != NONE and no exposure mask exists)   
           |
           V
        SRC_CNTS   (if source file != NONE)
           |
           V
       BKFAC_MAKE
           |
           V
      CALC_FACTORS
           |
           V
      BE_DS_ROTATE --> output background map

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.

rbkmap = "" prompt = output rotated bkgd image [root_bkg.imh]

The output rotated background map. If no root is given, the output file name will be the root of the reference QPOE file followed by the "_bkg.imh" suffix. If the user supplies a name without an extension, the default extension will be "_bkg.imh".

pi_band = "all" prompt = PI band

The PI band for the final rotated background map. 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.).

srcfile = "" prompt = input source table [or NONE]

The table of sources, in physical coordinates. The only requirements for this table is that the columns containing the x and y coordinates for each source be labelled "X" and "Y". The output of ldetect would be appropriate, as would the source tables from the Einstein unscreened CDROM.

If "NONE" is entered, then the user will be prompted for the number of source counts.

src_cnts = 0. prompt = input source counts

[Only prompted for if srcfile is "NONE".]

The total number of counts in the image due to sources. If there are no sources, this value should be 0.0.

expfile = "" prompt = exposure PL mask [root_exp.pl]

[Only prompted for if srcfile is not "NONE".]

If the file named by this parameter does not already exist, this task will create one by running the task exp_make .

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 a default bright Earth map, this is the pathname of a user-created bright Earth map.

dsmap = "" prompt = input deep survey map

If not using a default deep survey map, this is the pathname of a user-created deep survey map.

(bkfac_tab = ".") [string]

The intermediate background factors table used to group similar (usually OBI averaged) aspect and bright Earth and deep survey weights. If no root is given (default "."), the output table 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". Note that because this is an intermediate file, it will automatically overwrite any previous BKFAC file.

(xscale = 1.0) [double]

Specifies how much the final image should be scaled in the X dimension. If the scaling is above one, the background map will be expanded; less than one, compressed. If xscale is left as 1.0, the final image will be the same size as the QPOE image, i.e. 1024 pixels wide. If xscale=2.0, this task will produce an image twice the width, i.e., 2048 pixels wide.

(yscale = 1.0) [double]

Specifies how much the final image should be scaled in the Y dimension. If the scaling is above one, the background map will be expanded; less than one, compressed. If yscale is left as 1.0, the final image will be the same size as the QPOE image, i.e. 1024 pixels high. If yscale=2.0, this task will produce an image twice the height, i.e., 2048 pixels high.

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

(use_obi = yes) [boolean]
[BKFAC_MAKE]

Should the background factors table be generated with 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 rotation, since more rows for the BKFAC table will be created. (See bkfac_make for more information on how this parameter affects the creation of the BKFAC table.)

(gti_ext = "") [string]
[BKFAC_MAKE]

The GTI extension of the QPOE file 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]
[BKFAC_MAKE]

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") [string]
[BKFAC_MAKE, CALC_FACTORS, SRC_CNTS]

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

(max_off_diff = 1.) [double]
[BKFAC_MAKE]

This is the total number of pixels allowed when considering grouping together aspect offsets in bkfac_make . For example, if the difference is 1.0 pixels and two aspect offsets are aspx,aspy=(0.8,1.3) and (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]
[BKFAC_MAKE]

The distance to the edge of the field, in pixels. This is used in conjunction with max_off_diff to determine if two sets of aspect are close during bkfac_make . The value is used to determine approximately how many pixels the edge of the field is moved by a small radial 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 (with the default distance of 150.0 pixels).

(br_edge_reg = "box 256.256.5 226 226") [string]
[CALC_FACTORS, BE_DS_ROTATE]

The bright edge region to be applied to deep survey and bright Earth maps. This parameter is used to screen out the bright edges in unscreened data. This region must describe the identical area as the bright edge filter parameter above, br_edge_filt.

(min_grp_time = 1000.) [double]
[CALC_FACTORS]

If the livetime of a row in the background factors table is above this threshold, we are confident of the PI_CTS column during the calculations of the weighting factors in calc_factors . Otherwise, the counts for this group are recalculated as described in calc_factors .

(catfile = ".") [file]
[EXP_MAKE]

This table is an intermediate file used to group together similar aspect during exp_make . If no root is given (default "."), the output table file name will be the root of the reference QPOE file followed by the "_cat.tab" suffix. If the user supplies a name without an extension, the default extension will be "_cat.tab". Note that because this is an intermediate file, it will automatically overwrite any previous CAT file.

(full_exp = no) [boolean]
[EXP_MAKE]

There are two sets of values for the IPC geometry in the geometry boundaries table. The first (specified with full_exp=no) is the standard spatial screening of the IPC geometry (3/4 degrees). The second (specified with full_exp=yes) is a larger screening, up to the boundaries of the geometry (1 degree). (This larger screening will include the bright spots of an unscreened IPC image). Note that the two different exposure maps are rotated and imbedded into a 1024x1024 image.

See the geom_bounds table for the particular values of the IPC geometry.

(aspx_res = 4.) [double]
[EXP_MAKE]

The aspect x offset resolution (in pixels) for the binning in exp_make . With a resolution of 4 pixels, aspect x offsets of -2.0 through 2.0 will be binned together, as will 2.0 through 6.0, etc.

(aspy_res = 4.) [double]
[EXP_MAKE]

The aspect y offset resolution (in pixels) for the binning in exp_make . With a resolution of 4 pixels, aspect y offsets of -2.0 through 2.0 will be binned together, as will 2.0 through 6.0, etc.

(aspr_res = 0.0087266463) [double]
[EXP_MAKE]

The aspect roll offset resolution (in radians) for the binning in exp_make . The default value corresponds to 0.5 degrees and will, for instance, bin together all aspect roll offsets between -0.25 and 0.25 degrees.

(cell_size = 4) [int]
[EXP_MAKE]

This parameter specifies the resolution of the final exposure mask. The mask will consist a series of nxn cells, each with the same exposure value. The user can request a finer cell_size (which will take longer), but should change the aspect x and y resolutions above as well.

(exp_max = 32767) [int]
[EXP_MAKE]

For the generated PL mask, this integer value will correspond to 100% exposure in the image. This is the default value used in other PROS tasks, such as qpspec .

(geom_bounds = "eintoolsdata$geom_bounds.tab) [file]
[EXP_MAKE]

This table contains information for the IPC geometry bounds for exp_make .

(src_rad = 22.5) [double]
[SRC_CNTS]

Source radius (in pixels). This is the size of the source circle to be used around each source in src_cnts .

(bkgd_ann_in = 37.5) [double]
[SRC_CNTS]

Inner radius of background annulus. This is used to generate background counts for each image in src_cnts .

(bkgd_ann_out = 45.) [double]
[SRC_CNTS]

Outer radius of background annulus. This is used to generate background counts for each image in src_cnts .

(soft_cmsc = 1.09) [double]
[SRC_CNTS]

Circle mirror scattering correction for Einstein soft band. The value comes from Einstein Level One Processing file IPC.PF.

(soft_cprc = 1.09) [double]
[SRC_CNTS]

Circle point response correction for Einstein soft band. The value comes from Einstein Level One Processing file IPC.PF.

(hard_cmsc = 1.14) [double]
[SRC_CNTS]

Circle mirror scattering correction for Einstein hard band. The value comes from Einstein Level One Processing file IPC.PF.

(hard_cprc = 1.00) [double]
[SRC_CNTS]

Circle point response correction for Einstein hard band. The value comes from Einstein Level One Processing file IPC.PF.

(xsample = 1.0, ysample = 1.0) [real]
[BE_DS_ROTATE]

The coordinate surface subsampling factors. The coordinate surfaces are evaluated at every xsample-th pixel in x and every ysample-th pixel in y. Transformed coordinates at intermediate pixel values are determined by bilinear interpolation in the coordinate surfaces. If the coordinate surface is of high order setting these numbers to some reasonably high value is strongly recommended.

(interpolant = "linear") [string]
[BE_DS_ROTATE]

The interpolant used for rebinning the image. The choices are the following.

nearest
Nearest neighbour.
linear
Bilinear interpolation in x and y.
poly3
Third order polynomial in x and y.
poly5
Fifth order polynomial in x and y.
spline3
Bicubic spline.
(boundary = "constant") [string]
[BE_DS_ROTATE]

The choices are:

nearest
Use the value of the nearest boundary pixel.
constant
Use a user supplied constant value.
(constant = 0.0) [real]
[BE_DS_ROTATE]

The value of the constant for boundary extension.

(nxblock = 256, nyblock = 256) [int]
[BE_DS_ROTATE]

If the size of the output image is less than nxblock by nxblock then the entire image is transformed at once. Otherwise the output image is computed in blocks nxblock by nxblock pixels.

(clobber = no) [boolean]

OK to overwrite the existing output background map?

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

EXAMPLES

1. Use rbkmap_make to create a broad-band background map for an Einstein IPC image. We use a user-specified source list and the default bright Earth and deep survey maps.

ei> tcreate
name of table to be created: snr_src.tab
name of file containing column descriptions (STDIN): 
name of file containing data (STDIN): 
Give column definitions (name, datatype, print format, units)
 ... then newline & EOF to finish.
x r
y r

Give table data ... then newline & EOF to finish.
512.0 504.0

ei> rbkmap_make
input QPOE file [root.qp]: xdata$snr.qp
output rotated background image [root_bkg.imh] (.): 
PI band (all): broad
input source table [or NONE]: snr_src.tab
exposure PL mask [root_exp.pl] (.): 
use default bright Earth and deep survey maps? (yes): 

Using bright Earth map eintoolsdata$bemapb and deep survey map
eintoolsdata$dsmapb.

Creating exposure map ./snr_exp.pl for QPOE file xdata$snr.qp...

Created constant aspect table ./snr_cat.tab with 1 row(s).

Created exposure file ./snr_exp.pl.

Calculating source counts...

Found source counts of image to be 3691.25.

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

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.

Creating final background map...

This task will be rotating 1 image(s).

Rotating image # 1...

Scaling background map to (1.00,1.00)...

Created rotated background map ./snr_bkg.imh.

2. Use rbkmap_make to create a background map for the soft band of an IPC QPOE file. We use a list of sources detected with the Level One Processing with the LDETECT algorithm. This list is created by using tselect on the CPTS table extracted from the "sd" FITS file found on the IPC unscreened CDROM. (In this case, we have already run ecd2pros to extract the CPTS table from the "sd" FITS file.)

ei> tselect
Input tables: i352CPTS.tab
Output tables: i352_src.tab
Expression used for selection: METHOD="L" && BAND="S"
ei> rbkmap_make
input QPOE file [root.qp]: i352.qp
output rotated background image [root_bkg.imh] (.): 
PI band (all): soft
input source table [or NONE]: i352_src.tab
exposure PL mask [root_exp.pl] (.): 
use default bright Earth and deep survey maps? (yes): 

Using bright Earth map eintoolsdata$bemaps and deep survey map
eintoolsdata$dsmaps.

Creating exposure map ./i352_exp.pl for QPOE file i352.qp...

Created constant aspect table ./i352_cat.tab with 9 row(s).

Created exposure file ./i352_exp.pl.

Calculating source counts...

Found source counts of image to be 955.01.

Created bkfac table ./i352_bkfac.tab with 3 row(s).

Added background factors to table ./i352_bkfac.tab.

Creating final background map...

This task will be rotating 3 image(s).

Rotating image # 1...
Rotating image # 2...
Rotating image # 3...

Scaling background map to (1.00,1.00)...

Created rotated background map ./i352_bkg.imh.

TIME REQUIREMENTS

This task takes under 3 minutes on a Sparc for a QPOE file with 3 BLT records and one source.

BUGS

Time filters might not be applied properly on the command line. It is safest to use qpcopy on the QPOE file before calling rbkmap_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 and CAT tables 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.

The algorithm for generating background maps does not take into account particle backgrounds. Thus if the observation has high particle backgrounds, this task will assume the excess counts are from bright Earth and will potentially generate a background map with an inaccurate spectrum.

SEE ALSO

See exp_make for more information on making the exposure map, src_cnts for more information on generating the source counts, bkfac_make and calc_factors for algorithms used to generate the background factors table, and be_ds_rotate for more information on how the final background map is generated.

See the tasks be_ds_rotate and calc_factors for probable interpretations of warning messages displayed by this task.

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

Use "help explain_cat" for more information on the contents of constant aspect tables.

Use "help making_be_ds_maps" for more information on creating deep survey and bright Earth maps for a specified band.


Source Code · Search Form · STSDAS