regcnts [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_value]
-b [n] # bin factor for binary tables (make in-memory image smaller)
-c [str] # data slice ('*:*:1428') or cube ('all') specification string
-e [efile] # error filename (def: stderr)
-g # output using nice g format
-G # output using %.14g format (maximum precision)
-j # output using JSON format (def: table format)
-m # match individual source and bkgd regions
-o [ofile] # output filename (def: stdout)
-p # output in pixels, even if wcs is present
-r # output inner/outer radii (and angles) for annuli (and pandas)
-s # output summed values
-t # output in strict starbase/rdb format
-z # output regions with zero area
The regcnts program counts photons in the specified source regions and reports the results for each region. Regions are specified using the Spatial Region Filtering mechanism. Photons are also counted in the specified bkgd regions applied to the same data file or a different data file. (Alternatively, a constant background value in counts/pixel**2 can be specified.) The bkgd regions are either paired one-to-one with source regions or pooled and normalized by area, and then subtracted from the source counts in each region. Displayed results include the bkgd-subtracted counts in each region, as well as the error on the counts, the area in each region, and the surface brightness (cnts/area**2) calculated for each region.
The first argument to the program specifies the FITS input image or binary table. The optional second argument is the source region descriptor. If no region is specified, the entire field is used.
The background arguments can take one of two forms, depending on whether a separate background file is specified. If the source file is to be used for background as well, the third argument can be either the background region or a constant value denoting background cnts/pixel. Alternatively, the third argument can be a background data file and the fourth argument the background region. If no third argument is specified, a constant value of 0 is used (i.e., no background).
In summary, the following command arguments are valid:
$ regcnts sfile # counts in source file $ regcnts sfile sregion # counts in source region $ regcnts sfile sregion bregion # bkgd reg. is from source file $ regcnts sfile sregion bvalue # bkgd reg. is constant $ regcnts sfile sregion bfile bregion # bkgd reg. is from separate file
For example, to extract the counts within a radius of 22 pixels from the center of the FITS binary table snr.ev and subtract the background determined from the same image within an annulus of radii 50-100 pixels:
$ regcnts snr.ev "circle(502,512,22)" "annulus(502,512,50,100)"
# source
# data_file: snr.ev
# arcsec/pixel: 8
# background
# data_file: snr.ev
# column units
# area: arcsec**2
# surf_bri: cnts/arcsec**2
# surf_err: cnts/arcsec**2
# background-subtracted results
reg net_counts error background berror area surf_bri surf_err
---- ------------ --------- ------------ --------- --------- --------- ---------
1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001
# source_region(s):
# circle(502,512,22)
# source_data
reg counts pixels
---- ------------ ---------
1 4382.000 1513
# background_region(s)
# annulus(502,512,50,100)
# background_data
reg counts pixels
---- ------------ ---------
all 8656.000 23572
The area units for the output columns labeled "area", "surf_bri"
(surface brightness) and "surf_err" will be given either in
arc-seconds (if appropriate WCS information is in the data file
header(s)) or in pixels. If the data file has WCS info, but you do not
want arc-second units, use the -p switch to force output in
pixels. Also, regions having zero area are not normally included in
the primary (background-subtracted) table, but are included in the
secondary source and bkgd tables. If you want these regions to be
included in the primary table, use the -z switch.
Note that a simple sed command will extract the background-subtracted results for further analysis:
$ cat regcnts.sed 1,/---- .*/d /^$/,$d $ sed -f regcnts.sed regcnts.out 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001
If separate source and background files are specified, regcnts will attempt to normalize the the background area so that the background pixel size is the same as the source pixel size. This normalization can only take place if the appropriate WCS information is contained in both files (e.g. degrees/pixel values in CDELT). If either file does not contain the requisite size information, the normalization is not performed. In this case, it is the user's responsibility to ensure that the pixel sizes are the same for the two files.
Normally, if more than one background region is specified, regcnts will combine them all into a single region and use this background region to produce the background-subtracted results for each source region. The -m (match multiple backgrounds) switch tells regcnts to make a one-to-one correspondence between background and source regions, instead of using a single combined background region. For example, the default case is to combine 2 background regions into a single region and then apply that region to each of the source regions:
$ regcnts snr.ev "annulus(502,512,0,22,n=2)" "annulus(502,512,50,100,n=2)"
# source
# data_file: snr.ev
# arcsec/pixel: 8
# background
# data_file: snr.ev
# column units
# area: arcsec**2
# surf_bri: cnts/arcsec**2
# surf_err: cnts/arcsec**2
# background-subtracted results
reg net_counts error background berror area surf_bri surf_err
---- ------------ --------- ------------ --------- --------- --------- ---------
1 3101.029 56.922 136.971 1.472 23872.00 0.130 0.002
2 725.375 34.121 418.625 4.500 72959.99 0.010 0.000
# source_region(s):
# annulus(502,512,0,22,n=2)
# source_data
reg counts pixels
---- ------------ ---------
1 3238.000 373
2 1144.000 1140
# background_region(s)
# annulus(502,512,50,100,n=2)
# background_data
reg counts pixels
---- ------------ ---------
all 8656.000 23572
Using the -m switch causes regcnts to use each of the two background regions independently with each of the two source regions:
$ regcnts -m snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)"
# source
# data_file: snr.ev
# arcsec/pixel: 8
# background
# data_file: snr.ev
# column units
# area: arcsec**2
# surf_bri: cnts/arcsec**2
# surf_err: cnts/arcsec**2
# background-subtracted results
reg net_counts error background berror area surf_bri surf_err
---- ------------ --------- ------------ --------- --------- --------- ---------
1 3087.015 56.954 150.985 2.395 23872.00 0.129 0.002
2 755.959 34.295 388.041 5.672 72959.99 0.010 0.000
# source_region(s):
# annulus(502,512,0,22,n=2)
# source_data
reg counts pixels
---- ------------ ---------
1 3238.000 373
2 1144.000 1140
# background_region(s)
# ann(502,512,50,100,n=2)
# background_data
reg counts pixels
---- ------------ ---------
1 3975.000 9820
2 4681.000 13752
Note that the basic region filter rule "each photon is counted once
and no photon is counted more than once" still applies when using The
-m to match background regions. That is, if two background
regions overlap, the overlapping pixels will be counted in only one of
them. In a worst-case scenario, if two background regions are the same
region, the first will get all the counts and area and the second
will get none.
Most floating point quantities are displayed using "f" format. You can change this to "g" format using the -g switch. This can be useful when the counts in each pixel is very small or very large. If you want maximum precision and don't care about the columns lining up nicely, use -G, which outputs all floating values as %.14g.
When counting photons using the annulus and panda (pie and annuli) shapes, it often is useful to have access to the radii (and panda angles) for each separate region. The -r switch will add radii and angle columns to the output table:
$ regcnts -r snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)"
# source
# data_file: snr.ev
# arcsec/pixel: 8
# background
# data_file: snr.ev
# column units
# area: arcsec**2
# surf_bri: cnts/arcsec**2
# surf_err: cnts/arcsec**2
# radii: arcsecs
# angles: degrees
# background-subtracted results
reg net_counts error background berror area surf_bri surf_err radius1 radius2 angle1 angle2
---- ------------ --------- ------------ --------- --------- --------- --------- --------- --------- --------- ---------
1 3101.029 56.922 136.971 1.472 23872.00 0.130 0.002 0.000 88.000 NA NA
2 725.375 34.121 418.625 4.500 72959.99 0.010 0.000 88.000 176.000 NA NA
# source_region(s):
# annulus(502,512,0,22,n=2)
# source_data
reg counts pixels
---- ------------ ---------
1 3238.000 373
2 1144.000 1140
# background_region(s)
# ann(502,512,50,100,n=2)
# background_data
reg counts pixels
---- ------------ ---------
all 8656.000 23572
Radii are given in units of pixels or arc-seconds (depending on the presence of WCS info), while the angle values (when present) are in degrees. These columns can be used to plot radial profiles.
The -s (sum) switch causes regcnts to produce an additional table of summed (integrated) background subtracted values, along with the default table of individual values:
$ regcnts -s snr.ev "annulus(502,512,0,50,n=5)" "annulus(502,512,50,100)"
# source
# data_file: snr.ev
# arcsec/pixel: 8
# background
# data_file: snr.ev
# column units
# area: arcsec**2
# surf_bri: cnts/arcsec**2
# surf_err: cnts/arcsec**2
# summed background-subtracted results
upto net_counts error background berror area surf_bri surf_err
---- ------------ --------- ------------ --------- --------- --------- ---------
1 2880.999 54.722 112.001 1.204 19520.00 0.148 0.003
2 3776.817 65.254 457.183 4.914 79679.98 0.047 0.001
3 4025.492 71.972 1031.508 11.087 179775.96 0.022 0.000
4 4185.149 80.109 1840.851 19.786 320831.94 0.013 0.000
5 4415.540 90.790 2873.460 30.885 500799.90 0.009 0.000
# background-subtracted results
reg net_counts error background berror area surf_bri surf_err
---- ------------ --------- ------------ --------- --------- --------- ---------
1 2880.999 54.722 112.001 1.204 19520.00 0.148 0.003
2 895.818 35.423 345.182 3.710 60159.99 0.015 0.001
3 248.675 29.345 574.325 6.173 100095.98 0.002 0.000
4 159.657 32.321 809.343 8.699 141055.97 0.001 0.000
5 230.390 37.231 1032.610 11.099 179967.96 0.001 0.000
# source_region(s):
# annulus(502,512,0,50,n=5)
# summed_source_data
reg counts pixels sumcnts sumpix
---- ------------ --------- ------------ ---------
1 2993.000 305 2993.000 305
2 1241.000 940 4234.000 1245
3 823.000 1564 5057.000 2809
4 969.000 2204 6026.000 5013
5 1263.000 2812 7289.000 7825
# background_region(s)
# annulus(502,512,50,100)
# background_data
reg counts pixels
---- ------------ ---------
all 8656.000 23572
The algorithm for calculating net counts and error is the usual one:
C = Raw Counts in Source Region Ac= Area of Source Region B= Raw Counts in Background Region Ab= Area of Background Region Net= C - B * (Ac / Ab)with the standard propagation of errors for the Error on Net. The net rate (surface brightness) would then be:
Net Rate = Net / Ac
If the -t (rdb table) switch is used, the output will conform to starbase/rdb data base format: tabs will be inserted between columns rather than spaces and line-feed will be inserted between tables. If the -j (json) switch is used, the output will be a JSON-formatted string instead of a table.
It is important to note that regcnts is an image program, even though it can be run directly on FITS binary tables. This means that image filtering (where a pixel is inside a region if its center is inside the region) is applied to table rows, ensuring that the same results are obtained regardless of whether a table or the equivalent binned image is used. As a result, the number of counts found using regcnts can differ from the number of events found using cfitsio row-filter syntax. For more information about boundary issues, see the discussion of Region Boundaries.
Regcnts works on FITS binary tables by asking the underlying cfitsio library to generate an in-memory FITS image. For some X-ray missions (e.g. XMM), the image dimensions of the data are huge (approx. 50k x 50K for XMM EPN). Trying to generate an in-memory image of that magnitude generally will hang the program as your computer swaps itself into oblivion. To avoid this problem, either utilize the cfitsio binning specifier on the command line, or use the -b switch to tell regcnts how to bin the image:
$ regcnts data/pn_201_clean.fits'[bin 32]'or:
$ regcnts -b data/pn_201_clean.fitsSome day available memory will be infinite ... but not today.
The above discussion describes how regcnts works on 2D images and tables. You can process a 3D FITS cube by specifying the -c [str] (cube) switch, whose argument can take any of the following forms:
# process slice 1428 in dimension 3 of the data cube regcnts -c 1428 cube.fits "circle(502,512,10)" regcnts -c '*:*:1428' cube.fits "circle(502,512,10)" # process all slices in dimension 3 of the data cube regcnts cube.fits "circle(502,512,10)" regcnts -c all cube.fits "circle(502,512,10)" regcnts -c '*:*:all' cube.fits "circle(502,512,10)"but you can specify any of the three dimensions as the cube dimension:
# process slice 1428 in dimension 2 of the data cube regcnts -c '*:1428:*' cube.fits "circle(502,512,10)" # process all slices in dimension 2 of the data cube regcnts -c '*:all:*' cube.fits "circle(502,512,10)"If a whole data cube is processed, the results of each slice will be identified by the slice number, e.g.:
.... 17 slices previous to this one ...
# background-subtracted results #18
reg net_counts error background berror area surf_bri surf_err
---- ------------ --------- ------------ --------- --------- --------- ---------
1 1299.000 36.042 0.000 0.000 60516.00 0.021 0.001
# source_region(s):
# field()
# source_data
reg counts pixels
---- ------------ ---------
1 1299.000 250000
For a large number of slices, using the -j (json) switch might be the
easiest way to access the individual slices:
"backgroundSubtractedResults18": [{
"reg": 1,
"netCounts": 1299.000,
"error": 36.042,
"background": 0.000,
"berror": 0.000,
"area": 60516.00,
"surfBrightness": 0.021,
"surfError": 0.001
}],
"sourceRegions18": "field()",
"sourceData18": [{
"reg": 1,
"counts": 1299.000,
"pixels": 250000
}]