XMM-Newton Data Center at MPE - Calibrated EPIC MOS Event List

This description was developped for SAS version 5.3
input files: ODF files form orbit 0070_ (see bolow)
output files:
   P0123700101M1S001FL_GTI0000.FIT  P0123700101M1U002MIEVLI0000.FIT
   P0123700101M1S001FL_TSR0000.FIT  P0123700101M2S002FL_GTI0000.FIT
   P0123700101M1S001MIEVLI0000.FIT  P0123700101M2S002FL_TSR0000.FIT
   P0123700101M1U002FL_GTI0000.FIT  P0123700101M2S002MIEVLI0000.FIT
   P0123700101M1U002FL_TSR0000.FIT  
instrument: EPIC MOS, IMAGING mode
test data directory: /xmm_archive/orbitData/0070/

For most purposes the standard event file provided to the user is good enough to perform most analysis tasks. However, in some cases it can be necessary that the user creates his/her own event file, e.g. you want information that is in the Observational Data Files (ODFs) but not in the standard event file. In this example we will show how to create an event file with some additional columns.
An ODF contains many files of the form... (see http://xmm.vilspa.esa.es/tech/socdoc_top.html):
   
   RRRR_PPPPPPOOLL_IIUEEECCMMF.ZZZ
where:
   
   - RRRR is the revolution number
   - PPPPPPOOLL is the observation identifier
   - II is the instrument identifier, e.g. M1, M2 for the EPIC MOS 1 
     and 2 camera
   - U indicates whether the observation was Scheduled or Unscheduled
   - EEE in the exposure number within the total observation
   - CC is the CCD identifier (1-7  for EPIC MOS)
   - MM is the observing mode identifier, e.g. IM imaging, TI timing 
   - F is the file type, e.g. E = event list file
   - ZZZ is the file format, e.g. FIT for fits file
For our example: 0070_0123700101_M1S00160IME.FIT
    ==>  revolution number 70
         observation ident: 0123700101
	 instrument ident:  M1 = EPIC MOS Camera 1
	 scheduling:        S = scheduled (U=unscheduled)
 	 exposure number:   001 = 1. observation
	 CCD number:        60 = CCD 6
	 observing mode:    IM = imaging mode
	 file type:         E = event list
	 format type:       FIT = FITS format
For each `exposure', for one EPIC MOS camera observation, one should have (for the different modes) the following number of files.
			IMAGING		TIMING 	

AUXiliary file		   1		  1	
CCD files 		   7(IME)	  1+6(TIE)
A number of housekeeping data files have now to be placed with these files to create the full ODF directory. These are created/formed by the SAS task `odffix'. Please make sure that you have complete ODF. Check, if you have a Periodic House keeping file ...PEH.... If this is not the case, you have to use the XMMSAS task odffix. Please follow the description given on ODF fix page how to create a fixed ODF with dummy housekeeping files. These are the time correlation file (TCS), the attitude history file (ATS), the periodic housekeeping files (PHM), the reconstructed orbit file (ROS) and the ODF summary file (SUM).

We use the following ODFs from the test data directory listed above:
0070_0123700101_M1S00100AUX.FIT   0070_0123700101_M2S00200AUX.FIT
0070_0123700101_M1S00100CCX.FIT   0070_0123700101_M2S00210IME.FIT
0070_0123700101_M1S00110IME.FIT   0070_0123700101_M2S00220IME.FIT
0070_0123700101_M1S00120IME.FIT   0070_0123700101_M2S00230IME.FIT
0070_0123700101_M1S00130IME.FIT   0070_0123700101_M2S00240IME.FIT
0070_0123700101_M1S00140IME.FIT   0070_0123700101_M2S00250IME.FIT
0070_0123700101_M1S00150IME.FIT   0070_0123700101_M2S00260IME.FIT
0070_0123700101_M1S00160IME.FIT   0070_0123700101_M2S00270IME.FIT
0070_0123700101_M1S00170IME.FIT   0070_0123700101_M2S40810OVE.FIT
0070_0123700101_M1S40110OVE.FIT   0070_0123700101_M2S40920OVE.FIT
0070_0123700101_M1S40220OVE.FIT   0070_0123700101_M2S41030OVE.FIT
0070_0123700101_M1S40330OVE.FIT   0070_0123700101_M2S41140OVE.FIT
0070_0123700101_M1S40440OVE.FIT   0070_0123700101_M2S41250OVE.FIT
0070_0123700101_M1S40550OVE.FIT   0070_0123700101_M2S41360OVE.FIT
0070_0123700101_M1S40660OVE.FIT   0070_0123700101_M2S41470OVE.FIT
0070_0123700101_M1S40770OVE.FIT   0070_0123700101_M2X00000HBH.FIT
0070_0123700101_M1U00200AUX.FIT   0070_0123700101_M2X00000HCH.FIT
0070_0123700101_M1U00200CCX.FIT   0070_0123700101_M2X00000HTH.FIT
0070_0123700101_M1U00210IME.FIT   0070_0123700101_M2X00000PEH.FIT
0070_0123700101_M1U00220IME.FIT   0070_0123700101_M2X00000PTH.FIT
0070_0123700101_M1U00230IME.FIT
0070_0123700101_M1U00240IME.FIT
0070_0123700101_M1U00250IME.FIT
0070_0123700101_M1U00260IME.FIT
0070_0123700101_M1U00270IME.FIT
0070_0123700101_M1X00000HBH.FIT
0070_0123700101_M1X00000HCH.FIT
0070_0123700101_M1X00000HTH.FIT
0070_0123700101_M1X00000PEH.FIT
0070_0123700101_M1X00000PTH.FIT
Before you start, please make sure that the ODF directory is set and that you have created a summary file ...SUM.SAS and the Current Calibration Index File (CIF). Please check The System Setup page how to set the parameters and how to create those files.

The XMMSAS provides two ways to create your own event file, either you use the by the chain task emchain that combines several XMMSAS tasks or you work with those individual tasks that we will list and describe below. The structure of the emchain task and how to create an event file can be see in this postscript file.
For some earlier processed ODF from the Commissioning (orbits 20-46) and CAL PV (orbits 47-102) phases the ODF may not be complete. Check if e.g. a ...HCH.. file is present. If this is not the case, you have to run the task odffix. Please have a look at the example given ath the EPIC PN Event file creation page for a description.
The task emchain combines all the tasks listed below. The most simple way to run the chain is:
 emchain
In this way it will create a standard output events file. However, it is still possible to control the output by parameters of the emchain task. Here you can for example choose specific CCDs, or exposures (see the emchain manual for which parameters are available. In any case there is no choice of the name of the output file by using the chain. Because emchain creates a whole set of output files there is no way to choose you own file names. It is even not recommended for the EPIC MOS to choose the output file name by using the task evlistcomb as suggested for the EPIC PN data. In our example the following outfiles are created:
 P0123700101M2S002MIEVLI0000.FIT
 P0123700101M2S002FL_GTI0000.FIT  
 P0123700101M2S002FL_TSR0000.FIT
where P0123700101M2S002MIEVLI0000.FIT is the output event file in the imaging mode (..TIEVLI.. in the timing mode), P0123700101M2S002FL_GTI0000.FIT and P0123700101M2S002FL_TSR0000.FIT are Good Time Interval files that can be used for selecting out proton flares in the data. All those output files are created per instrument, per exposure and per mode.
The task emchain calls for each CCD the required XMMSAS tasks and then combines the files together into the final merged event file. It makes use of the following SAS tasks as described on this postscript file). The task emchain can be control by parameters, most of them are used for the single tasks that are called by emchain.
All steps have to be performed per CCD:
emframes: analyses the information of a frame (auxillary) file for one CCD/node of EPIC-MOS over one exposure. It adds columns for the quality flag, the dead time fraction, the time and the GATTI value to the file and performs several tests and computes the specific Good Time Intervals (GTI).
emframes auxiliaryset=/xmm_archive/orbitData/0070/0070_0123700101_M2S00200AUX.FIT \
         frameset=frame04.out withodfeventset=Y \
	 odfeventset=/xmm_archive/orbitData/0070//0070_0123700101_M2S00240IME.FIT \
	 neweventset=Y outeventset=event.in writegtiset=Y \
	 outgtiset=ccdgti.in
The example is for the 2nd observation of Camera M2 for CCD 4.

badpixfind: Finds new bad pixel and creates a new list,
badpix: Adding badpix extension to an events list and produces a badpix table that contains the information of the position and the type of defect of the bad pixel. The badpixelsets are written to a new directory `badpixfind':
 badpix eventset=event.in badpixset=../badpixfind/badpixfind04
emevents: Defines the final list of events, their position and time
 emevents odfeventset=event.in eventset=event04.fits 
where odfeventset defines the input file and eventset the output file. Please check in the ODF if there are offset/variance files available for the specific CCD/observation your are working on (they have the letters OVE in the end of the name, e.g. 0070_0123700101_M1S40110OVE.FIT for observation number 401 and CCD 1. If those file(s) are there, you have to add withoffvarsets=y offvarsets=`all OVE files in that observation'.
attcalc: transformation of detector into sky coordinates
 attcalc eventset=events04.fits refpointlabel=pnt atthkset=atthk.dat \
         withmedianpnt=Y attitudelabel=ahf
emenergy: Assigns energy and quality flag to events for one node of one EPIC-MOS CCD over one exposure. It prepares the spectral analysis of EPIC MOS data.
 emenergy ineventset=events04.fits neweoutput=y outeventset=events04_out.fits
where ineventset is the input file, newoutput is a switch to create a new output file, and outeventset is the output file.
evlistcomb: combines single CCD event files into one merged output event file. Here is the chance to choose the columns from ODFs that you want in the output event file. It is only possible to choose your own output file name by using the parameter imagingset in the line command task evlistcomb. In the chain (line command task as well as GUI) it has a fixed name, e.g. as in our example P0123700101M2S002MIEVLI0000.FIT In our example we choose TIME, X, Y, PI, and PATTERN of CCDs 1,4, 5, and 7, which are the CCDs in the middle of the detector. The column CCDNR in the events file is created automatically by the evlistcomb task.
 evlistcomb eventsets="events01.out events04.out events05.out events07.out" \
	    instrument=emos imagingset=events.fits \
            emosimgcolnames='"TIME" "X" "Y" "PI" "PATTERN"' \
            emosimgcoltypes='"double" "int32" "int32" "int16" "int8"' 
The fact that you have to put `emosimgcolnames' and `emosimgcoltypes' with the right types is not very user-friendly. Here is a list of all columns of an input events file and the types:
emosimgcolnames       emosimgcoltypes

TIME                 double
RAWX                 int16
RAWY                 int16
DETX                 int16
DETY                 int16
X                    int32
Y                    int32
PHA                  int16
PI                   int16
FLAG                 int32
PAT_TYP              int16
PAT_IND              int16
PAT_ORI              int16
PATTERN              int8
PAT_ID               int16
PAT_SEQ              int8
FRAME                int32
PHA_CTI              int16
CCDNR                int8