diff options
Diffstat (limited to 'funtools/doc/regbounds.html')
-rw-r--r-- | funtools/doc/regbounds.html | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/funtools/doc/regbounds.html b/funtools/doc/regbounds.html new file mode 100644 index 0000000..4fef30f --- /dev/null +++ b/funtools/doc/regbounds.html @@ -0,0 +1,179 @@ +<!-- =defdoc regbounds regbounds n --> +<HTML> +<HEAD> +<TITLE>Spatial Region Boundaries</TITLE> +</HEAD> +<BODY> + +<!-- =section regbounds NAME --> +<H2><A NAME="regbounds">RegBounds: Region Boundaries</A></H2> + +<!-- =section regbounds SYNOPSIS --> +<H2>Summary</H2> +Describes how spatial region boundaries are handled. + +<!-- =section regbounds DESCRIPTION --> +<H2>Description</H2> +<P> +The golden rule for spatial region filtering was first enunciated by +Leon VanSpeybroeck in 1986: + +<P> +<B>Each photon will be counted once, and no photon will be counted +more than once</B>. + +<P> +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. + +<H2>Image boundaries : radially-symmetric shapes (circle, annuli, ellipse)</H2> + +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: + +<UL> +<LI> the outer boundary of a symmetric shape does not include such pixels +<LI> the inner boundary of a symmetric shape (annulus) includes such pixels +</UL> + +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. + +<H2>Image Boundaries: non-radially symmetric shapes (polygons, boxes)</H2> + +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. + +<H2>Row Boundaries are Analytic</H2> + +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. + +<P> +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). + +<H2>Image Boundaries vs. Row Boundaries: Practical Considerations</H2> + +<P> +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: +<PRE> + fundisp test1.fits"[box(4219,3887,6,6,0)]" | wc + 8893 320148 3752846 +</PRE> +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: +<PRE> + ./funtable test1.fits"[box(4219,3887,6,6,0)]" test2.fits +</PRE> +Now run funcnts using the original filter on the derived file: +<PRE> + ./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 +</PRE> +There are 1044 rows (events) that pass the row filter in fundisp (or +funtable) but fail to make it through funcnts. Why? + +<P> +The reason can be traced to how analytic row filtering (fundisp, funtable) +differs from integerized pixel filtering(funcnts, funimage). Consider the +region: +<PRE> + box(4219,3887,6,6,0) +</PRE> +Analytically (i.e., using row filtering), positions will pass this +filter successfully if: +<PRE> + 4216 <= x <= 4222 + 3884 <= y <= 3890 +</PRE> +For example, photons with position values of x=4216.4 or y=3884.08 will pass. + +<P> +Integerized image filtering is different in that the pixels that will +pass this filter have centers at: +<PRE> + x = 4217, 4218, 4219, 4220, 4221, 4222 + y = 3885, 3886, 3887, 3888, 3889, 3890 +</PRE> +Note that there are 6 pixels in each direction, as specified by the region. +That means that positions will pass the filter successfully if: +<PRE> + 4217 <= (int)x <= 4222 + 3885 <= (int)y <= 3890 +</PRE> +Photons with position values of x=4216.4 or y=3884.08 will NOT pass. + +<P> +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. + +<P> +[It could be argued that the correct photon limits for floating point +row data really should be: +<PRE> + 4216.5 <= x <= 4222.5 + 3884.5 <= y <= 3890.5 +</PRE> +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.] + +<!-- =section regbounds SEE ALSO --> +<!-- =text See funtools(n) for a list of Funtools help pages --> +<!-- =stop --> + +<P> +<A HREF="./help.html">Go to Funtools Help Index</A> + +<H5>Last updated: November 16, 2005</H5> + +</BODY> +</HTML> |