rgsregions defines and constructs the various RGS event-selection regions, and adds them to the source list (see rgssources). Event-selection regions are closed two-dimensional shapes that may be used to filter the event list for the purpose of spectral analysis (see rgsspectrum). The regions are stored as extension tables in the source list, formatted according to the specifications of the “ASC FITS File Designers' Guide”. Image regions and the spatial background region refer to the plane of dispersion versus cross-dispersion (image plane) and select events based on their spatial coordinates. An image region selects events from a specific astrophysical source, while the spatial background region selects events that are presumed consistent with the lack of any particular source. The order regions refer to the plane of dispersion versus calibrated pulse-height (energy plane) and select events from a specific astrophysical source within a particular reflection order. The order regions exploit the over-determined nature of coordinates in the energy plane to greatly reduce spurious detections. For all types of regions (image, spatial background and order regions) the spectrumbinning parameter should be used to switch the dispersion plane unit from beta to lambda and vice versa.
In High Time Resolution (HTR) mode the entire cross-dispersion
dimension is collapsed into one row, inextricably mixing source and
background events together. There is no spatial background region in
this mode, and all image regions simply outline the exposure map with
no dependence on source position. Reproducing the same degenerate
image region for each source is redundant, of course, but
nevertheless preferable to specifying a separate region naming
convention just for HTR mode data. The missing spatial background
region is replaced by a collection of order-specific background
regions in the energy plane. Throughout this document a 
marks
items that do not apply to HTR mode data and a 
marks items
that apply only to HTR mode data.
The SRCLIST table contains two columns, SRC_SELECT
and BACK_SELECT, which control the default behavior of
rgsregions. Each source with SRC_SELECT set true is
given one image region and an order region for each reflection order
from one to the value of the maxorder parameter. In HTR mode
only there is an order background region paired with each order
region. The spatial background region is the entire exposed surface
in the image plane with regions around the more significant
identified sources excluded: each source with BACK_SELECT
set true is excluded from this region. The task parameters,
procsrcsexpr and exclsrcsexpr
, allow the user to
override these default selections without having to edit the
SRCLIST table. The procsrcsexpr expression replaces
the list derived from SRC_SELECT and the
exclsrcsexpr expression replaces the list derived from
BACK_SELECT. Specifying setflags=yes (non-default)
makes these replacements permanent in the SRCLIST table
itself (in HTR mode exclsrcsexpr is ignored and
BACK_SELECT is set to false for all sources). The
selection expressions are parsed in the context of the whole
SRCLIST table, including all of its columns and attributes.
The same basic procedure applies to the construction of all regions.
A region is an assemblage of separate polygons, each corresponding to
a specific node and source. Only nodes with an exposure map
extension in the event list are considered. The exposure map sets
the bounding limits of the polygon, and a
parameter—spatialres in the image plane and
orderres in the energy plane—sets the number of opposing
vertex pairs. The pairs are distributed evenly across the dispersion
axis so that the first and last pairs align with the extreme edges of
the node. Each vertex in a pair has the same dispersion coordinate
value, and with the other coordinate the pair spans some portion of
the applicable model curve: the canonical cross-dispersion PSF in the
image plane and the canonical pulse-height (PI) distribution in the
energy plane. This portion is specified differently for each type of
region. Note that in the case of the spatial background region each
of these polygons define a region that is excluded from the larger
region defined by the limits of the exposure map. The list of
sources excluded from the spatial background region is recorded in
its extension by a non-standard (not part of the ASC standard)
attribute, EXCLSRCS. For all regions (except for HTR image
regions) the number of vertex pairs per node is recorded by the
non-standard SPACING attribute.
The PI limits of an order region (at each vertex pair) are chosen to
provide the narrowest span that covers at least the specified
percentage of the model PI distribution. This percentage is
specified by the pdistincl parameter and is recorded in the
region extension by the non-standard COVERAGE attribute. And
additional parameter picutoff supplies the minimum cutoff in
PI. For all spatial regions the cross-dispersion off-axis angle of the
relevant astrophysical source divides the model cross-dispersion PSF
into two parts: upper and lower. The upper limit of an image region
(at each vertex pair) is chosen to cover at least the specified
percentage of the upper part. This percentage is specified by the
xdspabove parameter and is recorded in the region
extension by the non-standard COVABOVE attribute.
Similarly the lower limit is specified by the xdspbelow parameter, which is recorded as COVBELOW. For each excluded
source in the spatial background region a single parameter,
xpsfexcl, specifies both the upper and lower limits, and
is recorded in the region extension as COVERAGE.
An addition for easing the analysis of extended sources is provided with the
parameters xdspregions and xdspbackground. They define
rectangular regions in (units arcminutes)in cross-dispersion direction. Any
number of rectangular regions can be defined at once, which may apply to a
central
position of a source defined under rgssources. So, a call to
rgsregions
as following:
> rgsregions srclist='PxxxSRCLI_0000.FIT' evlist='PxxxEVENLI0000.FIT' xdspregions="-1.0 0.0 0.0 1.0" xdspbackground="1.5 2.0"
will define two "source" rectangular regions with DELTA_XDSP=[1.0,0.0] arcmin
and DELTA_XDSP=[0.0,1.0] arcmin respectively and one rectangular
"background" region with DELTA_XDSP=[1.5,2.0] arcmin.
The on-board calibration sources are characterized simply as rectangles in the energy plane. These rectangles are always excluded from the order regions if there is overlap. This can usually be seen in the second order region, but not in the first order region for an on-axis source. The image plane footprint of the calibration sources is not excluded from the spatial regions because that would eliminate too many valid photons for off-axis sources. Another peculiarity of the order regions is the silicon edge, where the PI distribution function changes shape abruptly. To ensure that this edge is properly resolved, two extra pairs of vertices are added to the relevant polygon just on either side of the edge. The HTR mode order background regions are just the regular order regions transformed by reflecting each vertex pair vertically around the upper vertex. To avoid overlapping the second-order region the vertex pairs of the second-order region are used in the first-order background region for chips 1, 2 and 3.
If the source list already contains a region that rgsregions is supposed to add, that region is inspected to determine whether it was constructed to the specifications established under the current task parameters; if so (or if it is protected) it is left in place, otherwise it is deleted and replaced. A region is considered protected if the non-standard PROTECT attribute is missing or set true. The protect parameter can be used to mark each region added or replaced as protected, and once a region is so marked it must be manually deleted by the user before it can be replaced by rgsregions. This feature should be used very selectively. At verbosity level four (Sparse) the name of each region added or replaced is noted.
Two final non-standard attributes of all regions, which are provided solely for their diagnostic value, are PIX_ENCL and PIX_AREA. These describe the enclosed area of the region in terms of the number of pixels enclosed and the area of a pixel. The dimensions of a pixel are: one dispersion channel width by one cross-dispersion channel width in the image plane, and one dispersion channel width by one PI unit in the energy plane. The channel widths are as defined in the event list.
