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


eimsim (eimsim-2.4.2) [xmmsas_20211130_0941-20.0.0]


Perform source detection

This function may be performed alone by calling the script with entrystage and finalstage=`detect'.

This is the core of the simulation process: the detection of `sources' in the simulated images. Exactly how this is performed is up to the user - ie the user can write their own detection script, and arrange very easily for this to be called by eimsim. In this way, several different schemes can be compared. At present, the eimsim package contains two example detection scripts: eimsimdetect1xmm and eimsimdetect2xmm, corresponding to the respective `prep' scripts and template sets. The name of the detection script can be supplied to parameter dettask of eimsim, although a more robust way is available, as described in section 4.2.5 of the package documentation.

A user-written detection script must supply the detected sources in a FITS binary table called SRCLIST. There must be no more than 1 row per source. The table must contain columns as follows:

Name
Data type Units
SRC_NUM 4-byte int  
FLUX 4-byte real erg cm$^{-2}$ s$^{-1}$
FLUX_ERR 4-byte real erg cm$^{-2}$ s$^{-1}$
RA 8-byte real decimal deg
DEC 8-byte real decimal deg
RADEC_ERR 4-byte real arcseconds
DETEC_PNULL 4-byte real  

Column SRC_NUM is an positive-valued integer which is unique to the source. Note that, for 1xmm and 2xmm detection schemes, the name of the output source ID column is hard-wired into emldetect or srcmatch, whichever is relevant; SRC_NUM contains these identical values; the column is just given a new, common name for convenience. The `original' column name is written to the keyword ID_COL.

Note that the FLUX and FLUX_ERR values should be valid for the same energy band as the simulated sources. This band is defined by the E_MIN and E_MAX keywords of the FLUX_SCALES table in the source template file.

Column DETEC_PNULL records the probability $P_\mathrm{null}$ that the source is detected by chance. At present, both eimsimdetect1xmm and eimsimdetect2xmm take, for each source, the value of DET_ML from the row with ID_INST==0 and ID_BAND==0, and process it as follows to get DETEC_PNULL:

  DETEC_PNULL = exp(-DET_ML).

Task eimsim calls the supplied detection script using the same command-line format as for sas tasks, viz:

  <detection task> obsidroots='<list>' refband=2 <etc>
The full list of parameters supplied to this command line is as follows:

Parameter
Passed in from eimsim Comment
obsidroots yes  
refband yes  
prdssubdir yes  
simopsubdir yes  
simgensubdir yes  
astest yes  
srcspecset yes  
srclistset no Name of the output source list
streamnumber yes  
idnumber yes  
entrystage no passed in from eimsim parameter –detentrystage
finalstage no passed in from eimsim parameter –detfinalstage

In order to avoid cross-talk when running several simulations in parallel, any intermediate files written by the detection script should have names which contain both the stream and id numbers. In addition, it is helpful to construct the detection script so that it has an optional entry point named `cleanup'. The function of this portion of the detection script should be just to delete all intermediate files. In other words, the detection script should be so designed, that it deletes all its intermediate files if invoked as follows:

  <detection task> entrystage=cleanup

If you opt to use one of the supplied detection scripts instead of writing your own, PLEASE NOTE that the 1xmm and 2xmm detection schemes employed different energy band definitions and different versions of non-eimsim sas tasks. You can obtain the correct band scheme by making use of the relevant template file in $SAS_DIR/lib/data/eimsimdata/. The filenames have 1xmm or 2xmm in them so it is not hard to tell which to use. The non-eimsim sas task versions are as follows:

Task
1XMM version 2XMM version
emask 2.7 2.9
eboxdetect 4.13.1 4.15.2
emldetect 4.32.1 4.44.25
esplinemap 4.0.3 4.4
srcmatch 3.15.1 not used

The matching det prep tasks will check these versions and issue a warning if the incorrect ones are found.

XMM-Newton SOC -- 2021-11-30