regcnts - background-subtracted counts in regions

regcnts  [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_value]

  -b [n]        # bin factor for binary tables (make in-memory image smaller)
  -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 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.

Finally, 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.fits
Some day available memory will be infinite ... but not today.


Other pages of interest:
Last updated: August 9, 2015