summaryrefslogtreecommitdiffstats
path: root/funtools/doc/pod/funcnts.pod
diff options
context:
space:
mode:
authorWilliam Joye <wjoye@cfa.harvard.edu>2016-10-26 21:13:00 (GMT)
committerWilliam Joye <wjoye@cfa.harvard.edu>2016-10-26 21:13:00 (GMT)
commitda2e3d212171bbe64c1af39114fd067308656990 (patch)
tree9601f7ed15fa1394762124630c12a792bc073ec2 /funtools/doc/pod/funcnts.pod
parent76b109ad6d97d19ab835596dc70149ef379f3733 (diff)
downloadblt-da2e3d212171bbe64c1af39114fd067308656990.zip
blt-da2e3d212171bbe64c1af39114fd067308656990.tar.gz
blt-da2e3d212171bbe64c1af39114fd067308656990.tar.bz2
rm funtools for update
Diffstat (limited to 'funtools/doc/pod/funcnts.pod')
-rw-r--r--funtools/doc/pod/funcnts.pod657
1 files changed, 0 insertions, 657 deletions
diff --git a/funtools/doc/pod/funcnts.pod b/funtools/doc/pod/funcnts.pod
deleted file mode 100644
index 7d5dfe5..0000000
--- a/funtools/doc/pod/funcnts.pod
+++ /dev/null
@@ -1,657 +0,0 @@
-=pod
-
-=head1 NAME
-
-
-
-B<funcnts - count photons in specified regions, with bkgd subtraction>
-
-
-
-=head1 SYNOPSIS
-
-
-
-
-
-funcnts [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_value]
-
-
-
-
-
-=head1 OPTIONS
-
-
-
-
-
- -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
-
-
-
-
-
-=head1 DESCRIPTION
-
-
-
-
-B<funcnts> 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, array, or
-raw event file to process. If "stdin" is specified, data are read from
-the standard input. Use Funtools Bracket
-Notation to specify FITS extensions, image sections, and filters.
-
-
-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, 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).
-
-
-In summary, the following command arguments are valid:
-
- [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
-
-
-
-NB: 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 field() is the
-default source region. This rarely is the desired behavior. On the
-other hand, with FITS 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.
-
-
-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:
-
- [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
-
- # 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
-
-
- # the following source and background components were used:
- source region(s)
- ----------------
- circle(502,512,22)
-
- reg counts pixels
- ---- ------------ ---------
- 1 4382.000 1513
-
- background region(s)
- --------------------
- annulus(502,512,50,100)
-
- 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 B<-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 B<-z> switch.
-
-
-Note that a simple sed command will extract the background-subtracted results
-for further analysis:
-
- [sh] cat funcnts.sed
- 1,/---- .*/d
- /^$/,$d
-
- [sh] sed -f funcnts.sed funcnts.out
- 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001
-
-
-
-If separate source and background files are specified, B<funcnts> 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, B<funcnts>
-will combine them all into a single region and use this background
-region to produce the background-subtracted results for each source
-region. The B<-m> (match multiple backgrounds) switch tells
-B<funcnts> 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:
-
-
- [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
-
- # 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
-
-
- # the following source and background components were used:
- source region(s)
- ----------------
- annulus(502,512,0,22,n=2)
-
- reg counts pixels
- ---- ------------ ---------
- 1 3238.000 373
- 2 1144.000 1140
-
- background region(s)
- --------------------
- annulus(502,512,50,100,n=2)
-
- reg counts pixels
- ---- ------------ ---------
- all 8656.000 23572
-
-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
-B<-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.
-
-
-Using the B<-m> switch causes B<funcnts> to use each of the two
-background regions independently with each of the two source regions:
-
-
- [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
-
- # 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
-
-
- # the following source and background components were used:
- source region(s)
- ----------------
- annulus(502,512,0,22,n=2)
-
- reg counts pixels
- ---- ------------ ---------
- 1 3238.000 373
- 2 1144.000 1140
-
- background region(s)
- --------------------
- ann(502,512,50,100,n=2)
-
- reg counts pixels
- ---- ------------ ---------
- 1 3975.000 9820
- 2 4681.000 13752
-
-
-
-Note that most floating point quantities are displayed using "f"
-format. You can change this to "g" format using the B<-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 B<-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 B<-r> switch will add radii
-and angle columns to the output table:
-
-
- [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
-
- # 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
-
-
- # the following source and background components were used:
- source region(s)
- ----------------
- annulus(502,512,0,22,n=2)
-
- reg counts pixels
- ---- ------------ ---------
- 1 3238.000 373
- 2 1144.000 1140
-
- background region(s)
- --------------------
- ann(502,512,50,100,n=2)
-
- 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. For
-example, the script B<funcnts.plot> 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:
-
-
- #!/bin/sh
-
- 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 \"funcnts(%s)\"\n", FILES
- printf "set xlabel \" radius(%s)\"\n", XLABEL
- printf "set ylabel \"surf_bri(%s)\"\n", YLABEL
- print "plot \"-\" 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
-
- 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\n", 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
-
-
-Thus, to run B<funcnts> and plot the results using gnuplot (version 3.7
-or above), use:
-
- funcnts -r snr.ev "annulus(502,512,0,50,n=5)" ... | funcnts.plot gnuplot
-
-
-
-The B<-s> (sum) switch causes B<funcnts> to produce an
-additional table of summed (integrated) background subtracted values,
-along with the default table of individual values:
-
-
- [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
-
- # 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 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
-
-
- # the following source and background components were used:
- source region(s)
- ----------------
- annulus(502,512,0,50,n=5)
-
- 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)
-
- reg counts pixels
- ---- ------------ ---------
- all 8656.000 23572
-
-
-
-The B<-t> and B<-e> 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:
-
- 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
-
- 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
-
-Then, Net Counts in Source region is
-
- Net= C - B * (Ac*Tc*Ec)/(Ab*Tb*Eb)
-
-with the standard propagation of errors for the Error on Net.
-The net rate would then be
-
- Net Rate = Net/(Ac*Tc*Ec)
-
-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
-B<funcnts> will deal with the blocking automatically. Using the
-B<-e> switch, you can supply both source and background exposure
-files (separated by ";"), 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, B<funcnts> 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.
-
-
-NB: The B<-e> switch assumes that the exposure map overlays the
-image file B<exactly>, 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, B<do not use> the B<-e> exposure
-correction. In this case, it still is possible to perform exposure
-correction B<if> both the image and the exposure map have valid
-WCS information: use the B<-w> switch so that the transformation
-from image pixel to exposure pixel uses the WCS 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 B<-w> can increase the time
-required to process the exposure correction considerably.
-
-
-A time correction can be applied to both source and
-background data using the B<-t> 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:
-
- [sh] funcnts -t 23.4 ... # number for source
- [sh] funcnts -t "LIVETIME;23.4" ... # param for source, numeric for bkgd
-
-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.
-
-
-The B<-i> (interval) switch is used to run B<funcnts> on multiple
-column-based intervals with only a single pass through the data. It is
-equivalent to running B<funcnts> several times with a different column
-filter added to the source and background data each time. For each
-interval, the full B<funcnts> 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.
-
-
-Two formats are supported for interval specification. The most general
-format is semi-colon-delimited list of filters to be used as intervals:
-
- funcnts -i "pha=1:5;pha=6:10;pha=11:15" snr.ev "circle(502,512,22)" ...
-
-Conceptually, this will be equivalent to running B<funcnts> three times:
-
- 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)"
-
-However, using the B<-i> switch will require only one pass through
-the data.
-
-
-Note that complex filters can be used to specify intervals:
-
- funcnts -i "pha=1:5&&pi=4;pha=6:10&&pi=5;pha=11:15&&pi=6" snr.ev ...
-
-The program simply runs the data through each filter in turn and generates
-three B<funcnts> outputs, separated by the line-feed character.
-
-
-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
-"interval" filter have to be related to another. For example:
-
- funcnts -i "pha=1:5;pi=6:10;energy=11:15" snr.ev "circle(502,512,22)" ...
-
-is equivalent to running B<funcnts> three times with unrelated filter
-specifications.
-
-
-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:
-
- funcnts -i "pha;1:5;6:10;11:15" snr.ev "circle(502,512,22)" ...
-
-This is equivalent to the first example, but requires less typing. The
-B<funcnts> program will simply prepend "pha=" before each of the specified
-intervals. (Note that this format does not contain the "=" character in
-the column argument.)
-
-
-Ordinarily, when B<funcnts> is run on a FITS binary table (or a
-raw event table), one integral count is accumulated for each row
-(event) contained within a given region. The B<-v "scol[;bcol]">
-(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.
-
-
-If the B<-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.
-
-
-Finally, note that B<funcnts> is an image program, even though it
-can be run directly on FITS 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 B<funcnts> can differ from the number of events found
-using row-filter programs such as B<fundisp> or B<funtable>
-For more information about these difference, see the discussion of
-Region Boundaries.
-
-
-
-
-=head1 SEE ALSO
-
-
-
-See funtools(n) for a list of Funtools help pages
-
-
-=cut