diff options
Diffstat (limited to 'funtools/doc/pod/funcnts.pod')
| -rw-r--r-- | funtools/doc/pod/funcnts.pod | 657 |
1 files changed, 657 insertions, 0 deletions
diff --git a/funtools/doc/pod/funcnts.pod b/funtools/doc/pod/funcnts.pod new file mode 100644 index 0000000..7d5dfe5 --- /dev/null +++ b/funtools/doc/pod/funcnts.pod @@ -0,0 +1,657 @@ +=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 |