XMM-Newton Science Analysis System


rgssources (rgssources-6.3.3) [xmmsas_20230412_1735-21.0.0]

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 files 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

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 keywords.
• (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 fixed with respect to the celestial sphere and those which are fixed with respect to the reference attitude. (Since the latter may take on slightly different values, depending on how it is calculated, the two are not quite the same thing.) In older-format files, the proposal and all epic and user sources fell into the former category and the onaxis and offaxis 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 values, 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 different ID_BAND numbers encountered and these are used to assign values to the EPIC_FILE column of these sources.
• Offaxis sources are given LABEL values of `OFFAXISnnnnn' where nnnnn is the number of offaxis sources so far detected in the file.
• Sources which have old LABEL values which are neither `proposal', `onaxis', `epic' or `offaxis' 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.
• 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 file). No other extensions of the source list file are altered or deleted during this upgrade process.