| imcnts | xray.xspatial | imcnts |
imcnts -- count photons in the specified regions, with bkgd subtraction
imcnts source region bkgd bkgdregion table
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.
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.
The ASCII region descriptor or pixel mask file name. If "none" (or any abbreviation of "none") or "" is specified, the entire field is used.
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).
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.
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.
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.
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.
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.)
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.
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.
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.
Boolean flag that determines whether the bkgd is used in the calculation of the error on the net counts.
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.
Boolean flag (taking on values "true" or "false") specifying whether or not the background should be normalized by the ratio of live times.
User-specified background normalization factor (default = 1.0). The background is multiplied by this factor before being subtracted from the signal.
Boolean flag specifying whether or not the table file can be overwritten, if it already exists.
If greater than 0, this will report on the creation of the table file.
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
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.
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.
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.