Merge commit '23c7930d27fe11c4655e1291a07a821dbbaba78d' as 'funtools'

1 files changed, 806 insertions, 0 deletions

diff --git a/funtools/man/man1/funcnts.1 b/funtools/man/man1/funcnts.1
new file mode 100644
index 0000000..0af4b73
--- /dev/null
+++ b/funtools/man/man1/funcnts.1
@@ -0,0 +1,806 @@
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  | will give a
+.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.\"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "funcnts 1"
+.TH funcnts 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation"
+.SH "NAME"
+funcnts \- count photons in specified regions, with bkgd subtraction
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+\&\fBfuncnts\fR  [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_value]
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.Vb 16
+\&  \-e "source_exposure[;bkgd_exposure]"
+\&                # source (bkgd) FITS exposure image using matching files
+\&  \-w "source_exposure[;bkgd_exposure]"
+\&                # source (bkgd) FITS exposure image using WCS transform
+\&  \-t "source_timecorr[;bkgd_timecorr]"
+\&                # source (bkgd) time correction value or header parameter name
+\&  \-g            # output using nice g format
+\&  \-G            # output using %.14g format (maximum precision)
+\&  \-i "[column;]int1;int2..." # column-based intervals
+\&  \-m            # match individual source and bkgd regions
+\&  \-p            # output in pixels, even if wcs is present
+\&  \-r            # output inner/outer radii (and angles) for annuli (and pandas)
+\&  \-s            # output summed values
+\&  \-v "scol[;bcol]" # src and bkgd value columns for tables
+\&  \-T            # output in starbase/rdb format
+\&  \-z            # output regions with zero area
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBfuncnts\fR 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.
+.PP
+The first argument to the program specifies the \s-1FITS\s0 input image, array, or
+raw event file to process.  If \*(L"stdin\*(R" is specified, data are read from
+the standard input. Use Funtools Bracket
+Notation to specify \s-1FITS\s0 extensions, image sections, and filters.
+.PP
+The optional second argument is the source region descriptor.  If no
+region is specified, the entire field is used.
+.PP
+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, in which case the fourth argument is the background region.
+If no third argument is specified, a constant value of 0 is used
+(i.e., no background).
+.PP
+In summary, the following command arguments are valid:
+.PP
+.Vb 5
+\&  [sh] funcnts sfile                        # counts in source file
+\&  [sh] funcnts sfile sregion                # counts in source region
+\&  [sh] funcnts sfile sregion bregion        # bkgd reg. is from source file
+\&  [sh] funcnts sfile sregion bvalue         # bkgd reg. is constant
+\&  [sh] funcnts sfile sregion bfile bregion  # bkgd reg. is from separate file
+.Ve
+.PP
+\&\s-1NB:\s0 unlike other Funtools programs, source and background regions are
+specified as separate arguments on the command line, rather than being
+placed inside brackets as part of the source and background filenames.
+This is because regions in funcnts are not simply used as data
+filters, but also are used to calculate areas, exposure, etc. If you
+put the source region inside the brackets (i.e. use it simply as a
+filter) rather than specifying it as argument two, the program still
+will only count photons that pass the region filter. However, the area
+calculation will be performed on the whole field, since \fIfield()\fR is the
+default source region. This rarely is the desired behavior. On the
+other hand, with \s-1FITS\s0 binary tables, it often is useful to put a column
+filter in the filename brackets, so that only events matching the
+column filter are counted inside the region.
+.PP
+For example, to extract the counts within a radius of 22 pixels from the
+center of the \s-1FITS\s0 binary table snr.ev and subtract the background determined
+from the same image within an annulus of radii 50\-100 pixels:
+.PP
+.Vb 10
+\&  [sh] funcnts snr.ev "circle(502,512,22)" "annulus(502,512,50,100)"
+\&  # source
+\&  #   data file:        snr.ev
+\&  #   degrees/pix:      0.00222222
+\&  # background
+\&  #   data file:        snr.ev
+\&  # column units
+\&  #   area:             arcsec**2
+\&  #   surf_bri:         cnts/arcsec**2
+\&  #   surf_err:         cnts/arcsec**2
+.Ve
+.PP
+.Vb 4
+\&  # 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
+.Ve
+.PP
+.Vb 4
+\&  # the following source and background components were used:
+\&  source region(s)
+\&  ----------------
+\&  circle(502,512,22)
+.Ve
+.PP
+.Vb 3
+\&   reg       counts    pixels
+\&  ---- ------------ ---------
+\&     1     4382.000      1513
+.Ve
+.PP
+.Vb 3
+\&  background region(s)
+\&  --------------------
+\&  annulus(502,512,50,100)
+.Ve
+.PP
+.Vb 3
+\&   reg       counts    pixels
+\&  ---- ------------ ---------
+\&  all      8656.000     23572
+.Ve
+.PP
+The area units for the output columns labeled \*(L"area\*(R", \*(L"surf_bri\*(R"
+(surface brightness) and \*(L"surf_err\*(R" will be given either in
+arc-seconds (if appropriate \s-1WCS\s0 information is in the data file
+header(s)) or in pixels. If the data file has \s-1WCS\s0 info, but you do not
+want arc-second units, use the \fB\-p\fR 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 \fB\-z\fR switch.
+.PP
+Note that a simple sed command will extract the background-subtracted results
+for further analysis:
+.PP
+.Vb 3
+\&  [sh] cat funcnts.sed
+\&  1,/---- .*/d
+\&  /^$/,$d
+.Ve
+.PP
+.Vb 2
+\&  [sh] sed \-f funcnts.sed funcnts.out
+\&  1     3826.403    66.465      555.597     5.972  96831.98     0.040     0.001
+.Ve
+.PP
+If separate source and background files are specified, \fBfuncnts\fR 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 \s-1WCS\s0 information is contained in
+both files (e.g. degrees/pixel values in \s-1CDELT\s0). 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.
+.PP
+Normally, if more than one background region is specified, \fBfuncnts\fR
+will combine them all into a single region and use this background
+region to produce the background-subtracted results for each source
+region. The \fB\-m\fR (match multiple backgrounds) switch tells
+\&\fBfuncnts\fR 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:
+.PP
+.Vb 10
+\&  [sh] funcnts snr.ev "annulus(502,512,0,22,n=2)" "annulus(502,512,50,100,n=2)"
+\&  # source
+\&  #   data file:        snr.ev
+\&  #   degrees/pix:      0.00222222
+\&  # background
+\&  #   data file:        snr.ev
+\&  # column units
+\&  #   area:             arcsec**2
+\&  #   surf_bri:         cnts/arcsec**2
+\&  #   surf_err:         cnts/arcsec**2
+.Ve
+.PP
+.Vb 5
+\&  # 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
+.Ve
+.PP
+.Vb 4
+\&  # the following source and background components were used:
+\&  source region(s)
+\&  ----------------
+\&  annulus(502,512,0,22,n=2)
+.Ve
+.PP
+.Vb 4
+\&   reg       counts    pixels
+\&  ---- ------------ ---------
+\&     1     3238.000       373
+\&     2     1144.000      1140
+.Ve
+.PP
+.Vb 3
+\&  background region(s)
+\&  --------------------
+\&  annulus(502,512,50,100,n=2)
+.Ve
+.PP
+.Vb 3
+\&   reg       counts    pixels
+\&  ---- ------------ ---------
+\&  all      8656.000     23572
+.Ve
+.PP
+Note that the basic region filter rule \*(L"each photon is counted once
+and no photon is counted more than once\*(R" still applies when using The
+\&\fB\-m\fR 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.
+.PP
+Using the \fB\-m\fR switch causes \fBfuncnts\fR to use each of the two
+background regions independently with each of the two source regions:
+.PP
+.Vb 10
+\&  [sh] funcnts \-m snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)"
+\&  # source
+\&  #   data file:        snr.ev
+\&  #   degrees/pix:      0.00222222
+\&  # background
+\&  #   data file:        snr.ev
+\&  # column units
+\&  #   area:             arcsec**2
+\&  #   surf_bri:         cnts/arcsec**2
+\&  #   surf_err:         cnts/arcsec**2
+.Ve
+.PP
+.Vb 5
+\&  # 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
+.Ve
+.PP
+.Vb 4
+\&  # the following source and background components were used:
+\&  source region(s)
+\&  ----------------
+\&  annulus(502,512,0,22,n=2)
+.Ve
+.PP
+.Vb 4
+\&   reg       counts    pixels
+\&  ---- ------------ ---------
+\&     1     3238.000       373
+\&     2     1144.000      1140
+.Ve
+.PP
+.Vb 3
+\&  background region(s)
+\&  --------------------
+\&  ann(502,512,50,100,n=2)
+.Ve
+.PP
+.Vb 4
+\&   reg       counts    pixels
+\&  ---- ------------ ---------
+\&     1     3975.000      9820
+\&     2     4681.000     13752
+.Ve
+.PP
+Note that most floating point quantities are displayed using \*(L"f\*(R"
+format. You can change this to \*(L"g\*(R" format using the \fB\-g\fR
+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 \fB\-G\fR, which outputs
+all floating values as %.14g.
+.PP
+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 \fB\-r\fR switch will add radii
+and angle columns to the output table:
+.PP
+.Vb 12
+\&  [sh] funcnts \-r snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)"
+\&  # source
+\&  #   data file:        snr.ev
+\&  #   degrees/pix:      0.00222222
+\&  # background
+\&  #   data file:        snr.ev
+\&  # column units
+\&  #   area:             arcsec**2
+\&  #   surf_bri:         cnts/arcsec**2
+\&  #   surf_err:         cnts/arcsec**2
+\&  #   radii:            arcsecs
+\&  #   angles:           degrees
+.Ve
+.PP
+.Vb 5
+\&  # 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.00     88.00        NA        NA
+\&     2      725.375    34.121      418.625     4.500  72959.99     0.010     0.000     88.00    176.00        NA        NA
+.Ve
+.PP
+.Vb 4
+\&  # the following source and background components were used:
+\&  source region(s)
+\&  ----------------
+\&  annulus(502,512,0,22,n=2)
+.Ve
+.PP
+.Vb 4
+\&   reg       counts    pixels
+\&  ---- ------------ ---------
+\&     1     3238.000       373
+\&     2     1144.000      1140
+.Ve
+.PP
+.Vb 3
+\&  background region(s)
+\&  --------------------
+\&  ann(502,512,50,100,n=2)
+.Ve
+.PP
+.Vb 3
+\&   reg       counts    pixels
+\&  ---- ------------ ---------
+\&  all      8656.000     23572
+.Ve
+.PP
+Radii are given in units of pixels or arc-seconds (depending on the
+presence of \s-1WCS\s0 info), while the angle values (when present) are in
+degrees.  These columns can be used to plot radial profiles. For
+example, the script \fBfuncnts.plot\fR in the funtools
+distribution) will plot a radial profile using gnuplot (version 3.7 or
+above). A simplified version of this script is shown below:
+.PP
+.Vb 1
+\&  #!/bin/sh
+.Ve
+.PP
+.Vb 37
+\&  if [ x"$1" = xgnuplot ]; then
+\&    if [ x`which gnuplot 2>/dev/null` = x ]; then
+\&      echo "ERROR: gnuplot not available"
+\&      exit 1
+\&    fi
+\&    awk '
+\&    BEGIN{HEADER=1; DATA=0; FILES=""; XLABEL="unknown"; YLABEL="unknown"}
+\&    HEADER==1{
+\&      if( $1 == "#" && $2 == "data" && $3 == "file:" ){
+\&        if( FILES != "" ) FILES = FILES ","
+\&        FILES = FILES $4
+\&      }
+\&      else if( $1 == "#" && $2 == "radii:" ){
+\&        XLABEL = $3
+\&      }
+\&      else if( $1 == "#" && $2 == "surf_bri:" ){
+\&        YLABEL = $3
+\&      }
+\&      else if( $1 == "----" ){
+\&        printf "set nokey; set title \e"funcnts(%s)\e"\en", FILES
+\&        printf "set xlabel \e" radius(%s)\e"\en", XLABEL
+\&        printf "set ylabel \e"surf_bri(%s)\e"\en", YLABEL
+\&        print  "plot \e"-\e" using 3:4:6:7:8 with boxerrorbars"
+\&        HEADER = 0
+\&        DATA = 1
+\&        next
+\&      }
+\&    }
+\&    DATA==1{
+\&      if( NF == 12 ){
+\&        print $9, $10, ($9+$10)/2, $7, $8, $7-$8, $7+$8, $10-$9
+\&      }
+\&      else{
+\&        exit
+\&      }
+\&    }
+\&    ' | gnuplot \-persist - 1>/dev/null 2>&1
+.Ve
+.PP
+.Vb 34
+\&  elif [ x"$1" = xds9 ]; then
+\&    awk '
+\&    BEGIN{HEADER=1; DATA=0; XLABEL="unknown"; YLABEL="unknown"}
+\&    HEADER==1{
+\&      if( $1 == "#" && $2 == "data" && $3 == "file:" ){
+\&        if( FILES != "" ) FILES = FILES ","
+\&        FILES = FILES $4
+\&      }
+\&      else if( $1 == "#" && $2 == "radii:" ){
+\&        XLABEL = $3
+\&      }
+\&      else if( $1 == "#" && $2 == "surf_bri:" ){
+\&        YLABEL = $3
+\&      }
+\&      else if( $1 == "----" ){
+\&        printf "funcnts(%s) radius(%s) surf_bri(%s) 3\en", FILES, XLABEL, YLABEL
+\&        HEADER = 0
+\&        DATA = 1
+\&        next
+\&      }
+\&    }
+\&    DATA==1{
+\&      if( NF == 12 ){
+\&        print $9, $7, $8
+\&      }
+\&      else{
+\&        exit
+\&      }
+\&    }
+\&    '
+\&  else
+\&    echo "funcnts \-r ... | funcnts.plot [ds9|gnuplot]"
+\&    exit 1
+\&  fi
+.Ve
+.PP
+Thus, to run \fBfuncnts\fR and plot the results using gnuplot (version 3.7
+or above), use:
+.PP
+.Vb 1
+\&  funcnts \-r snr.ev "annulus(502,512,0,50,n=5)" ...  | funcnts.plot gnuplot
+.Ve
+.PP
+The \fB\-s\fR (sum) switch causes \fBfuncnts\fR to produce an
+additional table of summed (integrated) background subtracted values,
+along with the default table of individual values:
+.PP
+.Vb 10
+\&  [sh] funcnts \-s snr.ev "annulus(502,512,0,50,n=5)" "annulus(502,512,50,100)"
+\&  # source
+\&  #   data file:        snr.ev
+\&  #   degrees/pix:      0.00222222
+\&  # background
+\&  #   data file:        snr.ev
+\&  # column units
+\&  #   area:             arcsec**2
+\&  #   surf_bri:         cnts/arcsec**2
+\&  #   surf_err:         cnts/arcsec**2
+.Ve
+.PP
+.Vb 8
+\&  # 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
+.Ve
+.PP
+.Vb 8
+\&  # background-subtracted results
+\&   reg       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
+.Ve
+.PP
+.Vb 4
+\&  # the following source and background components were used:
+\&  source region(s)
+\&  ----------------
+\&  annulus(502,512,0,50,n=5)
+.Ve
+.PP
+.Vb 7
+\&   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
+.Ve
+.PP
+.Vb 3
+\&  background region(s)
+\&  --------------------
+\&  annulus(502,512,50,100)
+.Ve
+.PP
+.Vb 3
+\&   reg       counts    pixels
+\&  ---- ------------ ---------
+\&  all      8656.000     23572
+.Ve
+.PP
+The \fB\-t\fR and \fB\-e\fR switches can be used to apply timing and
+exposure corrections, respectively, to the data. Please note that
+these corrections are meant to be used qualitatively, since
+application of more accurate correction factors is a complex and
+mission-dependent effort. The algorithm for applying these simple
+corrections is as follows:
+.PP
+.Vb 4
+\&  C =  Raw Counts in Source Region
+\&  Ac=  Area of Source Region
+\&  Tc=  Exposure time for Source Data
+\&  Ec=  Average exposure in Source Region, from exposure map
+.Ve
+.PP
+.Vb 4
+\&  B=   Raw Counts in Background Region
+\&  Ab=  Area of Background Region
+\&  Tb=  (Exposure) time for Background Data
+\&  Eb=  Average exposure in Background Region, from exposure map
+.Ve
+.PP
+Then, Net Counts in Source region is
+.PP
+.Vb 1
+\&  Net=  C - B * (Ac*Tc*Ec)/(Ab*Tb*Eb)
+.Ve
+.PP
+with the standard propagation of errors for the Error on Net.
+The net rate would then be
+.PP
+.Vb 1
+\&  Net Rate = Net/(Ac*Tc*Ec)
+.Ve
+.PP
+The average exposure in each region is calculated by summing up the
+pixel values in the exposure map for the given region and then
+dividing by the number of pixels in that region. Exposure maps often
+are generated at a block factor > 1 (e.g., block 4 means that each
+exposure pixel contains 4x4 pixels at full resolution) and
+\&\fBfuncnts\fR will deal with the blocking automatically. Using the
+\&\fB\-e\fR switch, you can supply both source and background exposure
+files (separated by \*(L";\*(R"), if you have separate source and background
+data files. If you do not supply a background exposure file to go with
+a separate background data file, \fBfuncnts\fR assumes that exposure
+already has been applied to the background data file. In addition, it
+assumes that the error on the pixels in the background data file is
+zero.
+.PP
+\&\s-1NB:\s0 The \fB\-e\fR switch assumes that the exposure map overlays the
+image file \fBexactly\fR, except for the block factor.  Each pixel in
+the image is scaled by the block factor to access the corresponding
+pixel in the exposure map. If your exposure map does not line up
+exactly with the image, \fBdo not use\fR the \fB\-e\fR exposure
+correction.  In this case, it still is possible to perform exposure
+correction \fBif\fR both the image and the exposure map have valid
+\&\s-1WCS\s0 information: use the \fB\-w\fR switch so that the transformation
+from image pixel to exposure pixel uses the \s-1WCS\s0 information. That is,
+each pixel in the image region will be transformed first from image
+coordinates to sky coordinates, then from sky coordinates to exposure
+coordinates. Please note that using \fB\-w\fR can increase the time
+required to process the exposure correction considerably.
+.PP
+A time correction can be applied to both source and
+background data using the \fB\-t\fR switch. The value for the correction can
+either be a numeric constant or the name of a header parameter in
+the source (or background) file:
+.PP
+.Vb 2
+\&  [sh] funcnts \-t 23.4 ...            # number for source
+\&  [sh] funcnts \-t "LIVETIME;23.4" ... # param for source, numeric for bkgd
+.Ve
+.PP
+When a time correction is specified, it is applied to the net counts
+as well (see algorithm above), so that the units of surface brightness
+become cnts/area**2/sec.
+.PP
+The \fB\-i\fR (interval) switch is used to run \fBfuncnts\fR on multiple
+column-based intervals with only a single pass through the data. It is
+equivalent to running \fBfuncnts\fR several times with a different column
+filter added to the source and background data each time. For each
+interval, the full \fBfuncnts\fR output is generated, with a linefeed
+character (^L) inserted between each run.  In addition, the output for
+each interval will contain the interval specification in its header.
+Intervals are very useful for generating X\-ray hardness ratios
+efficiently.  Of course, they are only supported when the input data
+are contained in a table.
+.PP
+Two formats are supported for interval specification. The most general
+format is semi-colon-delimited list of filters to be used as intervals:
+.PP
+.Vb 1
+\&  funcnts \-i "pha=1:5;pha=6:10;pha=11:15" snr.ev "circle(502,512,22)" ...
+.Ve
+.PP
+Conceptually, this will be equivalent to running \fBfuncnts\fR three times:
+.PP
+.Vb 3
+\&  funcnts snr.ev'[pha=1:5]' "circle(502,512,22)"
+\&  funcnts snr.ev'[pha=6:10]' "circle(502,512,22)"
+\&  funcnts snr.ev'[pha=11:15]' "circle(502,512,22)"
+.Ve
+.PP
+However, using the \fB\-i\fR switch will require only one pass through
+the data.
+.PP
+Note that complex filters can be used to specify intervals:
+.PP
+.Vb 1
+\&  funcnts \-i "pha=1:5&&pi=4;pha=6:10&&pi=5;pha=11:15&&pi=6" snr.ev ...
+.Ve
+.PP
+The program simply runs the data through each filter in turn and generates
+three \fBfuncnts\fR outputs, separated by the line-feed character.
+.PP
+In fact, although the intent is to support intervals for hardness ratios,
+the specified filters do not have to be intervals at all. Nor does one
+\&\*(L"interval\*(R" filter have to be related to another. For example:
+.PP
+.Vb 1
+\&  funcnts \-i "pha=1:5;pi=6:10;energy=11:15" snr.ev "circle(502,512,22)" ...
+.Ve
+.PP
+is equivalent to running \fBfuncnts\fR three times with unrelated filter
+specifications.
+.PP
+A second interval format is supported for the simple case in which a
+single column is used to specify multiple homogeneous intervals for
+that column. In this format, a column name is specified first,
+followed by intervals:
+.PP
+.Vb 1
+\&  funcnts \-i "pha;1:5;6:10;11:15" snr.ev "circle(502,512,22)" ...
+.Ve
+.PP
+This is equivalent to the first example, but requires less typing. The
+\&\fBfuncnts\fR program will simply prepend \*(L"pha=\*(R" before each of the specified
+intervals. (Note that this format does not contain the \*(L"=\*(R" character in
+the column argument.)
+.PP
+Ordinarily, when \fBfuncnts\fR is run on a \s-1FITS\s0 binary table (or a
+raw event table), one integral count is accumulated for each row
+(event) contained within a given region. The \fB\-v \*(L"scol[;bcol]\*(R"\fR
+(value column) switch will accumulate counts using the value from the
+specified column for the given event. If only a single column is
+specified, it is used for both the source and background regions. Two
+separate columns, separated by a semi\-colon, can be specified for source
+and background. The special token '$none' can be used to specify that
+a value column is to be used for one but not the other. For example,
+\&'pha;$none' will use the pha column for the source but use integral
+counts for the background, while '$none;pha' will do the converse.
+If the value column is of type logical, then the value used will be 1
+for T and 0 for F.  Value columns are used, for example, to integrate
+probabilities instead of integral counts.
+.PP
+If the \fB\-T\fR (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.
+.PP
+Finally, note that \fBfuncnts\fR is an image program, even though it
+can be run directly on \s-1FITS\s0 binary tables. This means that image
+filtering is applied to the rows in order to ensure that the same
+results are obtained regardless of whether a table or the equivalent
+binned image is used. Because of this, however, the number of counts
+found using \fBfuncnts\fR can differ from the number of events found
+using row-filter programs such as \fBfundisp\fR or \fBfuntable\fR
+For more information about these difference, see the discussion of
+Region Boundaries.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+See funtools(7) for a list of Funtools help pages