Two files from two exposures (even from different instruments) are taken as input. These may be EPIC event lists or two other additional files (attitude files, orbit files etc [see comments]). The files are checked via their extension names (EVENTS, ATTHK, ORBIT) for their type, and depending on the type, certain attributes are checked to see whether the files are compatible with each other. In the attitude and orbit cases, any files can be merged together (so long as they are both attitude or both orbit files), whereas in the events case, some care should be taken. For instance event files from different modes should not be merged, though perhaps event files from different instruments can (see comments). Warnings are given when the event files are deemed not entirely compatible (i.e. their INSTRUME or FILTER keywords are different). Here it is up to the user to interpret the output files sensibly.
Also, in the event files case, the two pointings need to be close to each other; the accuracy of the reprojection degrades with the offset between the two pointings, and warnings will be given when this offset becomes significantly large. Only if the input files pass all the checks does the merging proceed and an output file (event list, attitude file, orbit file) is produced. The individual blocks (e.g. EVENTS) are merged in time order, as are the other relevant extensions (e.g. EXPOSUnn, STDGTI, GTI, etc [see comments]). In the event files case, the sky coordinates are deprojected and reprojected again onto a common sky position (given either by the user, via the parameters withradec, ra and dec, or as, by default, the mean of the two input pointings), and new WCS attributes are calculated (the size of the WCS `image' is given by the parameter imagesize). It is possible also to adjust the individual event file sky coordinates prior to merging. This is useful when one sees offsets between sources in two datasets. Changes to RA, Dec and position angle can be given for each of the input event files (see examples).
Given here is a summary of the current conditions whereby event files (or parts thereof [blocks/columns etc]) are or are not merged. In each condition, the necessary warning/error messages are given.
It is strongly recommended not to merge event files from different observations because of the difficulty of accurately using the merged file in downstream software. By default, an error is issued and the task aborted, if two input files with different observation numbers are used. However, expert users may override this behaviour by setting the command line parameter mergedifferentobs="yes".
If present, the following event file columns will be merged: TIME, RAWX, RAWY, DETX, DETY, X, Y, PHA, PI, FLAG, PATTERN, PAT_ID, PAT_SEQ, PAY_TYP, PAT_IND, PAT_ORG, CCDNR, WEIGHT. Up to 12 additional columns may be specified by command line parameter.
The output files can be used by evselect and the higher level detection and time analysis tasks. See the caveats and limitations listed in the comments section.
