Документ взят из кэша поисковой машины. Адрес оригинального документа : http://xmm.vilspa.esa.es/sas/7.1.0/doc/rgssources.ps.gz
Дата изменения: Mon Jul 9 05:24:04 2007
Дата индексирования: Tue Oct 2 08:43:50 2012
Кодировка:
Поисковые слова: tail
XMM-Newton Science Analysis System Page: 1
rgssources
July 9, 2007
Abstract
The task constructs a list of sources that are to be processed by RGS pipeline.
1 Instruments/Modes
Instrument Mode
RGS SPECTROSCOPY
2 Use
pipeline processing yes
interactive analysis yes
3 Description
3.1 Introduction.
This task creates the RGS source list. This source list is used as the main reference for the de nition of
selection regions by rgsregion and for the creation of the response matrix by rgsrmfgen. For the latter,
knowledge of the source position is required in order to correctly determine the wavelength scale. In
pipeline use, the RGS source list is used to indicate those sources for which products should be extracted.
3.2 Environment variables.
In nearly all cases, rgssources requires information from the CCF. (The exceptions are trivial cases such
as running with filemode=`modify' but with both addusersource and withepicset = `no'.) Because
the exceptions are insigni cant and involve complicated logic to disentangle, it has been made mandatory
to supply a CCF to the task. The location of the CCF is pointed to in the usual way, ie via the environment
variable SAS CCF.
The CCF interface needs to know whether the instrument is RGS1 or RGS2 in order to provide the
correct boresight etc. Although the instexpid parameter has not been made mandatory, the task will
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 2
fail with an error if the information is not ultimately available. See the algorithm section 7 for details of
the way the task attempts to deduce the instrument.
The task may also require information from the ODF summary le, in which case the variable SAS ODF
must be set before running the task. This information may be necessary for one of two reasons:
 The attitude must be calculated.
 It is desired to write observation-speci c keywords to the source list header.
Every attempt has been made to avoid this requirement where possible and thus cater to the user who
does not have the entire ODF at their ngertips.
3.3 Where the data comes from.
The source data can come from several sources:
 A source list from a previous run of rgssources (note that from version 5.1, rgssources is
now compatible with all earlier source list formats).
 The proposed target source.
 The attitude of the spacecraft.
 A source list output by either emldetect or eboxdetect.
 A source position supplied on the command line by the user.
These are described individually below.
3.3.1 Previous RGS source list.
The task rgssources can either modify a previously-created source list or create a new one, depending
on the value of the parameter filemode. If filemode=`create', the name of the newly created le is
read from parameter srclist. If on the other hand filemode=`modify', the name of the existing le
to be edited must instead be supplied to srclist. Note that if filemode=`create' and srclist gives
the name of an existing le, this existing le may (subject to the SAS CLOBBER setting) be completely
overwritten.
Although sources are never deleted from previous lists, some of the column entries may be altered. Older-
format source tables are automatically converted to conform to the current format. (Note however that
NO other extensions to the source list le are upgraded in format by rgssources.)
If filemode=`create', the name of the RGS instrument must be supplied via the parameter instexpid.
If on the other hand filemode=`modify', the instrument designation is read from header of the old le.
Note that all sources must originally have come from one of the following three categories. Their labels
(see description of column LABEL, section 5) will re ect that fact.
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 3
3.3.2 Proposal and Attitude sources.
These are now added automatically by the task and there are no longer any command-line parameters
that relate to them directly. If a previous RGS list is supplied (ie filemode=`modify'), the proposal
source from that le is used; otherwise this information is read from the ODF. If a previous RGS list is
supplied, and changeattitude=no, the attitude source from that le is used; otherwise the entries from
this source are calculated from those parameters relating to the attitude (see subsection 6.2).
The respective values of the LABEL column for the proposal and attitude sources are `PROPOSAL' and
`ONAXIS'.
3.3.3 EPIC source list.
A source list compiled by either emldetect or eboxdetect can be added to the RGS source list. This
is accomplished by setting withepicset=yes and giving the name of the le via epicset.
These EPIC source lists include positions and count rates for each source within several di erent energy
bands. However the RGS cameras only have signi cant sensitivity in the band 2{3 (500{2000 eV) (in the
standard de nition at the time of writing in 2006). Therefore only EPIC sources which have ID BAND=2
or =3 should be copied to the RGS list | this is the default behaviour, although users can specify their
favourite bands via bandids. Note that older-format lists may contain just band 2 sources, or band 1
sources (if even older), or epic sources from all bands.
More than one EPIC source list can be added to the RGS list by running rgssources several times in
`modify' mode on the same RGS set but with di erent EPIC sets as input.
The values of the LABEL column of the RGS source list must be unique. For EPIC sources this is partially
achieved by including the value of the EPIC source list column ML ID SRC or BOX ID SRC in the label for
that source. These column values are unique within the EPIC source list itself. However this number
becomes non-unique when several EPIC lists are included in the one RGS le. To retain uniqueness of
the LABEL value, another parameter is provided: epiclabelprefix. The LABEL value is constructed from
the string supplied via this parameter (default value is `EPIC'), followed by the digits of the ML ID SRC
or BOX ID SRC value. Note that all LABEL values are converted to upper case.
3.3.4 User-supplied source.
The user can supply the position, brightness and label of a source. The position can be speci ed in either
of two styles, controlled via the parameter positionstyle: if positionstyle=`radec' (the default), the
source J2000 right ascension and declination can be entered (in decimal degrees) via the parameters ra and
dec; if positionstyle=`wrtatt', the source position with respect to the spacecraft pointing direction,
in the cartesian dispersion/cross-dispersion basis, can be entered via the parameters deltadisp and
deltaxdsp. The units of the latter two are arcminutes.
The estimated brightness in counts per second can be entered via the parameter rate; the user source
label via label.
More than one user source can be added to the RGS list by running rgssources several times in `modify'
mode on the same RGS set, with addusersource=yes each time. Note that a di erent value of label
must be chosen each time, in fact label must be di erent to any of the values in column LABEL of the
old list.
Note that all LABEL values are converted to upper case, hence a source with label given as `Fred' will
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 4
con ict with a previous source supplied with label=`fred' since they each get translated to `FRED'.
3.4 Prime source.
The prime source is used in the pipeline by rgsangles as a reference to calculate approximate corrections
for attitude variation errors in the BETA values of events. rgssources always selects one member of its
output list to be the prime source and stores the INDEX column value of this source in the source-table
keyword PRIMESRC.
rgssources also calculates a confusion value between every other source and the prime source (see
subsection 5.2); these values are stored in the column CONFUSION.
The prime source can be designated in ve ways, via a number of di erent parameters:
 The previous value can be retained.
 The user-supplied source can be designated as the prime source.
 The brightest source can be designated as the prime source.
 The prime source can be designated via one the parameters primelabel, primeindex or
primeexpression, given the appropriate setting of primestyle.
 The task can be allowed to choose the best candidate (see the following subsection).
To see how these interact in detail, see the algorithm in section 7, also the examples in section 6; however
the order of precedence is roughly as the entries appear in the list above.
3.5 Auto selection of Prime source.
Here is the outline of the current algorithm to choose the (possibly the most reasonable) Prime source
when primestyle=auto. This is, for example, used in the Pipeline processing (section 6.1). Given
doconfusion=yes, withepicset=yes and enablefilter=yes, the selected Prime source will be
1. the proposed source, if the proposal source is within the FOV (of RGS) and is not confused
with other EPIC sources.
A likely scenario is this: the central chip of EPIC is used in the timing mode, where no EPIC
source list is extracted; as a result no source appears at the proposed position, which is most
likely to be at the EPIC central chip. Indeed if the observation is meant to be mainly for
RGS, the source is quite likely to be too bright to observe in the standard mode in EPIC.
2. the proposed source, if the proposal source is within the FOV (of RGS) and is confused with
more than one EPIC source.
A likely scenario is this: the proposed source is so bright that causes pile-ups in the EPIC
chip, leading to many spurious EPIC detections around it. In that case none of the EPIC
detection is reliable, so the proposed position would be better than those.
3. the brightest EPIC source, if either of the above is not the case, and if there are EPIC
sources in the FOV.
A likely scenario is this: there is one bright EPIC source detected as a confused source with
the proposed source; in this case the proposed position of the source is slightly wrong, and so
the position of the EPIC bright source is probably more appropriate for the RGS analysis.
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 5
Note that the brightest EPIC source (within the RGS FOV) may not be the source that
confuses with the proposed source, i.e., a completely di erent source from the proposed one
may be picked up as the Prime source, if the source is brighter than the supposedly proposed
one.
4. the ONAXIS source (=position), if none of the above is the case | ie., the last resort.
A likely scenario is this: the proposed position happens to be out of the FOV and no EPIC
source is available (within the FOV).
3.6 Attitude parameters.
The attitude is de ned as the pointing direction plus the position- or roll-angle of the spacecraft. It is
necessary to de ne the attitude for rgssources because the task must calculate values for the columns
DELTA DISP, DELTA XDSP, FOV PHI and FOV R, which record the source positions with respect to the
attitude.
In the case that filemode=`modify', the attitude is left by default at the value in the previous le.
To alter the attitude stored in the le while in this filemode, the parameter changeattitude must be
speci cally set by the user to `yes'. Assuming that this is done, the attitude can then either be calculated
(attstyle=`start', `mean', `median' or `expmedian') or input directly by the user (attstyle=`user', then
supply attra, attdec and attapos). The four types of calculation are brie y described as follows:
 attstyle=`start': the attitude at the start of the exposure is used.
 attstyle=`mean': the mean value of the attitude (as sampled in the attitude history le)
is used. This value is read from the output le from atthkgen.
 attstyle=`median': the median value of the attitude (as sampled in the attitude history
le) is used.This value is read from the output le from atthkgen.
 attstyle=`expmedian': the task att lter lters the attitude data such that only time
values within the exposure duration remain. This task also calculates the usual set of
means, medians etc for thsi restricted set of attitude data. With attstyle=`expmedian',
rgssources reads the median value of the attitude during the exposure from the output le
from att lter.
3.7 Upgrading the format.
rgssources is now backward-compatible, ie it can read source lists which were created in the pre-sas-5.1
format. The task attempts to upgrade the format of these older les and in fact can be used to do
this exclusively, without the necessity to add to or otherwise modify the source list. The upgrading is
performed by a public subroutine called convertOldFiles located in the module rgssources update.f90.
The interface is as follows:
subroutine convertOldFiles(setName, writeObsKwds, writeExpKwds&
, instrumentId, expId)
implicit none
character(*), intent(in) :: setName
logical, intent(in), optional :: writeObsKwds, writeExpKwds
integer(int32), intent(in), optional :: instrumentId, expId
end subroutine convertOldFiles
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 6
The algorithm is described in section 7.
The upgrade consists of the the following steps:
 The source list table is renamed from SOURCES to SRCLIST.
 The attitude keywords RA REF, DEC REF and APOS REF are moved from the source table to the
primary header, converted from radians to decimal degrees, and renamed RA PNT, DEC PNT
and PA PNT.
 The INSTRUME keyword is written.
 Standard values are written to the TELESCOP, FILTER, ORIGIN, RADECSYS and EQUINOX key-
words.
 (Optional) values are written to the OBS MODE, OBS ID, OBJECT and OBSERVER keywords.
These require SAS ODF to be set.
 (Optional) values are written to the DATAMODE and EXPIDSTR keywords. These require
SAS ODF to be set.
 The column names are converted.
 The column values are converted. See notes below.
 If there were sources of epic origin in the old-format list, the appropriate sets of E EXPRnn,
E CONTnn, E mBNDnn (which used to be E BANDnn before Ver.6.0) and E FILTnn keywords are
written. These all have value `UNKNOWN' except E mBNDnn.
Notes on the column value conversion:
 INDEX and RATE values are retained.
 Sources can be divided into those for which the coordinates are xed with respect to the
celestial sphere and those which are xed with respect to the reference attitude. (Since the
latter may take on slightly di erent values, depending on how it is calculated, the two are
not quite the same thing.) In older-format les, the proposal and all epic and user sources
fell into the former category and the onaxis and o axis sources into the latter. The former
sources have FIXED ON SKY set to true, vice versa for the latter. RA and DEC values are
retained for all the FIXED ON SKY sources, and DELTA DISP, DELTA XDSP, FOV PHI and FOV R
are recalculated; for the non-FIXED ON SKY sources it is the other way around.
 The LABEL values of the proposal and onaxis sources are uppercase-converted respectively
to `PROPOSAL' and `ONAXIS'.
 For epic sources, ID BAND and ML ID SRC are used to construct (hopefully) unique LABEL val-
ues, of the form `OLDEPICbbnnnnn', where bb and nnnnn are respectively the ID BAND and
ML ID SRC numbers. A tally is kept of the number of di erent ID BAND numbers encountered
and these are used to assign values to the EPIC FILE column of these sources.
 O axis sources are given LABEL values of `OFFAXISnnnnn' where nnnnn is the number of
o axis sources so far detected in the le.
 Sources which have old LABEL values which are neither `proposal', `onaxis', `epic' or `o axis'
are presumed to be user-added sources. Their LABEL values are just converted to upper-case.
Note however that rgssources will fail with an error if non-unique labels are detected.
 A non-zero value of SRC SELECT is translated into a true value of PROCESS.
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 7
 A non-zero value of BACK SELECT is translated into a true value of BKG EXCLUDE.
 CONFUSION is calculated from scratch.
The prime source is left untouched (although rgssources will fail if its INDEX value does not exist in the
le). No other extensions of the source list le are altered or deleted during this upgrade process.
4 Input Files
1. EPIC sources set with a binary extension table named SRCLIST (required only if withepicset
= `yes').
The following columns need to be present in this table:
 RA: this value is copied into the RGS column of the same name.
 DEC: this value is copied into the RGS column of the same name.
 ML ID SRC (if the source list was made by emldetect) or BOX ID SRC (if the source list
was made by eboxdetect): this number is included in the LABEL value of the source
in the RGS list.
 ID BAND: this value is used in distinguishing the energy band in calculating RATE (see
below).
 RATE: the sum of these values in the speci ed energy bands are written in the output
RGS list. The energy band (ID) is listed in the above-mentioned ID BAND column,
whereas the energy band IDs are speci ed in bandids command-line parameter.
2. RGS sources set as described in the `Output les' section (required only if filemode =
`modify').
3. The attitude history le created by atthkgen (required only if ((filemode = `modify' and
changeattitude = `yes') or filemode = `create') and attstyle = `mean' or `median'.).
4. The ltered attitude history le created by att lter (required only if ((filemode = `modify'
and changeattitude = `yes') or filemode = `create') and attstyle = `expmedian'.).
5 Output Files
1. RGS sources set with a binary extension table named SRCLIST. The header has all the
keywords mandatory for PPS products, in particular
 RA PNT: The right ascension of the attitude in decimal degrees.
 DEC PNT: The declination of the attitude in decimal degrees.
 PA PNT: The position angle of the attitude in decimal degrees.
The SRCLIST table has the following keywords:
 PRIMESRC: The INDEX value (see column description below) of the prime source.
 E EXPRn: There are n ( 99) occurrences of this keyword, one for each EPIC source
list added to the RGS list. The numbers n are consecutive, starting at 1. The values
of these keywords are taken from the INSTRUME header keyword in the input EPIC
source list (that is, probably EPN, in most of the cases, which does not carry a lot of
practical meaning, in fact), although it used to be the exposure IDs of the respective
EPIC source les (in the old-style source lists).
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 8
 E CONTn: Similar to the E EXPRn keyword, but this records the value of the CONTENT
keyword in the EPIC le header.
 E mBNDn: Similar to the E EXPRn keyword, but this records the value of either ID BAND
(in the input RGS source le, when filemode=`modify') or bandids, which is used
to select the EPIC sources and to calculate the RATE value, transmitted into the
output RGS source list. Note that this used to be E BANDn(=2) before Ver.6.0. If
filemode=`modify' and if the input RGS source list has E BANDn keywords, then they
will be preserved in the output RGS source list (i.e., both E BANDn and E mBNDn key-
words may appear).
 E FILTn: Similar to the E EXPRn keyword, but this records the value of the FILTER
keyword in the EPIC le header.
The SRCLIST table has the following columns:
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 9
Column name: Data type: Description:
INDEX int16 Source index number. Each source has a unique
value, which rgssources never alters.
LABEL string Label for the source. These values are also unique to
each source. Only upper case is used. At present, la-
bel values can only be 20 characters or less in length.
Trailing spaces are not allowed.
RA real32 J2000 right ascension in decimal degrees.
DEC real32 J2000 declination in decimal degrees.
RATE real32 Counts per second.
DELTA DISP real32 O set on the sky, in the dispersion direction, of the
source with respect to the pointing direction. Given
in arcminutes.
DELTA XDSP real32 O set on the sky, in the cross-dispersion direction,
of the source with respect to the pointing direction.
Given in arcminutes.
FOV PHI real32 This and the next column give the polar coordinates
of DELTA DISP and FOV PHI. Units for both are dec-
imal degrees. FOV PHI is the angle of the source po-
sition from the -ve dispersion axis towards the +ve
cross-dispersion axis.
FOV R real32
CONFUSION real32 This is a measure of how confused the source is with
respect to the prime source. See subsection 5.2 for a
description of how it is calculated. It is a dimension-
less number.
PROCESS bool This column is used by rgsregions to ag those
sources for which spectrum extraction regions should
be calculated. This column is no longer set by
rgssources, though, so all values are written as
false in principle. An exception is the case of
filemode=`modify'; in that case the PROCESS col-
umn in the input RGS source list is in principle pre-
served. Another exception is the sources added by
the user (addusersource=true), where the value of
the command-line option process is written as it
is in principle. In any case, if filemode=`modify'
and changeattitude=true, all PROCESS values
are forcibly written as false regardless of the value
process or PROCESS in the input RGS source list.
BKG EXCLUDE bool This column is used by rgsregions to ag those
sources which should be excluded from the back-
ground spectrum extraction region. This column is
no longer set by rgssources, so all values are written
as false.
FIXED ON SKY bool This column ags those sources for which the po-
sitional information was derived from right ascen-
sion and declination. The only sources for which
FIXED ON SKY is false are the attitude source and any
user source supplied with userstyle=`wtatt'.
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 10
Column name: Data type: Description:
EPIC FILE int16 This gives the number of the E EXPRn, E CONTn,
E mBNDn (or E BANDn before Ver.6.0) and E FILTn
keywords appropriate to the source if it has been
derived from an EPIC source list. Eg, for
EPIC FILE=3, the details of the original list from
which this source came can be found from the key-
words E EXPR3, E CONT3, E mBND3 and E FILT3.
FLAG int32 If non-zero, something goes wrong in the source.
It is a binary (bit-type) form of representation
for each cause { see the following table for de-
tail (n.b., The representation of this FLAG col-
umn is entirely di erent from that in the input
EPIC source list). Note that some of the checks
may be bypassed if requested (by command-line pa-
rameters); for example if enablefilter=false and
flagepicsrcoutoffov=false, no check for OUTOF-
FOV is carried out.
The following is the description for the FLAG column:
Name Bit Description
OUTOFFOV 0 The source is out of eld of view.
CONFUSED 1 The source may be confused with other source(s).
BADBAND 1 2 The energy band used (hence RATE) may be wrong.
WIDESRC 3 The source is greater than 90 degrees away from the pointing.
Note that the RGS source list set is also used to store the spectrum extraction regions
created by rgsregions. These become invalidated if the attitude is altered; in this case
rgssources deletes them. See the algorithm (section 7) for details of the circumstances
under which this occurs.
The RGS source list table is required to have 1 source whose position is taken from the
observation proposal, and 1 source whose position is equal to the RGS attitude (stored in
the dataset header keywords RA PNT, DEC PNT and PA PNT). The LABEL values of these two
sources are PROPOSAL and ONAXIS respectively.
5.1 Uniqueness of LABEL and INDEX values.
These column values are maintained unique in order to provide the user with convenient ways to select
either the prime source or (via the selection expression parameters of rgsregions) a subset of sources
for which spectrum-extraction regions are desired. When a previously-made RGS source list is modi ed,
the task checks to make sure the labels and index values in this list are unique. (They are left so by any
previous invocation of rgssources, but values might be changed in the interim by use of the appropriate
ftool, for example.)
Further added sources from either a submitted EPIC list or the user are checked one by one against all
previous LABEL values in the list before themselves being added to it. An INDEX value equal to the next
highest unused value is given to each added source.
If a source is found to have the same LABEL value as an existing member of the source list, the action
taken by the task depends on the value of the parameter clobberonlabel. If clobberonlabel=no (the
default), the task fails with an error. Otherwise it discards the newer source, with a warning.
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 11
5.2 CONFUSION values.
It is intended to ag in the RGS pipeline sources which are confused with the prime source, so as to allow
the end user to assess whether these have a deleterious e ect on the spectra of the prime source. For this
purpose rgssources calculates, for each source, a value which is stored in a column called CONFUSION.
This value is calculated from the following formula:
C = I 1
prime
n
p 1 + p 2 I exp
h (j prime j + a) 2
2b 2
(j  prime j + c) 2
2d 2
io
:
Here C is the confusion value, I is the source brightness (ie value of the RATE column) and and  are
respectively the dispersion and cross-dispersion angles in arcseconds. The constants p 1 , p 2 , a, b, c and
d will eventually be stored in CCF MiscData, but at present are `hard-wired' into the task code, with
values as follows:
p 1 = 0:00653 cts=sec
p 2 = 1:01
a = 36:9 arcsec
b = 593:4 arcsec
c = 2:29 arcsec
d = 23:3 arcsec
6 Examples.
Before running rgssources you will need to set SAS CCF. SAS ODF may also be required (see below
for details).
There are essentially three reasons for invoking rgssources:
 To create a new source list (eg when invoked by either the Pipeline Control and Monitoring
System (PCMS) or by rgsproc).
 To update the format of a pre-sas-5.1 source list.
 To add further sources to an existing source list.
Examples of each are detailed below.
6.1 Pipeline useage.
rgssources is usually rst invoked within the PCMS or within rgsproc. In PCMS usage the command
should be
rgssources filemode=create instexpid=
srclist=rgssrclist.ds
attstyle=median medianset=
withepicset=yes epicset= doconfusion=yes
primestyle=auto flagepicsrcoutoffov=yes enablefilter=yes
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 12
enablefilter ensures that only epic sources within the RGA led of view are selected (sources out of
FOV are agged); primestyle=auto forces rgssources to choose a prime source in arguably the most
reasonable way (see section 3.5 for the outline of the criteria/algorithm or section 7 for the detailed
algorithm).
6.2 Attitude parameters.
6.3 Upgrading the format.
rgssources is now backward-compatible: it is able to add sources to source lists which were created in
the pre-sas-5.1 format. See section 3.7 for a detailed description of the process. The task attempts to
upgrade the format of these older les and in fact can be used to do this exclusively, without the necessity
to add to or otherwise modify the source list. To fully upgrade an older source list, rgssources needs
the following information:
 The instrument name.
 Information from the CCF.
 The exposure number.
 Information from the ODF.
The rst two items are mandatory; the second two optional. Details of this are as follows:
6.3.1 Instrument name.
If the le name is in either the PPS or the rgsproc formats, then rgssources is able to deduce the
instrument name from the le name. The PPS format is PooooooooooiiteeeSRCLI 0000.FIT; the rgsproc
format is rrrrooooooooooiiteee00 sources.ds. In these templates, rrrr is the rev number, oooooooooo is
the observation identi er, ii the instrument (either R1 or R2), eee the exposure number and t the exposure
type (either S or U)). However forcing rgssources to do this is not the preferred option, which is rather
to give the instrument name directly via the parameter instexpid.
6.3.2 CCF.
To access this, the user should set SAS CCF in the usual way.
6.3.3 Exposure number.
rgssources can also deduce the exposure number from the standard le name formats described above.
However this is not the preferred option, which is to give the exposure number directly via the parameter
instexpid. However, the information is optional. If the le name is not in a standard format, and the
exposure number is not otherwise known, its use can be turned o by setting writeexpkwds to `no' or
`false'. In this case the only e ect is that some exposure-speci c keywords are not written to the le
header. (Note that the exposure number is required if it is desired to recalculate the attitude.)
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 13
6.3.4 ODF.
To access this, the user should set SAS ODF to point to the ODF in question. However, the information
is optional. If the user does not have access to the ODF, it can be rendered unnecessary by setting
writeobskwds to `no' or `false'. In this case the only e ect is that some observation-speci c keywords
are not written to the le header. (Note that ODF access is required if it is desired to recalculate the
attitude.)
6.3.5 Example calls.
Full upgrades:
setenv SAS_CCF
setenv SAS_ODF
rgssources srclist=PooooooooooiiteeeSRCLI_0000.FIT
or
setenv SAS_CCF
setenv SAS_ODF
rgssources srclist=rrrrooooooooooiiteee00_sources.ds
or
setenv SAS_CCF
setenv SAS_ODF
rgssources srclist= instexpid=iiteee
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 14
Just format upgrade without exposure keywords:
setenv SAS_CCF
setenv SAS_ODF
rgssources srclist=PooooooooooiiteeeSRCLI_0000.FIT writeexpkwds=no
or
setenv SAS_CCF
setenv SAS_ODF
rgssources srclist=rrrrooooooooooiiteee00_sources.ds writeexpkwds=no
or
setenv SAS_CCF
setenv SAS_ODF
rgssources srclist= instexpid=iiteee
writeexpkwds=no
Just format upgrade with neither exposure nor observation keywords:
setenv SAS_CCF
rgssources srclist=PooooooooooiiteeeSRCLI_0000.FIT writeexpkwds=no
writeobskwds=no
or
setenv SAS_CCF
rgssources srclist=rrrrooooooooooiiteee00_sources.ds writeexpkwds=no
writeobskwds=no
or
setenv SAS_CCF
rgssources srclist= instexpid=iiteee
writeexpkwds=no writeobskwds=no
6.4 Adding further sources.
6.4.1 Simplest case.
After the initial source list has been made, the user will generally want to add some source positions of
his/her own. The simplest call to do this is:
xmmsas\_20070708\_1801-7.1.0

XMM-Newton Science Analysis System Page: 15
setenv SAS_CCF [if it hasn't already been done, of course.
From now on I'll assume that SAS_CCF has been set - it is always necessary.]
rgssources srclist= addusersource=yes
ra= dec=
Notes:
1. It is unnecessary to set the parameter filemode=modify since this is the default value.
2. It is unnecessary with this call to supply an attitude history le.
3. It is unnecessary with this call to set the environment variable SAS ODF.
4. If you addusersource but forget the ra and/or dec parameters, the task will issue a warning.
5. The pointing and prime source remain unchanged by default.
6. It is a good idea to specify a label as well for your source via the parameter label. Reason:
the default value is 'USER'. If you try to add another source using again the default label
value, the task will not allow this because LABEL values must be unique.
7. Parameter enablefilter if set will not at present prevent you adding an out-of-FOV source
to the source list; however it will enable the task to generate a warning after the fact, and
the out-of-FOV sources are agged as it is in the resultant source list.
6.4.2 Old-format source list.
The considerations of subsection 6.3 apply. Note however that rgssources does its best to upgrade the
format of any old les it encounters. It will incorporate the instrument, exposure etc into the le header
if you supply them just one time on the command line; you won't then need to do so for subsequently
added sources.
6.4.3 Elaborations.
If you know the position of your source with respect to the instrument pointing direction but not its ra
and dec, you may want to specify the position instead via the deltadisp and deltaxdsp parameters,
viz:
rgssources srclist=rgssrclist.ds addusersource=yes positionstyle=wrtatt
deltadisp=
deltaxdsp=
Both the delta* parameters have units of arcminutes. Such entries in the source list have their column
FIXED ON SKY values set false. This means that their values for RA and DEC may be altered by subsequent
invocations of rgssources, but columns DELTA DISP, DELTA XDSP, FOV PHI, and FOV R will never be
altered. The opposite holds for sources which have been entered with a de ned ra and dec; these have
FIXED ON SKY equal to true.
Note that you need to explicitly set the parameter positionstyle to `wrtatt' for this style of user-source
input - its default value is `radec'.
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 16
If you want to change the attitude you must explicitly set the parameter changeattitude. Just providing
values for att* parameters for example won't have any e ect. A change of attitude to a user-speci ed
value can be achieved by:
rgssources srclist=rgssrclist.ds changeattitude=yes attapos= angle of instrument pointing> attdec= attra=
Note that in this case the atthk le is not needed. Other ways to respecify the attitude might however
require it. In these cases the task will fail with an error if atthkset is not lled. Note also that a
recalculation of the attitude can only be done if the exposure number is known and if the user has access
to the ODF. The exposure number may not be present in the source list header if the source list originated
in an older format. In this case, if rgssources is not able to deduce the exposure number from the le
name (which has to be in either PPS or rgsproc standard format for this to be possible), then you must
supply this value to parameter instexpid, whether you have writeexpkwds set or not.
Be warned that changing the attitude will have two e ects: rstly all the DELTA DISP, DELTA XDSP,
FOV PHI, and FOV R values will be recalculated for those sources for which FIXED ON SKY is true, whereas
RA and DEC are recalculated for those for which FIXED ON SKY is false; secondly, the region extensions
created by rgsregions (if any) are falsi ed and are therefore deleted.
Changing the prime source is similar, you need to set the parameter changeprime. To add a user source
and reset the prime source to this source, you should do something like
rgssources srclist=rgssrclist.ds addusersource=yes changeprime=yes
userasprime=yes (followed by position and optionally the label of the
user source as described above)
Having to set both changeprime and userasprime is a bit irritating and we hope to amend the logic of the
task in a future version so that this is no longer necessary. changeprime itself is necessary to prevent the
task reverting to a prime source value de ned by the default values for the tree of prime source selection
parameters. Future modi cations to the parameter interface may allow the task to detect whether a
parameter has appeared on the command line or not and much of these extra parameters will vanish.
Note that after changing the prime source, the section of the proc/pipeline from rgsangles onwards
should be re-run. This is because the prime source is used to calculate attitude-drift corrections to the
rgs events.
7 Algorithm
read parameters;
################# start format upgrade section.
if (filemode eq 'modify') {
# convert old-style source list if necessary:
if (! instrument_supplied) {
if (hasAttribute(set, 'INSTRUME')) {
instrument = stringAttribute(oldListSet, 'INSTRUME');
} else {
xmmsas\_20070708\_1801-7.1.0

XMM-Newton Science Analysis System Page: 17
# attempt to get it from file name:
if (! instrument_in_filename) {call error;}
}
}
call CAL_setState(instrument=instrumentId);
rename table to 'SRCLIST';
get attitude from *_REF keywords;
write_generic_keywords;
if (writeobskwds) {write_observation_keywords;}
if (writeexpkwds) {
if (! exposure_supplied) {
if (hasAttribute(set, 'EXP_ID')) {
exposure = stringAttribute(oldListSet, 'EXP_ID');
} else {
# attempt to get it from file name:
if (! exposure_in_filename) {call error;}
}
}
}
# Convert columns:
n_offaxis_sources = 0;
foreach (source) {
fixed_on_sky = true; # default
process = false; # default
bkg_exclude = false; # default
if (old_label eq 'proposal') {
new_label = 'PROPOSAL';
new_ra = old_ra;
new_dec = old_dec;
} elsif (label eq 'onaxis') {
new_label = 'ON_AXIS';
new_ra = attitude_ra;
new_dec = attitude_dec;
delta_disp = 0;
delta_xdsp = 0;
new_fov_phi = 0;
new_fov_r = 0;
fixed_on_sky = false;
} elsif (label eq 'epic') {
new_label = 'OLDEPIC'.id_band.ml_id_src;
new_ra = old_ra;
new_dec = old_dec;
epic_file = number of bands found;
} elsif (label eq 'offaxis') {
n_offaxis_sources = n_offaxis_sources + 1;
new_label = 'OFFAXIS'.n_offaxis_sources;
delta_disp = rgs_disp;
delta_xdsp = rgs_xdsp;
xmmsas\_20070708\_1801-7.1.0

XMM-Newton Science Analysis System Page: 18
calculate new_fov_phi, new_fov_r;
fixed_on_sky = false;
} else { # assume is user-added source.
new_label = upper_case(old_label);
new_ra = old_ra;
new_dec = old_dec;
}
new_rate = old_rate;
if (src_select > 0) {process = true;}
if (back_select > 0) {bkg_exclude = true;}
if (fixed_on_sky) {
calculate delta_disp;
calculate delta_xdsp;
calculate new_fov_phi;
calculate new_fov_r;
} else {
calculate new_ra;
calculate new_dec;
}
}
calculate_confusion(src_data, prime_index);
delete old columns;
write column data to new columns;
write epic keywords;
}
################# end format upgrade section.
# get the instrument:
if (filemode eq 'modify') {
instrument = stringAttribute(oldListSet, 'INSTRUME');
} else {
# get instrument from parameter;
if (instrument parameter at default value) {call error;}
}
# get the exposure number:
expid_is_valid = true;
if (filemode eq 'modify') {
exposure = int32Attribute(oldListSet, 'EXP_ID');
} else {
# get exposure from parameter;
if (exposure parameter at default value) {
expid_is_valid = false;
}
}
call CAL_setState(instrument=instrumentId);
# get the pointing:
if (filemode .eq. 'modify' && ! changeAttitude) {
# read attitude from old source list;
} elsif (attitudeStyle .eq. 'user') {
xmmsas\_20070708\_1801-7.1.0

XMM-Newton Science Analysis System Page: 19
# read attitude from attra, attdec and attapos parameters;
} else {
if (!expid_is_valid) {call error;}
call OAL_setState(instrument=instrument, exposureNr=exposure);
if (attitudeStyle .eq. 'start') {
# get attitude from attitude at start of observation;
} elsif (attitudeStyle .eq. 'mean') {
# get attitude from mean of attitude history file values;
} elsif (attitudeStyle .eq. 'median') {
# get attitude from median of attitude history file values;
}
}
allocate(src_data(max_number_sources));
if (filemode eq 'create') {
proposal position -> src_data(1);
attitude position -> src_data(2);
} else { # filemode eq 'modify'
open(old rgs set, 'READ');
call check(old rgs list); # This checks that all label names are unique,
# and that there is a proposal and attitude source.
old rgs sources -> src_data;
release(old rgs set);
if (changeattitude) {attitude position -> src_data(index of onaxis src);}
}
if (withepicset) {
clone(old epic set);
if (enablefilter) {spatial filtering of cloned epic set;}
foreach(epic source) {
label = 'epiclabelprefix'.column('*_ID_SRC');
foreach(source already in src_data) {
if (label eq src_data(LABEL)) {
no_label_clash = F;
if (clobberonlabel) {
last;
} else {
call error;
}
}
}
if (no_label_clash) {
epic source -> src_data;
}
}
release(old epic set);
}
if (addusersource) {
foreach(source already in src_data) {
if (label eq src_data(LABEL)) {
xmmsas\_20070708\_1801-7.1.0

XMM-Newton Science Analysis System Page: 20
no_label_clash = F;
if (clobberonlabel) {
last;
} else {
call error;
}
}
}
if (no_label_clash) {
user source -> src_data;
}
}
# Possible routine in this place that filters out (or at least identifies)
# all pairs of too-close sources.
if (changeattitude or null in column) {
foreach(source in src_data) {
# Calculate ra/dec or delta_disp/delta_xdsp/fov_phi/fov_r, as appropriate;
}
}
# Write the data to file:
if (filemode eq 'create') {
open(new rgs set, 'CREATE');
# write keywords to header:
write_generic_keywords;
if (writeobskwds) {write_observation_keywords;}
if (writeexpkwds && expid_is_valid) {write_exposure_keywords;}
} else { # filemode eq 'modify'
open(old rgs set, 'MODIFY');
if (changeattitude) {
rewrite attitude attributes (#RA_PNT etc);
delete all region extensions;
set PROCESS and BKG_EXCLUDE to false;
}
delete all table entries;
}
src_data -> new rgs set;
if (withepicset) {
write_epic_specific_keywords;
}
if (enablefilter) {check that all members of the src list are within the
fov, flag them and warn if not;}
# Estimate groups of confused sources:
if (withepicset && doEpicConfusion) {
mark_groups_of_confused_sources
foreach (confused_group) {
if (a confused group includes the proposed source) {
if (proposed source is confused with only one EPIC source) {
flag_the_proposed_and_leave_the_EPIC_one;
xmmsas\_20070708\_1801-7.1.0

XMM-Newton Science Analysis System Page: 21
} else { # proposed source is confused with more than one EPIC source
flag_all_but_the_proposed;
}
} else {
flag_all_but_the_brightest;
}
}
}
# Now calculate prime source index value:
if (filemode eq 'modify' && !changeprime) {
prime_index = prime_index in old file;
} else {
if (addusersource && userasprime) {
prime_index = index of (last) user-added source;
} else {
if (primestyle eq 'label') {
prime_index = index of source with label=primesourcelabel;
} elsif(primestyle eq 'index') {
prime_index = primesourceindex;
} elsif(primestyle eq 'brightest') {
prime_index = index of brightest source;
} elsif(primestyle eq 'auto') {
if (proposal source is within FOV and is not flagged as confused) {
prime_index = index of proposal source;
} elsif (there are some epic sources within FOV) {
prime_index = index of brightest within-FOV epic source;
} else {
prime_index = index of pointing (ONAXIS) source;
}
}
}
}
if (filemode eq 'create' || changeprime) {
prime_index -> #PRIMESRC;
}
call calculate_confusion(src_data, prime_index);
# Write the confusion data to file:
# release the data set.
8 Parameters
This section documents the parameters recognized by this task (if any).
Parameter Mand Type Default Constraints
lemode no string modify modify|create
Controls whether the task opens a previous source list for editing or creates a new one.
changeprime no boolean no yes|no
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 22
Only active in filemode=`modify'. Unless this parameter is set, the previous prime source index number
is retained.
changeattitude no boolean no yes|no
Only active in filemode=`modify'. Unless this parameter is set, the previous attitude (stored in the
header) is retained.
srclist yes dataset rgsset.ds
The name of the rgs source list. If filemode=`create', the output is written to this le. If there is an
existing le of this name, it will be overwritten unless SAS CLOBBER is unset. If filemode=`modify',
the task looks for an existing source list of this name and modi es it.
instexpid no string
This parameter contains information about both the instrument (that is, RGS1 or 2) and the exposure
identi er (a letter S or U, indicating scheduled or unscheduled, followed by a three-digit numeric identi-
er. The instexpid string can be supplied in a number of di erent forms, but the two most useful are
(i) as a six-character string comprising either R1 or R2 followed by the exposure identi er (an example:
`R2S003'); (ii) the name of any of RGS-speci c les in the ODF can also be used. This parameter is
mandatory if filemode=`create', or in cases where the instrument and/or exposure can neither be read
from the le header or deduced from its name.
writeobskwds no boolean yes yes|no
If this is set, the task attempts to write observation-speci c keywords to the le header. The user must
point the environment variable SAS ODF to the ODF directory for this to succeed.
writeexpkwds no boolean yes yes|no
If this is set, the task attempts to write exposure-speci c keywords to the le header. For this to succeed,
the user must point the environment variable SAS ODF to the ODF directory, and the task must also
be able to determine the exposure number, either via the instexpid parameter, or from the EXPIDSTR
keyword in the le header, or (if neither are present) from the le name.
clobberonlabel no boolean no yes|no
Labels in RGS source lists are required to be unique. Where a clash is detected between a source already
in the list and a new candidate source, the task takes one of two actions, depending on the value of this
parameter: if `yes', the candidate is discarded; if `no', the task halts with an error.
primestyle no string label label|index|expr|brightest|auto
Only active if changeprime=yes and either addusersource or userasprime=no. It controls the way in
which the prime source is speci ed. See the parameters primelabel and primeindex. (An additional
possible value of `expression' is planned.)
primelabel no string PROPOSAL
If primestyle is active and set to `label', this parameter gives the value of the LABEL column of the
source that it is desired the PRIMESRC keyword should point to.
primeindex no integer 1 0 If primestyle is active and set to `index', the PRIMESRC keyword is set to this value.
primeexpression no string
This mode is not yet supported.
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 23
attstyle no string expmedian mean|median|start|user|expmedian
Controls the way the attitude is calculated. If `mean', the attitude is calculated from the mean of the
values in the attitude history le. If `median', the median of these values is used. If the value is `start',
the task uses the attitude at the start of the exposure as the reference attitude. A value of `expmedian'
tells the task to use the median of the attitude during the exposure only, as calculated by att lter. The
nal value, `user', allows the user to input the numbers him/herself via the next three parameters.
meanset no dataset atthk.dat
The name of the attitude history le. This le is a necessary input in the case that attstyle is `mean'.
medianset no dataset atthk.dat
The name of the attitude history le. This le is a necessary input in the case that attstyle is `median'.
attra yes angle 0 0 attra 360
Only active if attstyle=`user'. The right ascension of the attitude, in decimal degrees.
attdec yes angle 0 90 attdec 90
Only active if attstyle=`user'. The declination of the attitude, in decimal degrees.
attapos yes angle 0 0 attapos 360
Only active if attstyle=`user'. The position angle of the attitude, in decimal degrees.
expmediantable no table attgti.ds:STDGTI
The name of the table in the ltered attitude history le in which the exposure-median keywords can be
found. This le is a necessary input in the case that attstyle is `expmedian'.
addusersource no boolean no yes|no
This should be set if the user wishes to add a source to the list with a position speci ed on the command
line.
label no string USER
Only active if addusersource=yes. This is written directly to the LABEL column of the output source
list. The empty string is not permitted.
rate no real 0.0 0:0 Only active if addusersource=yes. The brightness of the source in counts per second. It is anticipated
that this parameter won't be used much, since this is not a quantity that is likely to be known in most
circumstances. The default value of 0.0 is harmless.
userasprime no boolean no yes|no
Only active if addusersource=yes. If changeprime=yes and userasprime=yes, then the attribute
PRIMESRC is set to the index number of the user source.
process no boolean no yes|no
Only active if addusersource=yes. This causes the value in the PROCESS column to be set to true for
the user-added source.
bkgexclude no boolean yes yes|no
Only active if addusersource=yes. This causes the value in the BKG EXCLUDE column to be set to true
for the user-added source.
positionstyle no string radec radec|wrtatt
Only active if addusersource=yes. If positionstyle=`radec', then the position of the user-added source
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 24
is expected via the parameters ra and dec. If on the other hand positionstyle=`wrtatt' (With Respect
To ATTitude), then the position of the user-added source is expected via the parameters deltadisp and
deltaxdsp.
ra yes angle 0 0 ra 360
Only active if addusersource=yes and positionstyle=`radec'. The right ascension of the user-added
source, in decimal degrees.
dec yes angle 0 90 dec 90
Only active if addusersource=yes and positionstyle=`radec'. The declination of the user-added
source, in decimal degrees.
deltaxdsp yes real 0.0
Only active if addusersource=yes and positionstyle=`wrtatt'. The displacement in arcminutes of the
user-added source from the pointing direction, in the dispersion direction.
deltadisp yes real 0.0
Only active if addusersource=yes and positionstyle=`wrtatt'. The displacement in arcminutes of the
user-added source from the pointing direction, in the cross-dispersion direction.
withepicset no boolean no yes|no
If this is set, the task looks for the parameter epicset, giving the name of an EPIC source list.
epicset no dataset
The name of a set containing a list of sources. Formats output by the tasks emldetect and eboxdetect
are accepted.
epiclabelpre x no string EPIC
This parameter gives the string which is used by the task as a pre x when constructing LABEL values for
EPIC-derived sources. The other part of the LABEL is the number ML ID SRC or BOX ID SRC. The main
purpose of this parameter is to allow several EPIC-derived source lists to be included in the one RGS list
if desired, while retaining unique labels.
doconfusion no boolean no yes|no
Active only if withepicset=true. This parameter causes the task to check the epic sources + proposal
position for confusion in the EPIC eld of view. It is mainly designed for use in the PCMS, to prevent
automatic extraction of too many spectra for what is essentially the same object. The degree of confusion
depends on the size of the PSF, which is a function of energy. Therefore, strictly speaking, it depends
on the selection of the energy band of interest (bandids). At the moment, however, the a-priori energy
of (0:5 + 2)=2 = 1:25 keV is unconditionally used for it, whatever bandids is.
instweights no real list 3.5,1.0,1.0
Active only if withepicset=true. This parameter gives the list of weighting factors for EPIC instruments
for the use of calculation of RATE, where the order is the normal ID INST number (i.e., pn, MOS1 and
2). The resultant RATE in the output RGS source list is normalised to 1.0 in the list, namely in default,
it is normalised to the RATE of MOS1 (or 2).
agepicsrcouto ov no boolean no yes|no
Active only if withepicset. If this is set, the input EPIC sources falling outside the FOV (see the
description of enablefilter for de nition) are agged and are not dropped from the output source list
due to that reason. If not (default), either they are dropped from the source list (if enablefilter=true)
or nothing is done. See the description of enablefilter for the summary of the behaviour.
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 25
enable lter no boolean no yes|no
If this is set, the task carries out ltering, where only those sources, the position of which corresponds
to cross-dispersion angles on the RGS camera between 2.9 and +2.9 arcminutes from camera centre,
are regarded as a good source. If withepicset=true, the ltering is made also for the input EPIC
sources, and the those EPIC sources regarded as no-good are either dropped out of the output list
(flagepicsrcoutoffov=false) or just agged as OUTOFFOV (if flagepicsrcoutoffov=false) (see sec-
tion 5 for the OUTOFFOV ag). Regardless of whether epic sources are added or not (withepicset),
the task checks the positions of all sources if enablefilter is set and ags them as it is and warns about
any that fall outside the FOV.
When enablefilter=true
EPIC sources Anything else
flagepicsrcoutoffov = true Flagged Flagged
flagepicsrcoutoffov = false Dropped Flagged
bandids no integer
list
2,3
This parameter gives the list of energy bands accepted for the input EPIC source list. The RATE value
of each source in the output RGS source list is the sum of the RATEs of the corresponding source for the
energy bands speci ed with this parameter. For 1XMM-source-catalogue type ones, this list should be 2,
whereas for 2XMM-source-catalogue type ones, this list should be 2, 3 (default). Although an arbitrary
number of elements in the list is allowed, if it is more than 9, only the rst 9 energy bands are stated in
the E mBNDnn header keyword and the rest is unstated (see section 5) in the output list.
withboresightfudge no boolean yes yes|no
Flip the sign of the boresight euler%psi. This parameter will be removed after the boresight is xed.
9 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.
noAttitude (error)
No attitude information is available from the oal for the start time of the exposure.
badAttitudeStyle (error)
The value of attstyle was not recognized.
badFileMode (error)
The value of filemode was not recognized.
nonUniqueEpicId (error)
There is more than one source in the EPIC source list with a given ML ID SRC or BOX ID SRC
number.
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 26
tooManyProposals (error)
The RGS source list to be modi ed has more than one source with the label `PROPOSAL'.
noProposal (error)
The RGS source list to be modi ed has no source with the label `PROPOSAL'.
tooManyAttSrc (error)
The RGS source list to be modi ed has more than one source with the label `ONAXIS'.
noAttSrc (error)
The RGS source list to be modi ed has no source with the label `ONAXIS'.
badEpicIdColumn (error)
The supposed EPIC source list has neither a ML ID SRC or BOX ID SRC column.
emptyUserLabel (error)
The label parameter, which is the desired label of the user-added source, is the empty
string.
duplicateLabel (error)
A candidate additional source has been found to have the same label as one of the existing
sources. This error can only occur if the parameter clobberonlabel=no.
notSupported (error)
A mode has been requested that is not yet implemented.
badPrimeStyle (error)
The value of primestyle was not recognized.
unableToSetNull (error)
For some reason it wasn't possible to set an integer 32 null value for the column EPIC FILE.
badSrcFileType (error)
The source list supplied to parameter srclist is not in a recognised format.
unknownInstrument (error)
No valid value was provided for the instexpid parameter, and rgssources was unable to
deduce the instrument from the old-format le header or name.
notStandardFileName (error)
The task has attempted to deduce either the instrument or the exposure number from the
le name, but the name was not found to adhere to either the PPS or rgsproc formats.
instIdClash (warning)
The instrument recorded in the source list header keyword INSTRUME is not the same as
that derived from the value of the instexpid parameter.
corrective action: The task uses the value from the source list header.
expIdStrClash (warning)
The 4-character exposure identi er recorded in the source list header keyword EXPIDSTR
is not the same as that derived from the value of the instexpid parameter.
corrective action: The task uses the value from the source list header.
mangledIdInstColumn (warning)
In the input EPIC source list, a row that should contain a required instrument-ID is missing.
corrective action: No action.
mangledIdInstBandColumn (warning)
The same as above, but in this case it also includes the case for the energy-band ID.
corrective action: No action.
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 27
noValidEpicSources (warning)
None of the epic sources have met all the conditions for inclusion.
corrective action: No epic sources are added to the le.
noEpicSourcesInFov (warning)
None of the epic sources were found to lie within the eld of view of the RGS camera.
corrective action: No epic sources are added to the le.
noEpicSources (warning)
There are no epic sources in the correct energy band.
corrective action: No epic sources are added to the le.
duplicateLabel (warning)
A candidate additional source has been found to have the same label as one of the existing
sources. If clobberonlabel=no, this condition causes the task to fail with an error.
corrective action: New source is not appended to the source list.
outsideFOV (warning)
A source has been found to lie outside the eld of view of the RGS camera.
corrective action: No action.
confSetAllZeroRate (warning)
A set of confused sources has none with a positive value of RATE.
corrective action: All sources agged as confused.
primeLabelNotFound (warning)
The user has set changeprime=yes and primestyle=`label', but no source with a label
equal to primelabel has been found in the le.
corrective action: The prime source is set to point to the proposal source.
primeIndexNotFound (warning)
The user has requested that the prime source be set to a source of a particular index value,
but no source in the list has this index value.
corrective action: The prime source is set to point to the proposal source.
noBrightPrime (warning)
The user has requested that the prime source be set to the index of the brightest source,
but brightest source has a rate less than or equal to zero.
corrective action: The prime source is set to point to the proposal source.
noChangePrime (warning)
The user has set userasprime, but not changeprime.
corrective action: Prime source is not changed.
primeAtLabelDefault (warning)
The user has set changeprime=yes and primestyle=`label', but primelabel still has its
default value. This may indicate that the user forgot to set it.
corrective action: No action.
primeAtIndexDefault (warning)
The user has set changeprime=yes and primestyle=`index', but primeindex still has its
default value. This may indicate that the user forgot to set it.
corrective action: No action.
primeAtDefault (warning)
A new RGS source list is being created, but primeindex still has its default value. This
may indicate that the user forgot to set it.
corrective action: No action.
xmmsas 20070708 1801-7.1.0

XMM-Newton Science Analysis System Page: 28
primeOutsideFOV (warning)
The designated prime source is outside the eld of view of the RGS camera.
corrective action: No action.
tooBigEPICAttrNum (warning)
Too many (over 99) EPIC source lists are read. As a result the sequence number for it in
the header keyword is truncated to 2 digits, which may cause overwriting the pre-existing
keywords.
corrective action: The last 2-digit in sequence-ID for EPIC source list is assigned.
tooManyEpicBandIds (warning)
Number of `bandids' speci ed is more than 9, which will lead to missing information of some
band-IDs in the header in the output RGS source list.
corrective action: No action.
instrumentClash (warning)
The instrument deduced from the le name does not agree with that deduced from the le
header.
corrective action: Header instrument will be used.
uncertainInstrument (warning)
The instrument has been deduced from the le name.
corrective action: Continues.
uncertainExposure (warning)
No instexpid value was supplied, and there is no EXPIDSTR keyword in the le.
corrective action: Task attempts to deduce exposure number from the le name.
badPrimeRate (warning)
The RATE value of the designated prime source has been found to be less than or equal to
zero. Confusion values can therefore not be calculated.
corrective action: Confusion values are set to zero.
References
xmmsas 20070708 1801-7.1.0