Документ взят из кэша поисковой машины. Адрес оригинального документа : http://xmm.vilspa.esa.es/sas/6.0.0/doc/rgsregions.ps.gz
Дата изменения: Thu Mar 18 23:35:08 2004
Дата индексирования: Tue Oct 2 08:01:38 2012
Кодировка:

XMM-Newton Science Analysis System Page: 1
rgsregions
March 18, 2004
Abstract
This task constructs RGS event-selection regions. It reads an event list processed
by rgslter and modies a source list created by rgssources. Flag columns in the
SRCLIST table determine which regions are added to the source list. This task should
be run any time the existing set of regions gets out of date. Existing regions are
replaced only as necessary. As a convenience, this task may also be used to edit the
ag columns in the SRCLIST table.
1 Instruments/Modes
Instrument Mode
RGS Spectroscopy
RGS High Time Resolution
2 Use
pipeline processing yes
interactive analysis yes
3 Description
rgsregions denes 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
lter 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 specications 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 specic 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 specic
astrophysical source within a particular re ection order. The order regions exploit the over-determined
nature of coordinates in the energy plane to greatly reduce spurious detections.
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
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 2
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-specic background regions in the energy
plane. Throughout this document a y marks items that do not apply to HTR mode data and a z marks
items that apply only to HTR mode data.
The SRCLIST table contains two columns, SRC SELECT and BACK SELECT, which control the default behav-
ior of rgsregions. Each source with SRC SELECT set true is given one image region and an order region
for each re ection 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 signicant identied sources excluded:
each source with BACK SELECT set true is excluded from this region. The task parameters, procsrcsexpr
and exclsrcsexpr y , 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 specic 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 y 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 rst 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 specied dierently for each type of region. Note that in the case
of the spatial background region each of these polygons dene a region that is excluded from the larger
region dened 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 specied percentage of the model PI distribution. This percentage is specied by the
pdistincl parameter and is recorded in the region extension by the non-standard COVERAGE attribute.
For all spatial regions the cross-dispersion o-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 specied percentage of the upper part. This percentage
is specied by the xdspabove y parameter and is recorded in the region extension by the non-standard
COVABOVE y attribute. Similarly the lower limit is specied by the xdspbelow y parameter, which is recorded
as COVBELOW y . For each excluded source in the spatial background region a single parameter, xpsfexcl y ,
species both the upper and lower limits, and is recorded in the region extension as COVERAGE.
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 rst 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 o-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 re ecting each vertex pair
vertically around the upper vertex. To avoid overlapping the second-order region the vertex pairs of the
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 3
second-order region are used in the rst-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 specications 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 nal 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 dened in the event list.
4 Parameters
This section documents the parameters recognized by this task (if any).
Parameter Mand Type Default Constraints
srclist yes dataset srclist.ds
Source denition list: a dataset containing the SRCLIST table, and to which the region extensions will be
added.
evlist no dataset
Event list: a dataset containing the EVENTS table and exposure map extensions. Not modied. The
default le name is inferred from the input srclist name as: *EVENLI????.* if there are ten characters
before the suфx, and otherwise just evlist.*.
maxorder no integer 2 1-
The number of re ection orders to be processed for each selected source. One order region is added for
each order, starting from rst order.
spatialres no integer 5 2-
The dispersion-axis spacing of vertices for image regions and the spatial background region, specied as
the number of vertices across a node. Not applicable in HTR mode.
orderres no integer 3 2-
The dispersion-axis spacing of vertices for order regions, specied as the number of vertices across a node.
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 4
xpsfbelow no real 90 0-100
Downward size of image regions, specied by the percentage of the cross-dispersion PSF covered between
the source cross-dispersion o-axis angle and the lower of each pair of vertices with the same dispersion
coordinate. Not applicable in HTR mode.
xpsfabove no real 90 0-100
Upward size of image regions, specied by the percentage of the cross-dispersion PSF covered between
the source cross-dispersion o-axis angle and the upper of each pair of vertices with the same dispersion
coordinate. Not applicable in HTR mode.
xpsfexcl no real 95 0-100
Size of the exclusion regions in the spatial background region, specied by the percentage of the cross-
dispersion PSF covered between each pair of vertices with the same dispersion coordinate and associated
source. Not applicable in HTR mode.
pdistincl no real 90 0-100
Size of order regions, specied by the percentage of the pulse-height distribution covered between each
pair of vertices with the same dispersion coordinate.
procsrcsexpr no string
Selection expression indicating which sources to process for image and order regions. The default species
the sources agged with SOURCE SELECT in the SRCLIST table.
exclsrcsexpr no string
Selection expression indicating which sources to exclude from the spatial background region. The default
species the sources agged with BACK SELECT in the SRCLIST table. Not applicable in HTR mode.
set ags no boolean no
If true, the selection expressions given by procsrcsexpr and exclsrcsexpr are used to set the re-
spective SRCLIST table ag columns, SOURCE SELECT and BACK SELECT. In HTR mode the inapplicable
BACK SELECT is simply set to false for all sources.
protect no boolean no
Value for the PROTECT attribute in each region added or replaced. Regions created with protect=yes
cannot be replaced by rgsregions without prior manual intervention.
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 5
5 Errors
This section documents warnings and errors generated by this task (if any). Note that warnings and
errors can also be generated in the SAS infrastructure libraries, in which case they would not be docu-
mented here. Refer to the index of all errors and warnings available in the HTML version of the SAS
documentation.
noExposureMaps (error)
The event list le does not contain any exposure map extensions. The exposure map for at
least one node is a required input. See task rgslter.
fractionalCoverage (warning)
The indicated region coverage parameter (xpsfincl, xpsfexcl, or pdistincl) was given a
value greater than zero but less than one, suggesting that the user has forgotten that these
parameters are specied as percentages.
corrective action: No corrective action is taken, but these regions will be too narrow to
have any practical value. Specify zero to avoid this warning and get eectively the same
result.
protectedRegion (warning)
A region selected for update is protected. Use a FITS editor to delete the region extension
and then try again.
corrective action: The requested update of the region does not occur.
emptyRegion (warning)
A region has been produced which encloses no pixels in the channel space. This is most
likely to occur with the spatial background region, particularly when more than one source
is designated for exclusion.
corrective action: No corrective action is taken, but this warning should be taken seriously
by the user, especially if the region in question is not the spatial background region.
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 6
6 Input Files
srclist
The SRCLIST table, as created by rgssources, is a required input, and is not modied. The
PRIMESRC attribute and the following columns are accessed.
INDEX int32 source identier
RGS DISP RGS XDSP real32 RGS oaxis angles (arcmin)
SRC SELECT int8 ag for standard processing
BACK SELECT int8 ag for background exclusion
evlist
{ Attribute INSTRUME is required.
{ EVENTS table
The EVENTS table, as last modied by rgsangles, is a required input, and is not
modied. Columns BETA CHANNEL and XDSP CHANNEL are accessed for the following
attributes: TCDLT, TCRVL, TCRPX, TLMIN and TLMAX.
{ EXPMn nn
A set of node-specic exposure map extensions, as created by evlistcomb, is a required
input. These are not modied. The array dimensions and the attributes, CCDID,
CCDNODE, CDELT1, CRVAL1, CRPIX1, CDELT2, CRVAL2, CRPIX2 are accessed.
7 Output Files
srclist
The region extensions added to the source list comply with the \ASC FITS File Designers'
Guide" specications. Some non-standard attributes are also provided with every region:
PROTECT protected from routine replacement
SPACING number of vertices across each node
PIX ENCL number of pixels enclosed
PIX AREA area of a pixel (units vary)
Additionally, the non-standard COVERAGE attribute is provided for order regions and the
spatial background region, and the non-standard pair, COVBELOW y and COVABOVE y , is provided
for image regions. These document the percentages used in constructing the regions. Unless
protected, existing versions of the regions may be overwritten if they are not compatible
with the given parameters. The regions are of four kinds:
{ spatial background region y
RGS BACKGROUND
There is only one extension of this kind. In addition to the attributes described above,
the list of source identiers for the image regions excluded from the background is also
provided as EXCLSRCS.
{ image regions
RGS SRC SPATIAL
There is one extension of this kind for each selected source. In HTR mode the inappli-
cable attributes SPACING, COVBELOW and COVABOVE are omitted.
{ order regions
RGS SRC ORDER
There is one extension of this kind for each requested order, for each selected source.
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 7
{ order background regions z
RGS SRC ORD BKG
There is one extension of this kind for each requested order, for each selected source.
8 Algorithm
Source Selections
if --procsrcsexpr is non-empty:
use --procsrcsexpr to select sources for image and order regions
if --setflags is true:
update SRC_SELECT column with this result
else:
initialize selected sources from SRC_SELECT column
Excluded Source Selections
if --exclsrcsexpr is non-empty:
use --exclsrcsexpr to select sources for exclusion from background region
if --setflags is true:
update BACK_SELECT column with this result
else:
initialize excluded sources from BACK_SELECT column
Spatial Background Region
unless a correctly specified or protected background region exists:
initialize empty region
for each node:
add polygon bounding the exposed surface
for each excluded source:
intersect polygon excluding --xpsfexcl percent of cross-dispersion PSF
scan region for total number of enclosed pixels
add region to source list
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 8
Image and Order Regions
for each selected source:
unless a correctly specified or protected image region exists:
initialize empty region
for each node:
if Spectroscopy:
add polygon enclosing the xdsp PSF from --xpsfbelow to --xpsfabove
else: (High Time Resolution)
add polygon enclosing all exposure
scan region for total number of enclosed pixels
add region to source list
for each order (1 to --maxorder):
unless a correctly specified or protected order region exists:
initialize empty region
for each node:
add polygon enclosing --pdistincl percent of PI distribution
add excluded rectangle to each node with a calibration source
scan region for total number of enclosed pixels
add region to source list
unless Spectroscopy or a correctly specified or protected background order region exists:
initialize empty region
for each node:
if first order and CCD < 4: switch to second order
construct polygon enclosing --pdistincl percent of PI distribution
transform it by reflecting around top vertex at each vertex pair
add transformed polygon to region
add excluded rectangle to each node with a calibration source
scan region for total number of enclosed pixels
add region to source list
xmmsas 20040318 1831-6.0.0

XMM-Newton Science Analysis System Page: 9
9 Comments
There are a few hardwired calibration constants that ought to be obtained via the CAL:
position and width (in dispersion) of the silicon edge
positions and widths (in PI) of the calibration source footprints
References
xmmsas 20040318 1831-6.0.0