XMM-Newton Science Analysis System


epicbscalgen (ccftools-1.36) [xmmsas_20230412_1735-21.0.0]

Practical examples and hints

The usage of the task is very straightforward and the possibilities of making mistakes are small. The following points should be noted however:

• epicbscalgen is a meta-task that makes use of a couple of other SAS tasks, viz.:
  • evselect
  • attcalc
  • eboxdetect
  • srcdisplay
  • imgdisplay

  A basic familiarity with the functionality provided by these tasks is recommended. This is not a pre-requisite of making use of epicbscalgen though.

• It is recommended to run the task on a verbosity level 5 for getting a feeling for the operations carried out in each iteration.
• For controlling the convergence process it is usually advantageous to re-direct the standard output and error stream into a file and monitor its contents. This can be done with

  unix> epicbscalgen -V 5 eventtable=ev.ds 2>&1 | tee log
  

  (sh syntax) which duplicates the standard error and output stream and logs all output in the file log. While the task is running the convergence process can then be monitored by periodically checking the content of log for the actual values of $\epsilon$ and the angles $(\phi, \theta, \psi)$:

  unix> fgrep 'Iteration' log
  unix> fgrep 'New set of Euler angles' log
  

  With each iteration, $\epsilon$ should get smaller and the Euler angle tuple should approach the sought solution.
• In the very first iteration, the user is required to input the true coordinates of at least two sources interactively. For this Ds9 is launched showing an image that has been accumulated from the input event list with all found sources marked through excluded circles. For each source that is to be used as a reference source the user needs to:
  1. Double click with the left mouse button on the respective circle marker.
  2. In the dialog box that will pop up:
     1. Select the menu item “Properties” $\longrightarrow$ “Include/Exclude”. After that the circle marker will be redrawn with a solid line which marks the source as a reference source.
     2. In the field “Text”, input the celestial J2000 coordinates (right ascension/declination) of the source in the form

              23h59m48.12s / 45o38'14.55"
        

        or

              123.23445 / 45.238474
        

  3. Click on “Apply” and “Close”

  If done, hit the Enter key in the terminal window from which the task was started. If all input is ok, execution shall proceed normally, otherwise an error message should be produced.

  There is an alternative reference source input method available that is activated with the withrefsrclist parameter. Here an eboxdetect-compliant source list data set is required from which the true celestial coordinates will be obtained. As in the scheme described above in a first iteration a source detection will be performed on the image from the given event list and the result displayed using Ds9. Then, the given reference source list is read and likewise displayed on the image however with a different color and the markers labeled with the respective source indices. The user is now requested to perform the cross-correlation between the two source marker sets by activating, i.e. including, the corresponding markers from the source detection run and labeling them with the right indices. Detailed on-screen instructions on this are given when this input scheme is selected.

• Convergence to the minimum can be slow - in this regard it is worth noticing that the Nelder-Mead-Simplex method is not optimized for minimum number of function evaluations. Please monitor the convergence process in the above described manner. As long as $\epsilon$ is steadily decreasing there is no need for any intervention.

• If two or more of the selected reference sources do not differ in flux by more than 5% it is conceivable that possible source-confusion problems are reported. This is not a real problem as long as the affected sources are sufficiently spatially separated from each other such that the scheme can uniquely identify them in each iteration. A failure to do so would typically lead to an oscillating $\epsilon$. In this case, please stop the task and re-start with different reference sources. Choosing a different source radius (see parameter sourceradius) may also help to resolve the problem.
• The above described scheme is rather CPU intensive because it involves the execution of several non-trivial tasks. The main performance driver is clearly the size of the initial event list which should be kept as small as possible.