XMM-Newton SAS Home Page
XMM-Newton Science Analysis System

rgsregions (rgsregions-1.23) [xmmsas_20230412_1735-21.0.0]


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 \dag marks items that do not apply to HTR mode data and a \ddag 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$^{\dag }$, 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$^{\dag }$ 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$^{\dag }$ parameter and is recorded in the region extension by the non-standard COVABOVE$^{\dag }$ attribute. Similarly the lower limit is specified by the xdspbelow$^{\dag }$ parameter, which is recorded as COVBELOW$^{\dag }$. For each excluded source in the spatial background region a single parameter, xpsfexcl$^{\dag }$, 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.

XMM-Newton SOC -- 2023-04-16