diff options
Diffstat (limited to 'funtools/man/man1/funcnts.1')
| -rw-r--r-- | funtools/man/man1/funcnts.1 | 806 |
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 |