diff options
Diffstat (limited to 'funtools/doc/pod/regbounds.pod')
-rw-r--r-- | funtools/doc/pod/regbounds.pod | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/funtools/doc/pod/regbounds.pod b/funtools/doc/pod/regbounds.pod new file mode 100644 index 0000000..c63a0bd --- /dev/null +++ b/funtools/doc/pod/regbounds.pod @@ -0,0 +1,203 @@ +=pod + +=head1 NAME + + + +B<RegBounds: Region Boundaries> + + + +=head1 SYNOPSIS + + + + +Describes how spatial region boundaries are handled. + + + +=head1 DESCRIPTION + + + + + +The golden rule for spatial region filtering was first enunciated by +Leon VanSpeybroeck in 1986: + + +Each photon will be counted once, and no photon will be counted +more than once. + + +This means that we must be careful about boundary +conditions. For example, if a circle is contained in an annulus such +that the inner radius of the annulus is the same as the radius of the +circle, then photons on that boundary must always be assigned to one +or the other region. That is, the number of photons in both regions +must equal the sum of the number of photons in each region taken +separately. + +With this in mind, the rules for determining whether a boundary image +pixel or table row are assigned to a region are defined below. + +B<Image boundaries : radially-symmetric shapes (circle, annuli, ellipse)> + +For image filtering, pixels whose center is inside the boundary are +included. This also applies non-radially-symmetric shapes. When a +pixel center is exactly on the boundary, the pixel assignment rule is: + + + +=over 4 + + + + +=item * + +the outer boundary of a symmetric shape does not include such pixels + + +=item * + +the inner boundary of a symmetric shape (annulus) includes such pixels + + +=back + + + +In this way, an annulus with radius from 0 to 1, centered exactly on a +pixel, includes the pixel on which it is centered, but none of its +neighbors. + +These rules ensure that when defining concentric shapes, no pixels are +omitted between concentric regions and no pixels are claimed by two +regions. When applied to small symmetric shapes, the shape is less +likely to be skewed, as would happen with non-radially-symmetric +rules. These rules differ from the rules for box-like shapes, which +are more likely to be positioned adjacent to one another. + +B<Image Boundaries: non-radially symmetric shapes (polygons, boxes)> + +For image filtering, pixels whose center is inside the boundary are +included. This also applies radially-symmetric shapes. When a pixel +center is exactly on the boundary of a non-radially symmetric region, +the pixel is included in the right or upper region, but not the left +or lower region. This ensures that geometrically adjoining regions +touch but don't overlap. + +B<Row Boundaries are Analytic> + +When filtering table rows, the boundary rules are the same as for +images, except that the calculation is not done on the center of a +pixel, (since table rows, especially X-ray events rows, often have +discrete, floating point positions) but are calculated exactly. That +is, an row is inside the boundary without regard to its integerized +pixel value. For rows that are exactly on a region boundary, the +above rules are applied to ensure that all rows are counted once and +no row is counted more than once. + + +Because row boundaries are calculated differently from image boundaries, +certain programs will give different results when filtering the same +region file. In particular, fundisp/funtable (which utilize analytic +row filtering) perform differently from funcnts (which performs image +filtering, even on tables). + +B<Image Boundaries vs. Row Boundaries: Practical Considerations> + + +You will sometimes notice a discrepancy between running funcnts on an +binary table file and running fundisp on the same file with the same filter. +For example, consider the following: + + fundisp test1.fits"[box(4219,3887,6,6,0)]" | wc + 8893 320148 3752846 + +Since fundisp has a 2-line header, there are actually 8891 photons +that pass the filter. But then run funtable and select only the +rows that pass this filter, placing them in a new file: + + ./funtable test1.fits"[box(4219,3887,6,6,0)]" test2.fits + +Now run funcnts using the original filter on the derived file: + + ./funcnts test2.fits "physical; box(4219,3887,6,6,0)" + + [... lot of processed output ...] + + # the following source and background components were used: + source region(s) + ---------------- + physical; box(4219,3887,6,6,0) + + reg counts pixels + ---- ------------ --------- + 1 7847.000 36 + +There are 1044 rows (events) that pass the row filter in fundisp (or +funtable) but fail to make it through funcnts. Why? + + +The reason can be traced to how analytic row filtering (fundisp, funtable) +differs from integerized pixel filtering(funcnts, funimage). Consider the +region: + + box(4219,3887,6,6,0) + +Analytically (i.e., using row filtering), positions will pass this +filter successfully if: + + 4216 <= x <= 4222 + 3884 <= y <= 3890 + +For example, photons with position values of x=4216.4 or y=3884.08 will pass. + + +Integerized image filtering is different in that the pixels that will +pass this filter have centers at: + + x = 4217, 4218, 4219, 4220, 4221, 4222 + y = 3885, 3886, 3887, 3888, 3889, 3890 + +Note that there are 6 pixels in each direction, as specified by the region. +That means that positions will pass the filter successfully if: + + 4217 <= (int)x <= 4222 + 3885 <= (int)y <= 3890 + +Photons with position values of x=4216.4 or y=3884.08 will NOT pass. + + +Note that the position values are integerized, in effect, binned into +image values. This means that x=4222.4 will pass this filter, but not +the analytic filter above. We do this to maintain the design goal that +either all counts in a pixel are included in an integerized filter, or +else none are included. + + +[It could be argued that the correct photon limits for floating point +row data really should be: + + 4216.5 <= x <= 4222.5 + 3884.5 <= y <= 3890.5 + +since each pixel extends for .5 on either side of the center. We chose +to the maintain integerized algorithm for all image-style filtering so +that funcnts would give the exact same results regardless of whether +a table or a derived non-blocked binned image is used.] + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + + +=cut |