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

rgssources (rgssources-6.3.3) [xmmsas_20230412_1735-21.0.0]


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=<displacement of user src in dispersion direction from attitude>
deltaxdsp=<ditto cross-dispersion direction>

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 defined 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'.

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 effect. A change of attitude to a user-specified value can be achieved by:

  rgssources srclist=rgssrclist.ds changeattitude=yes attapos=<position
angle of instrument pointing> attdec=<etc> attra=<etc>

Note that in this case the atthkfile 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 filled. 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 file 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 effects: firstly 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 falsified 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 defined by the default values for the tree of prime source selection parameters. Future modifications 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.

XMM-Newton SOC -- 2023-04-16