summaryrefslogtreecommitdiffstats
path: root/funtools/man/man1/funcnts.1
diff options
context:
space:
mode:
authorWilliam Joye <wjoye@cfa.harvard.edu>2016-10-27 17:38:41 (GMT)
committerWilliam Joye <wjoye@cfa.harvard.edu>2016-10-27 17:38:41 (GMT)
commit5b44fb0d6530c4ff66a446afb69933aa8ffd014f (patch)
treee059f66d1f612e21fe9d83f9620c8715530353ec /funtools/man/man1/funcnts.1
parentda2e3d212171bbe64c1af39114fd067308656990 (diff)
parent23c7930d27fe11c4655e1291a07a821dbbaba78d (diff)
downloadblt-5b44fb0d6530c4ff66a446afb69933aa8ffd014f.zip
blt-5b44fb0d6530c4ff66a446afb69933aa8ffd014f.tar.gz
blt-5b44fb0d6530c4ff66a446afb69933aa8ffd014f.tar.bz2
Merge commit '23c7930d27fe11c4655e1291a07a821dbbaba78d' as 'funtools'
Diffstat (limited to 'funtools/man/man1/funcnts.1')
-rw-r--r--funtools/man/man1/funcnts.1806
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