1funcen(1) SAORD Documentation funcen(1)
2
6 funcen - find centroid (for binary tables)
7
9 funcen [-i] [-n iter] [-t tol] [-v lev] <iname> <region>
10
12 -i # use image filtering (default: event filtering)
13 -n iter # max number of iterations (default: 0)
14 -t tol # pixel tolerance distance (default: 1.0)
15 -v [0,1,2,3] # output verbosity level (default: 0)
16
18 funcen iteratively calculates the centroid position within one or more
19 regions of a Funtools table (FITS binary table or raw event file).
20 Starting with an input table, an initial region specification, and an
21 iteration count, the program calculates the average x and y position
22 within the region and then uses this new position as the region center
23 for the next iteration. Iteration terminates when the maximum number of
24 iterations is reached or when the input tolerance distance is met for
25 that region. A count of events in the final region is then output,
26 along with the pixel position value (and, where available, WCS posi‐
27 tion).
28 The first argument to the program specifies the Funtools table file to
30 process. Since the file must be read repeatedly, a value of "stdin" is
31 not permitted when the number of iterations is non-zero. Use Funtools
32 Bracket Notation to specify FITS extensions and filters.
33 The second required argument is the initial region descriptor. Multiple
35 regions are permitted. However, compound regions (accelerators, vari‐
36 able argument regions and regions connected via boolean algebra) are
37 not permitted. Points and polygons also are illegal. These restrictions
38 might be lifted in a future version, if warranted.
39 The -n (iteration number) switch specifies the maximum number of itera‐
41 tions to perform. The default is 0, which means that the program will
42 simply count and display the number of events in the initial region(s).
43 Note that when iterations is 0, the data can be input via stdin.
44 The -t (tolerance) switch specifies a floating point tolerance value.
46 If the distance between the current centroid position value and the
47 last position values is less than this value, iteration terminates.
48 The default value is 1 pixel.
49 The -v (verbosity) switch specifies the verbosity level of the output.
51 The default is 0, which results in a single line of output for each
52 input region consisting of the following values:
53 counts x y [ra dec coordsys]
55 The last 3 WCS values are output if WCS information is available in the
57 data file header. Thus, for example:
58 [sh] funcen -n 0 snr.ev "cir 505 508 5"
60 915 505.00 508.00 345.284038 58.870920 j2000
61 [sh] funcen -n 3 snr.ev "cir 505 508 5"
63 1120 504.43 509.65 345.286480 58.874587 j2000
64 The first example simply counts the number of events in the initial
66 region. The second example iterates the centroid calculation three
67 times to determine a final "best" position.
68 Higher levels of verbosity obviously imply more verbose output. At
70 level 1, the output essentially contains the same information as level
71 0, but with keyword formatting:
72 [sh] funcen -v 1 -n 3 snr.ev "cir 505 508 5"
74 event_file: snr.ev
75 initial_region: cir 505 508 5
76 tolerance: 1.0000
77 iterations: 1
78 events: 1120
80 x,y(physical): 504.43 509.65
81 ra,dec(j2000): 345.286480 58.874587
82 final_region1: cir 504.43 509.65 5
83 Level 2 outputs results from intermediate calculations as well.
85 Ordinarily, region filtering is performed using analytic (event) fil‐
87 tering, i.e. that same style of filtering as is performed by fundisp
88 and funtable. Use the -i switch to specify image filtering, i.e. the
89 same style filtering as is performed by funcnts. Thus, you can perform
90 a quick calculation of counts in regions, using either the analytic or
91 image filtering method, by specifying the
92 -n 0 and optional -i switches. These two method often give different
93 results because of how boundary events are processed:
94 [sh] funcen snr.ev "cir 505 508 5"
96 915 505.00 508.00 345.284038 58.870920 j2000
97 [sh] funcen -i snr.ev "cir 505 508 5"
99 798 505.00 508.00 345.284038 58.870920 j2000
100 See Region Boundaries for more information about how boundaries are
102 calculated using these two methods.
103
105 See funtools(n) for a list of Funtools help pages
106version 1.4.0 August 15, 2007 funcen(1)