1regbounds(n) SAORD Documentation regbounds(n)
2
6 RegBounds: Region Boundaries
7
9 Describes how spatial region boundaries are handled.
10
12 The golden rule for spatial region filtering was first enunciated by
13 Leon VanSpeybroeck in 1986:
14 Each photon will be counted once, and no photon will be counted more
16 than once.
17 This means that we must be careful about boundary conditions. For
19 example, if a circle is contained in an annulus such that the inner
20 radius of the annulus is the same as the radius of the circle, then
21 photons on that boundary must always be assigned to one or the other
22 region. That is, the number of photons in both regions must equal the
23 sum of the number of photons in each region taken separately.
24 With this in mind, the rules for determining whether a boundary image
26 pixel or table row are assigned to a region are defined below.
27 Image boundaries : radially-symmetric shapes (circle, annuli, ellipse)
29 For image filtering, pixels whose center is inside the boundary are
31 included. This also applies non-radially-symmetric shapes. When a
32 pixel center is exactly on the boundary, the pixel assignment rule is:
33 · the outer boundary of a symmetric shape does not include such pix‐
35 els
36 · the inner boundary of a symmetric shape (annulus) includes such
38 pixels
39 In this way, an annulus with radius from 0 to 1, centered exactly on a
41 pixel, includes the pixel on which it is centered, but none of its
42 neighbors.
43 These rules ensure that when defining concentric shapes, no pixels are
45 omitted between concentric regions and no pixels are claimed by two
46 regions. When applied to small symmetric shapes, the shape is less
47 likely to be skewed, as would happen with non-radially-symmetric rules.
48 These rules differ from the rules for box-like shapes, which are more
49 likely to be positioned adjacent to one another.
50 Image Boundaries: non-radially symmetric shapes (polygons, boxes)
52 For image filtering, pixels whose center is inside the boundary are
54 included. This also applies radially-symmetric shapes. When a pixel
55 center is exactly on the boundary of a non-radially symmetric region,
56 the pixel is included in the right or upper region, but not the left or
57 lower region. This ensures that geometrically adjoining regions touch
58 but don't overlap.
59 Row Boundaries are Analytic
61 When filtering table rows, the boundary rules are the same as for
63 images, except that the calculation is not done on the center of a
64 pixel, (since table rows, especially X-ray events rows, often have dis‐
65 crete, floating point positions) but are calculated exactly. That is,
66 an row is inside the boundary without regard to its integerized pixel
67 value. For rows that are exactly on a region boundary, the above rules
68 are applied to ensure that all rows are counted once and no row is
69 counted more than once.
70 Because row boundaries are calculated differently from image bound‐
72 aries, certain programs will give different results when filtering the
73 same region file. In particular, fundisp/funtable (which utilize ana‐
74 lytic row filtering) perform differently from funcnts (which performs
75 image filtering, even on tables).
76 Image Boundaries vs. Row Boundaries: Practical Considerations
78 You will sometimes notice a discrepancy between running funcnts on an
80 binary table file and running fundisp on the same file with the same
81 filter. For example, consider the following:
82 fundisp test1.fits"[box(4219,3887,6,6,0)]" ⎪ wc
84 8893 320148 3752846
85 Since fundisp has a 2-line header, there are actually 8891 photons that
87 pass the filter. But then run funtable and select only the rows that
88 pass this filter, placing them in a new file:
89 ./funtable test1.fits"[box(4219,3887,6,6,0)]" test2.fits
91 Now run funcnts using the original filter on the derived file:
93 ./funcnts test2.fits "physical; box(4219,3887,6,6,0)"
95 [... lot of processed output ...]
97 # the following source and background components were used:
99 source region(s)
100 ----------------
101 physical; box(4219,3887,6,6,0)
102 reg counts pixels
104 ---- ------------ ---------
105 1 7847.000 36
106 There are 1044 rows (events) that pass the row filter in fundisp (or
108 funtable) but fail to make it through funcnts. Why?
109 The reason can be traced to how analytic row filtering (fundisp, funt‐
111 able) differs from integerized pixel filtering(funcnts, funimage). Con‐
112 sider the region:
113 box(4219,3887,6,6,0)
115 Analytically (i.e., using row filtering), positions will pass this fil‐
117 ter successfully if:
118 4216 <= x <= 4222
120 3884 <= y <= 3890
121 For example, photons with position values of x=4216.4 or y=3884.08 will
123 pass.
124 Integerized image filtering is different in that the pixels that will
126 pass this filter have centers at:
127 x = 4217, 4218, 4219, 4220, 4221, 4222
129 y = 3885, 3886, 3887, 3888, 3889, 3890
130 Note that there are 6 pixels in each direction, as specified by the
132 region. That means that positions will pass the filter successfully
133 if:
134 4217 <= (int)x <= 4222
136 3885 <= (int)y <= 3890
137 Photons with position values of x=4216.4 or y=3884.08 will NOT pass.
139 Note that the position values are integerized, in effect, binned into
141 image values. This means that x=4222.4 will pass this filter, but not
142 the analytic filter above. We do this to maintain the design goal that
143 either all counts in a pixel are included in an integerized filter, or
144 else none are included.
145 [It could be argued that the correct photon limits for floating point
147 row data really should be:
148 4216.5 <= x <= 4222.5
150 3884.5 <= y <= 3890.5
151 since each pixel extends for .5 on either side of the center. We chose
153 to the maintain integerized algorithm for all image-style filtering so
154 that funcnts would give the exact same results regardless of whether a
155 table or a derived non-blocked binned image is used.]
156
158 See funtools(n) for a list of Funtools help pages
159version 1.4.0 August 15, 2007 regbounds(n)