diff options
Diffstat (limited to 'funtools/doc/pod/funcnts.pod')
| -rw-r--r-- | funtools/doc/pod/funcnts.pod | 657 |
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 |