1funcnts(1) SAORD Documentation funcnts(1)
2
6 funcnts - count photons in specified regions, with bkgd subtraction
7
9 funcnts [switches] <source_file> [source_region] [bkgd_file]
10 [bkgd_region⎪bkgd_value]
11
13 -e "source_exposure[;bkgd_exposure]"
14 # source (bkgd) FITS exposure image using matching files
15 -w "source_exposure[;bkgd_exposure]"
16 # source (bkgd) FITS exposure image using WCS transform
17 -t "source_timecorr[;bkgd_timecorr]"
18 # source (bkgd) time correction value or header parameter name
19 -g # output using nice g format
20 -G # output using %.14g format (maximum precision)
21 -i "[column;]int1;int2..." # column-based intervals
22 -m # match individual source and bkgd regions
23 -p # output in pixels, even if wcs is present
24 -r # output inner/outer radii (and angles) for annuli (and pandas)
25 -s # output summed values
26 -v "scol[;bcol]" # src and bkgd value columns for tables
27 -T # output in starbase/rdb format
28 -z # output regions with zero area
29
31 funcnts counts photons in the specified source regions and reports the
32 results for each region. Regions are specified using the Spatial Region
33 Filtering mechanism. Photons are also counted in the specified bkgd
34 regions applied to the same data file or a different data file. (Alter‐
35 natively, a constant background value in counts/pixel**2 can be speci‐
36 fied.) The bkgd regions are either paired one-to-one with source
37 regions or pooled and normalized by area, and then subtracted from the
38 source counts in each region. Displayed results include the bkgd-sub‐
39 tracted counts in each region, as well as the error on the counts, the
40 area in each region, and the surface brightness (cnts/area**2) calcu‐
41 lated for each region.
42 The first argument to the program specifies the FITS input image,
44 array, or raw event file to process. If "stdin" is specified, data are
45 read from the standard input. Use Funtools Bracket Notation to specify
46 FITS extensions, image sections, and filters.
47 The optional second argument is the source region descriptor. If no
49 region is specified, the entire field is used.
50 The background arguments can take one of two forms, depending on
52 whether a separate background file is specified. If the source file is
53 to be used for background as well, the third argument can be either the
54 background region, or a constant value denoting background cnts/pixel.
55 Alternatively, the third argument can be a background data file, in
56 which case the fourth argument is the background region. If no third
57 argument is specified, a constant value of 0 is used (i.e., no back‐
58 ground).
59 In summary, the following command arguments are valid:
61 [sh] funcnts sfile # counts in source file
63 [sh] funcnts sfile sregion # counts in source region
64 [sh] funcnts sfile sregion bregion # bkgd reg. is from source file
65 [sh] funcnts sfile sregion bvalue # bkgd reg. is constant
66 [sh] funcnts sfile sregion bfile bregion # bkgd reg. is from separate file
67 NB: unlike other Funtools programs, source and background regions are
69 specified as separate arguments on the command line, rather than being
70 placed inside brackets as part of the source and background filenames.
71 This is because regions in funcnts are not simply used as data filters,
72 but also are used to calculate areas, exposure, etc. If you put the
73 source region inside the brackets (i.e. use it simply as a filter)
74 rather than specifying it as argument two, the program still will only
75 count photons that pass the region filter. However, the area calcula‐
76 tion will be performed on the whole field, since field() is the default
77 source region. This rarely is the desired behavior. On the other hand,
78 with FITS binary tables, it often is useful to put a column filter in
79 the filename brackets, so that only events matching the column filter
80 are counted inside the region.
81 For example, to extract the counts within a radius of 22 pixels from
83 the center of the FITS binary table snr.ev and subtract the background
84 determined from the same image within an annulus of radii 50-100 pix‐
85 els:
86 [sh] funcnts snr.ev "circle(502,512,22)" "annulus(502,512,50,100)"
88 # source
89 # data file: snr.ev
90 # degrees/pix: 0.00222222
91 # background
92 # data file: snr.ev
93 # column units
94 # area: arcsec**2
95 # surf_bri: cnts/arcsec**2
96 # surf_err: cnts/arcsec**2
97 # background-subtracted results
99 reg net_counts error background berror area surf_bri surf_err
100 ---- ------------ --------- ------------ --------- --------- --------- ---------
101 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001
102 # the following source and background components were used:
104 source region(s)
105 ----------------
106 circle(502,512,22)
107 reg counts pixels
109 ---- ------------ ---------
110 1 4382.000 1513
111 background region(s)
113 --------------------
114 annulus(502,512,50,100)
115 reg counts pixels
117 ---- ------------ ---------
118 all 8656.000 23572
119 The area units for the output columns labeled "area", "surf_bri" (sur‐
121 face brightness) and "surf_err" will be given either in arc-seconds (if
122 appropriate WCS information is in the data file header(s)) or in pix‐
123 els. If the data file has WCS info, but you do not want arc-second
124 units, use the -p switch to force output in pixels. Also, regions hav‐
125 ing zero area are not normally included in the primary (background-sub‐
126 tracted) table, but are included in the secondary source and bkgd
127 tables. If you want these regions to be included in the primary table,
128 use the -z switch.
129 Note that a simple sed command will extract the background-subtracted
131 results for further analysis:
132 [sh] cat funcnts.sed
134 1,/---- .*/d
135 /^$/,$d
136 [sh] sed -f funcnts.sed funcnts.out
138 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001
139 If separate source and background files are specified, funcnts will
141 attempt to normalize the the background area so that the background
142 pixel size is the same as the source pixel size. This normalization can
143 only take place if the appropriate WCS information is contained in both
144 files (e.g. degrees/pixel values in CDELT). If either file does not
145 contain the requisite size information, the normalization is not per‐
146 formed. In this case, it is the user's responsibility to ensure that
147 the pixel sizes are the same for the two files.
148 Normally, if more than one background region is specified, funcnts will
150 combine them all into a single region and use this background region to
151 produce the background-subtracted results for each source region. The
152 -m (match multiple backgrounds) switch tells funcnts to make a one to
153 one correspondence between background and source regions, instead of
154 using a single combined background region. For example, the default
155 case is to combine 2 background regions into a single region and then
156 apply that region to each of the source regions:
157 [sh] funcnts snr.ev "annulus(502,512,0,22,n=2)" "annulus(502,512,50,100,n=2)"
159 # source
160 # data file: snr.ev
161 # degrees/pix: 0.00222222
162 # background
163 # data file: snr.ev
164 # column units
165 # area: arcsec**2
166 # surf_bri: cnts/arcsec**2
167 # surf_err: cnts/arcsec**2
168 # background-subtracted results
170 reg net_counts error background berror area surf_bri surf_err
171 ---- ------------ --------- ------------ --------- --------- --------- ---------
172 1 3101.029 56.922 136.971 1.472 23872.00 0.130 0.002
173 2 725.375 34.121 418.625 4.500 72959.99 0.010 0.000
174 # the following source and background components were used:
176 source region(s)
177 ----------------
178 annulus(502,512,0,22,n=2)
179 reg counts pixels
181 ---- ------------ ---------
182 1 3238.000 373
183 2 1144.000 1140
184 background region(s)
186 --------------------
187 annulus(502,512,50,100,n=2)
188 reg counts pixels
190 ---- ------------ ---------
191 all 8656.000 23572
192 Note that the basic region filter rule "each photon is counted once and
194 no photon is counted more than once" still applies when using The -m to
195 match background regions. That is, if two background regions overlap,
196 the overlapping pixels will be counted in only one of them. In a worst-
197 case scenario, if two background regions are the same region, the first
198 will get all the counts and area and the second will get none.
199 Using the -m switch causes funcnts to use each of the two background
201 regions independently with each of the two source regions:
202 [sh] funcnts -m snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)"
204 # source
205 # data file: snr.ev
206 # degrees/pix: 0.00222222
207 # background
208 # data file: snr.ev
209 # column units
210 # area: arcsec**2
211 # surf_bri: cnts/arcsec**2
212 # surf_err: cnts/arcsec**2
213 # background-subtracted results
215 reg net_counts error background berror area surf_bri surf_err
216 ---- ------------ --------- ------------ --------- --------- --------- ---------
217 1 3087.015 56.954 150.985 2.395 23872.00 0.129 0.002
218 2 755.959 34.295 388.041 5.672 72959.99 0.010 0.000
219 # the following source and background components were used:
221 source region(s)
222 ----------------
223 annulus(502,512,0,22,n=2)
224 reg counts pixels
226 ---- ------------ ---------
227 1 3238.000 373
228 2 1144.000 1140
229 background region(s)
231 --------------------
232 ann(502,512,50,100,n=2)
233 reg counts pixels
235 ---- ------------ ---------
236 1 3975.000 9820
237 2 4681.000 13752
238 Note that most floating point quantities are displayed using "f" for‐
240 mat. You can change this to "g" format using the -g switch. This can
241 be useful when the counts in each pixel is very small or very large. If
242 you want maximum precision and don't care about the columns lining up
243 nicely, use -G, which outputs all floating values as %.14g.
244 When counting photons using the annulus and panda (pie and annuli)
246 shapes, it often is useful to have access to the radii (and panda
247 angles) for each separate region. The -r switch will add radii and
248 angle columns to the output table:
249 [sh] funcnts -r snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)"
251 # source
252 # data file: snr.ev
253 # degrees/pix: 0.00222222
254 # background
255 # data file: snr.ev
256 # column units
257 # area: arcsec**2
258 # surf_bri: cnts/arcsec**2
259 # surf_err: cnts/arcsec**2
260 # radii: arcsecs
261 # angles: degrees
262 # background-subtracted results
264 reg net_counts error background berror area surf_bri surf_err radius1 radius2 angle1 angle2
265 ---- ------------ --------- ------------ --------- --------- --------- --------- --------- --------- --------- ---------
266 1 3101.029 56.922 136.971 1.472 23872.00 0.130 0.002 0.00 88.00 NA NA
267 2 725.375 34.121 418.625 4.500 72959.99 0.010 0.000 88.00 176.00 NA NA
268 # the following source and background components were used:
270 source region(s)
271 ----------------
272 annulus(502,512,0,22,n=2)
273 reg counts pixels
275 ---- ------------ ---------
276 1 3238.000 373
277 2 1144.000 1140
278 background region(s)
280 --------------------
281 ann(502,512,50,100,n=2)
282 reg counts pixels
284 ---- ------------ ---------
285 all 8656.000 23572
286 Radii are given in units of pixels or arc-seconds (depending on the
288 presence of WCS info), while the angle values (when present) are in
289 degrees. These columns can be used to plot radial profiles. For exam‐
290 ple, the script funcnts.plot in the funtools distribution) will plot a
291 radial profile using gnuplot (version 3.7 or above). A simplified ver‐
292 sion of this script is shown below:
293 #!/bin/sh
295 if [ x"$1" = xgnuplot ]; then
297 if [ x`which gnuplot 2>/dev/null` = x ]; then
298 echo "ERROR: gnuplot not available"
299 exit 1
300 fi
301 awk '
302 BEGIN{HEADER=1; DATA=0; FILES=""; XLABEL="unknown"; YLABEL="unknown"}
303 HEADER==1{
304 if( $1 == "#" && $2 == "data" && $3 == "file:" ){
305 if( FILES != "" ) FILES = FILES ","
306 FILES = FILES $4
307 }
308 else if( $1 == "#" && $2 == "radii:" ){
309 XLABEL = $3
310 }
311 else if( $1 == "#" && $2 == "surf_bri:" ){
312 YLABEL = $3
313 }
314 else if( $1 == "----" ){
315 printf "set nokey; set title \"funcnts(%s)\"\n", FILES
316 printf "set xlabel \" radius(%s)\"\n", XLABEL
317 printf "set ylabel \"surf_bri(%s)\"\n", YLABEL
318 print "plot \"-\" using 3:4:6:7:8 with boxerrorbars"
319 HEADER = 0
320 DATA = 1
321 next
322 }
323 }
324 DATA==1{
325 if( NF == 12 ){
326 print $9, $10, ($9+$10)/2, $7, $8, $7-$8, $7+$8, $10-$9
327 }
328 else{
329 exit
330 }
331 }
332 ' ⎪ gnuplot -persist - 1>/dev/null 2>&1
333 elif [ x"$1" = xds9 ]; then
335 awk '
336 BEGIN{HEADER=1; DATA=0; XLABEL="unknown"; YLABEL="unknown"}
337 HEADER==1{
338 if( $1 == "#" && $2 == "data" && $3 == "file:" ){
339 if( FILES != "" ) FILES = FILES ","
340 FILES = FILES $4
341 }
342 else if( $1 == "#" && $2 == "radii:" ){
343 XLABEL = $3
344 }
345 else if( $1 == "#" && $2 == "surf_bri:" ){
346 YLABEL = $3
347 }
348 else if( $1 == "----" ){
349 printf "funcnts(%s) radius(%s) surf_bri(%s) 3\n", FILES, XLABEL, YLABEL
350 HEADER = 0
351 DATA = 1
352 next
353 }
354 }
355 DATA==1{
356 if( NF == 12 ){
357 print $9, $7, $8
358 }
359 else{
360 exit
361 }
362 }
363 '
364 else
365 echo "funcnts -r ... ⎪ funcnts.plot [ds9⎪gnuplot]"
366 exit 1
367 fi
368 Thus, to run funcnts and plot the results using gnuplot (version 3.7 or
370 above), use:
371 funcnts -r snr.ev "annulus(502,512,0,50,n=5)" ... ⎪ funcnts.plot gnuplot
373 The -s (sum) switch causes funcnts to produce an additional table of
375 summed (integrated) background subtracted values, along with the
376 default table of individual values:
377 [sh] funcnts -s snr.ev "annulus(502,512,0,50,n=5)" "annulus(502,512,50,100)"
379 # source
380 # data file: snr.ev
381 # degrees/pix: 0.00222222
382 # background
383 # data file: snr.ev
384 # column units
385 # area: arcsec**2
386 # surf_bri: cnts/arcsec**2
387 # surf_err: cnts/arcsec**2
388 # summed background-subtracted results
390 upto net_counts error background berror area surf_bri surf_err
391 ---- ------------ --------- ------------ --------- --------- --------- ---------
392 1 2880.999 54.722 112.001 1.204 19520.00 0.148 0.003
393 2 3776.817 65.254 457.183 4.914 79679.98 0.047 0.001
394 3 4025.492 71.972 1031.508 11.087 179775.96 0.022 0.000
395 4 4185.149 80.109 1840.851 19.786 320831.94 0.013 0.000
396 5 4415.540 90.790 2873.460 30.885 500799.90 0.009 0.000
397 # background-subtracted results
399 reg counts error background berror area surf_bri surf_err
400 ---- ------------ --------- ------------ --------- --------- --------- ---------
401 1 2880.999 54.722 112.001 1.204 19520.00 0.148 0.003
402 2 895.818 35.423 345.182 3.710 60159.99 0.015 0.001
403 3 248.675 29.345 574.325 6.173 100095.98 0.002 0.000
404 4 159.657 32.321 809.343 8.699 141055.97 0.001 0.000
405 5 230.390 37.231 1032.610 11.099 179967.96 0.001 0.000
406 # the following source and background components were used:
408 source region(s)
409 ----------------
410 annulus(502,512,0,50,n=5)
411 reg counts pixels sumcnts sumpix
413 ---- ------------ --------- ------------ ---------
414 1 2993.000 305 2993.000 305
415 2 1241.000 940 4234.000 1245
416 3 823.000 1564 5057.000 2809
417 4 969.000 2204 6026.000 5013
418 5 1263.000 2812 7289.000 7825
419 background region(s)
421 --------------------
422 annulus(502,512,50,100)
423 reg counts pixels
425 ---- ------------ ---------
426 all 8656.000 23572
427 The -t and -e switches can be used to apply timing and exposure correc‐
429 tions, respectively, to the data. Please note that these corrections
430 are meant to be used qualitatively, since application of more accurate
431 correction factors is a complex and mission-dependent effort. The algo‐
432 rithm for applying these simple corrections is as follows:
433 C = Raw Counts in Source Region
435 Ac= Area of Source Region
436 Tc= Exposure time for Source Data
437 Ec= Average exposure in Source Region, from exposure map
438 B= Raw Counts in Background Region
440 Ab= Area of Background Region
441 Tb= (Exposure) time for Background Data
442 Eb= Average exposure in Background Region, from exposure map
443 Then, Net Counts in Source region is
445 Net= C - B * (Ac*Tc*Ec)/(Ab*Tb*Eb)
447 with the standard propagation of errors for the Error on Net. The net
449 rate would then be
450 Net Rate = Net/(Ac*Tc*Ec)
452 The average exposure in each region is calculated by summing up the
454 pixel values in the exposure map for the given region and then dividing
455 by the number of pixels in that region. Exposure maps often are gener‐
456 ated at a block factor > 1 (e.g., block 4 means that each exposure
457 pixel contains 4x4 pixels at full resolution) and funcnts will deal
458 with the blocking automatically. Using the -e switch, you can supply
459 both source and background exposure files (separated by ";"), if you
460 have separate source and background data files. If you do not supply a
461 background exposure file to go with a separate background data file,
462 funcnts assumes that exposure already has been applied to the back‐
463 ground data file. In addition, it assumes that the error on the pixels
464 in the background data file is zero.
465 NB: The -e switch assumes that the exposure map overlays the image file
467 exactly, except for the block factor. Each pixel in the image is
468 scaled by the block factor to access the corresponding pixel in the
469 exposure map. If your exposure map does not line up exactly with the
470 image, do not use the -e exposure correction. In this case, it still
471 is possible to perform exposure correction if both the image and the
472 exposure map have valid WCS information: use the -w switch so that the
473 transformation from image pixel to exposure pixel uses the WCS informa‐
474 tion. That is, each pixel in the image region will be transformed first
475 from image coordinates to sky coordinates, then from sky coordinates to
476 exposure coordinates. Please note that using -w can increase the time
477 required to process the exposure correction considerably.
478 A time correction can be applied to both source and background data
480 using the -t switch. The value for the correction can either be a
481 numeric constant or the name of a header parameter in the source (or
482 background) file:
483 [sh] funcnts -t 23.4 ... # number for source
485 [sh] funcnts -t "LIVETIME;23.4" ... # param for source, numeric for bkgd
486 When a time correction is specified, it is applied to the net counts as
488 well (see algorithm above), so that the units of surface brightness
489 become cnts/area**2/sec.
490 The -i (interval) switch is used to run funcnts on multiple column-
492 based intervals with only a single pass through the data. It is equiva‐
493 lent to running funcnts several times with a different column filter
494 added to the source and background data each time. For each interval,
495 the full funcnts output is generated, with a linefeed character (^L)
496 inserted between each run. In addition, the output for each interval
497 will contain the interval specification in its header. Intervals are
498 very useful for generating X-ray hardness ratios efficiently. Of
499 course, they are only supported when the input data are contained in a
500 table.
501 Two formats are supported for interval specification. The most general
503 format is semi-colon-delimited list of filters to be used as intervals:
504 funcnts -i "pha=1:5;pha=6:10;pha=11:15" snr.ev "circle(502,512,22)" ...
506 Conceptually, this will be equivalent to running funcnts three times:
508 funcnts snr.ev'[pha=1:5]' "circle(502,512,22)"
510 funcnts snr.ev'[pha=6:10]' "circle(502,512,22)"
511 funcnts snr.ev'[pha=11:15]' "circle(502,512,22)"
512 However, using the -i switch will require only one pass through the
514 data.
515 Note that complex filters can be used to specify intervals:
517 funcnts -i "pha=1:5&&pi=4;pha=6:10&&pi=5;pha=11:15&&pi=6" snr.ev ...
519 The program simply runs the data through each filter in turn and gener‐
521 ates three funcnts outputs, separated by the line-feed character.
522 In fact, although the intent is to support intervals for hardness
524 ratios, the specified filters do not have to be intervals at all. Nor
525 does one "interval" filter have to be related to another. For example:
526 funcnts -i "pha=1:5;pi=6:10;energy=11:15" snr.ev "circle(502,512,22)" ...
528 is equivalent to running funcnts three times with unrelated filter
530 specifications.
531 A second interval format is supported for the simple case in which a
533 single column is used to specify multiple homogeneous intervals for
534 that column. In this format, a column name is specified first, followed
535 by intervals:
536 funcnts -i "pha;1:5;6:10;11:15" snr.ev "circle(502,512,22)" ...
538 This is equivalent to the first example, but requires less typing. The
540 funcnts program will simply prepend "pha=" before each of the specified
541 intervals. (Note that this format does not contain the "=" character in
542 the column argument.)
543 Ordinarily, when funcnts is run on a FITS binary table (or a raw event
545 table), one integral count is accumulated for each row (event) con‐
546 tained within a given region. The -v "scol[;bcol]" (value column)
547 switch will accumulate counts using the value from the specified column
548 for the given event. If only a single column is specified, it is used
549 for both the source and background regions. Two separate columns, sepa‐
550 rated by a semi-colon, can be specified for source and background. The
551 special token '$none' can be used to specify that a value column is to
552 be used for one but not the other. For example, 'pha;$none' will use
553 the pha column for the source but use integral counts for the back‐
554 ground, while '$none;pha' will do the converse. If the value column is
555 of type logical, then the value used will be 1 for T and 0 for F.
556 Value columns are used, for example, to integrate probabilities instead
557 of integral counts.
558 If the -T (rdb table) switch is used, the output will conform to star‐
560 base/rdb data base format: tabs will be inserted between columns rather
561 than spaces and line-feed will be inserted between tables.
562 Finally, note that funcnts is an image program, even though it can be
564 run directly on FITS binary tables. This means that image filtering is
565 applied to the rows in order to ensure that the same results are
566 obtained regardless of whether a table or the equivalent binned image
567 is used. Because of this, however, the number of counts found using
568 funcnts can differ from the number of events found using row-filter
569 programs such as fundisp or funtable For more information about these
570 difference, see the discussion of Region Boundaries.
571
573 See funtools(n) for a list of Funtools help pages
574version 1.4.0 August 15, 2007 funcnts(1)