STScI Logo

imcnts xray.xspatial


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

NAME

imcnts -- count photons in the specified regions, with bkgd subtraction

USAGE

imcnts source region bkgd bkgdregion table

DESCRIPTION

imcnts counts photons in the specified source regions and reports the results for each region. Regions are specified using the ASCII region descriptor mechanism. Photons are also counted in the specified bkgd regions. The bkgds are either paired one-to-one with source regions or pooled and normalized by area (and optionally, by time and a user-specified norm factor), and then subtracted from the source counts in each region. Both the source and bkgd images can be filtered using an exposure map (and a threshold at which to accept pixels) if desired. Displayed results include the bkgd-subtracted counts in each region, as well as the error on the counts, the number of pixels in each region, and the surface brightness (cnt/pixel) calculated for each region. A STScI table file, with columns describing source (signal), background, background-subtracted source, errors, pixels, surface brightness, and profile can be optionally created. When annuli are specified in the source, the inner and outer radii are displayed and added to the STScI table output. When pie slices (angles) are specified in the source, the angles are displayed and added to the STScI table output.

PARAMETERS

source = "" prompt = source image file

The source image data file. This can be any valid IRAF image file, including X-ray QPOE files. In the latter case, all QPOE filters are available to the user. (It is not recommended that the QPOE MASK=<mask> filter be used directly in the QPOE filter specification because mask information will not be saved into the output file header in this case. An already existing mask should instead be input in the region parameter.) Also, note that imcnts only works on a 1-D or 2-D section of an image. Images of dimension greater than two must use the IRAF section specification to reduce the dimensionality of the data to be displayed.

region = "" prompt = source region descriptor

The ASCII region descriptor or pixel mask file name. If "none" (or any abbreviation of "none") or "" is specified, the entire field is used.

bkgd = "" prompt = background image file or cts/pixel

The background image data file or the counts/pixel bkgd density. If the null string is input, the source image file is used for bkgd. If a bkgd density is input (by specifying a float or integer), that value is multiplied by the area ratio (and other optional norm factors) to get background in each region. In this latter case, the background region parameter is not prompted for. If "none" or 0 is specified, no bkgd is used (i.e., 0 cts/pixel bkgd).

bkgdregion = "" prompt = bkgd region descriptor

The background region descriptor, if a bkgd file is specified (instead of a bkgd density). If a null region descriptor is input, the source descriptor is used. (In this latter case, the bkgd file must be different from the source file.) If "none" or "" is specified, the entire field is used.

table = "" prompt = root name for output file [root_cnt.tab]

Name of the STScI table file to which output is written. If the null string is input, the source image file name is used (with a "_cnt.tab" extension). The extension can be omitted in the specification. If "none" is input, no table file is created.

The columns of the table file are: region, raw (raw source counts), pixels (area of each region in pixels), bkgd (normalized bkgd counts), bkgderr (error on normalized bkgd), net (net bkgd-subtracted counts), neterr (error on net counts), cnt/pix (brightness), err/pix, and the profile (profile) consisting of integrated counts in each successive region divided by total counts.

(exposure = "NONE") [string]

The PLIO mask containing exposure information for the specified source image. If the null string is input, the name will have the same root as the source image file, with an extension of "_exp.pl". If "none" is input (the default), no exposure filtering is performed.

(expthresh = 0.) [real]

The percentage of total exposure required for a given source pixel to pass the exposure filter, (if an exposure mask is present). For example, if expthresh is 50.0, then only pixels whose exposure time is >= 50% will be used. An exposure threshold of 0% allows all photons to pass the exposure filter.

(err = "NONE") [string]

The origination of the source error. The value of this string can be either "none", in which case source error is estimated by assuming the counts result from a Poisson process (see "help explain_errors"); or the name of a "variance" image, that is, the name of a file containing the square of the errors for the source data. If the null string is input, the error file name will have the same root as the source data file, with an extension of "_err.imh". (Such a file is created by, for example, errcreate.)

(matchbkgd = no) [boolean]

If this is set to "true" or "yes", and if further the number of bkgd regions is equal to the number of source regions, then each bkgd region is matched individually with the corresponding source region. Otherwise (the default), the counts in all background regions are pooled and normalized by area (and by time and/or normalization factor if the user provides them) before subtraction from the source regions.

(bkgdexposure = "NONE") [string]

The PLIO mask containing exposure information for the specified bkgd image. If the null string is input, the name will have the same root as the bkgd image file, with an extension of "_exp.pl". If "none" is input (the default), no exposure filtering is performed.

(bkgdthresh = 0.) [real]

The percentage of total exposure required for a given bkgd pixel to pass the exposure filter, (if an exposure mask is present). For example, if expthresh is 50.0, then only pixels whose exposure time is >= 50% will be used. An exposure threshold of 0% allows all photons to pass the exposure filter.

(addbkgderr = yes) [boolean]

Boolean flag that determines whether the bkgd is used in the calculation of the error on the net counts.

(bkgderr = "NONE") [boolean]

The origination of the bkgd error. If bkgd data are taken from a file, then the value of this string can be either "none", in which case bkgd error is estimated by assuming the counts result from a Poisson process (see "help explain_errors"); or the name of a "variance" image, that is, the name of a file containing the square of the errors for the bkgd data. If the null string is input, the error file will have the same root as the bkgd data file, with an extension of "_err.imh". (Such a file is created by, for example, errcreate.)

If bkgd is a constant, then the value of this string is the bkgd error per pixel. The string value can be either "none", in which case 0.0 is used, or it can be a numeric value. In all cases, the addbkgderr flag must be true.

(timenorm = no) [boolean]

Boolean flag (taking on values "true" or "false") specifying whether or not the background should be normalized by the ratio of live times.

(normfactor = 1.) [real]

User-specified background normalization factor (default = 1.0). The background is multiplied by this factor before being subtracted from the signal.

(clobber = no) [boolean]

Boolean flag specifying whether or not the table file can be overwritten, if it already exists.

(display = 1) [0-5]

If greater than 0, this will report on the creation of the table file.

EXAMPLES

1. Extract the counts within a radius of 20 pixels from the center of the image i298.qp and subtract the background determined from the same image within an annulus of radii 50-100 pixels.


xs> imcnts xdata$snr.qp "cir (502 512 22)" "" "a(502 512 50 100)" .

title string = CIRCLE (502. 512. 22.)

SOURCE
image:          xdata$snr.qp
mask_name:      in memory
mask_type:      region
ref_file:       none
xdim:           1024
ydim:           1024
scale:          none
regions:        CIRCLE 502. 512. 22. 
no exposure correction

BACKGROUND
image:          xdata$snr.qp
mask_name:      in memory
mask_type:      region
ref_file:       none
xdim:           1024
ydim:           1024
scale:          none
regions:        ANNULUS 502. 512. 50. 100. 
no exposure correction

user normalization: 1.00
time normalization: 1.00
final normalization: 1.00

SOURCE DATA:
REGION          COUNTS          PIXELS          
1               4382            1513      

BKGD DATA:
REGION          COUNTS          PIXELS          
1               8656            23572     

Creating table output file: snr_cnt.tab
xs>

The table file snr_cnt.tab can be displayed using tprint.

2. Count up the photons in i296 using i296.pl as a mask. The regions in this mask are:

        annulus(449.74,409.2,0,100,n=5)&pie(449.74,409.2,0,360,n=3)

The bkgd is taken from the same file, in a circle far from sources.
The bkgd mask is called i296b.pl.
The output table file is named i296_cnt.tab.

cl> imcnts i296.qp i296.pl "" i296b.pl ""

SOURCE
image:          i296.qp
mask_name:      in memory
mask_type:      region
ref_file:       none
xdim:           1024
ydim:           1024
scale:          none
regions:        ANNULUS (449.74 409.20 0.00 100.00 n=5.00) &
		  PIE (449.74 409.20 0.00 360.00 n=3.00)
no exposure correction

BACKGROUND
image:          i296.qp
mask_name:      in memory
mask_type:      region
ref_file:       none
xdim:           1024
ydim:           1024
scale:          none
regions:        CIRCLE (650.00 650.00 50.00)
no exposure correction

user normalization: 1.00
time normalization: 1.00
final normalization: 1.00

SOURCE DATA:
REGION          COUNTS          PIXELS
1               1009            418
2               1472            1251
3               1923            2093
4               2245            2925
5               2539            3763
6               957             417
7               1113            1258
8               1415            2093
9               1415            2936
10              1254            3763
11              926             424
12              2253            1261
13              3833            2100
14              5007            2937
15              5351            3776

BKGD DATA:
REGION          COUNTS          PIXELS
1               2813            7825

BKGD-SUBTRACTED DATA:
REG   COUNTS     ERROR      BKGD       BERROR     PIXELS   CNT/PIX   ERR/PIX
PROFILE    RAD1    RAD2       ANG1       ANG2
1     858.73     31.8909    150.27     2.8332     418      2.0544    0.0763
0.1581     0.00    20.00      0.00       120.00
2     1022.28    39.2925    449.72     8.4793     1251     0.8172    0.0314
0.3463     20.00   40.00      0.00       120.00
3     1170.59    46.0896    752.41     14.1863    2093     0.5593    0.0220
0.5619     40.00   60.00      0.00       120.00
4     1193.50    51.3620    1051.50    19.8256    2925     0.4080    0.0176
0.7816     60.00   80.00      0.00       120.00
5     1186.24    56.4760    1352.76    25.5056    3763     0.3152    0.0150
1.0000     80.00  100.00      0.00       120.00
6     807.09     31.0643    149.91     2.8264     417      1.9355    0.0745
0.3375     0.00   20.00       120.00     240.00
7     660.76     34.4341    452.24     8.5267     1258     0.5252    0.0274
0.6138     20.00  40.00       120.00     240.00
8     662.59     40.2026    752.41     14.1863    2093     0.3166    0.0192
0.8909     40.00  60.00       120.00     240.00
9     359.54     42.5560    1055.46    19.9002    2936     0.1225    0.0145
1.0413     60.00  80.00       120.00     240.00
10    -98.76     43.6410    1352.76    25.5056    3763     -0.0262   0.0116
1.0000     80.00  100.00      120.00     240.00
11    773.58     30.5657    152.42     2.8739     424      1.8245    0.0721
0.0569     0.00   20.00       240.00     360.00
12    1799.68    48.2292    453.32     8.5470     1261     1.4272    0.0382
0.1893     20.00  40.00       240.00     360.00
13    3078.07    63.5264    754.93     14.2338    2100     1.4657    0.0303
0.4157     40.00  60.00       240.00     360.00
14    3951.18    73.5070    1055.82    19.9069    2937     1.3453    0.0250
0.7063     60.00  80.00       240.00     360.00
15    3993.57    77.4986    1357.43    25.5937    3776     1.0576    0.0205
1.0000     80.00  100.00      240.00     360.00

TIME REQUIREMENTS

The time required depends on the speed of the mask I/O, and is proportional to the number of photons being filtered. Also, if a region description is input rather than an already existing pixel mask, for source and/or bkgd region, the pixel mask must be created at run time. This only takes a few seconds for relatively simple masks. For complicated masks that one will use repeatedly, use plcreate first and input the plio mask directly instead of the ASCII region descriptor.

BUGS

If a region specification includes a "multi-annulus" or a "multi-pie" (as in example 2 above), it is a good idea not to have another specifier of the same shape class in the same command. The rad1 and rad2 columns in the table output are the inner and outer radii of the annulus derived from the last annulus specifier in the command, not necessarily the one with the accelerator. Similarly, the ang1 and ang2 columns are the beginning and ending angles of the pie slice derived from the last pie specifier in the command, not necessarily the one with the accelerator. The computations will be correct, but the table will be less informative than you may wish, and could be confusing. (Example 2 above does not suffer from this problem, and the table is not misleading.) See help regalgebra for information that may help you work around the problem.

SEE ALSO

Documentation on region filtering (help regions ) for a description of the spatial filter user interface.

Documentation on QPOE filtering (help qpoe ) for a description of the QPOE filter user interface.

Documentation on error calculation (help explain_errors ) for a description of the PROS error algorithm.

Documentation on file extensions (help extensions ) for a description of PROS file extensions.

Documentation on coordinates (help coords ) for a description of PROS coordinate conventions.


Source Code · Search Form · STSDAS