XMM-Newton Science Analysis System


emevents (emevents-8.8) [xmmsas_20230412_1735-21.0.0]

Description

emevents flags unvalid events (following evatt), subtracts bad pixels, merges events split over two nodes, separates piled up diagonal events into two, adds the time column and monitors the GATTI performance. It also modifies the RAWX and RAWY coordinates to center the events and computes camera coordinates. emevents modifies the number of events. Therefore after it the event file is not consistent with the NVALID field of the frame file any more. It may be applied as is to slew data.

As a preliminary step, emevents rejects events with invalid FRAME, RAWX, RAWY and PATTERN. Those are the result of telemetry errors. They are removed from the list altogether (not only flagged).

emevents calls (in order) the following subroutines, all of which can be individually switched off (this is provided for calibration and debugging activities, the result will not in general be scientifically useful when not used with the default settings):

• EV_REC. In EDU Threshold mode (associated to telemetry REDUCED IMAGING mode), all pixels above the EMDH lower threshold and below the EMDH upper threshold are transmitted individually (no event recognition is performed on board). EV_REC performs the same pattern analysis (Fig. 1) as on-board, with the difference that it is performed with the EDU threshold set at the EMDH lower threshold (everything below that was lost) and the energies E$_3$ and E$_4$ cannot be recovered.
  EV_REC generates the ENERGYE1 and ENERGYE2 columns (per event) from the original ENGYE1E2 column (per pixel). It flags the events outside the EMDH thresholds with OUTSIDE_THRESHOLDS.
  In Imaging mode this pattern analysis is performed after CUT_BAD if analysepatterns is set to True.
  In Timing mode this pattern analysis is used to reject events classified as singles or bipixels by the 1-D pattern analysis on board (Fig. 2), but which are actually part of a large track from a cosmic-ray in the framestore area. A 2-D pattern analysis, similar to that in Imaging mode (Fig. 1), is run locally around all events with PATTERN 0 or 1 and the event is accepted only if it would have passed the Imaging pattern analysis, with any PATTERN less than 30. Otherwise it is flagged as COSMIC_RAY. No such cosmic-ray rejection is performed if analysepatterns is set to False. This may not be applied in Compressed Timing mode because most events do not have a valid RAWX and PATTERN in that mode.
  If Timing mode was configured on-board with EDUMODE=3 and Imaging patterns (non-standard), then no additional pattern analysis is carried out within emevents. Instead the PATTERN values are converted to Timing patterns (Fig. 2) (between 0 and 3), and all events with vertical extension are flagged as CLOSE_TO_BRIGHTPIX. Those are true events, but their energy is wrong because it was added to that of another event.
• CUT_BAD. On-board all events centered on a bright pixel (declared in the on-board library) are rejected, but weak bad pixels (with low charge contents) can also be included in X-ray events next to them. Those events must be corrected for that. To that end all areas around bright pixels (declared or not in the on-board library), and next to borders, may be reanalysed, putting the bright pixels and the pixels outside the declared window to 0. In the process events corresponding to bright pixels not declared on board are flagged as ON_BADPIX. If a bright pixel is the main pixel of a split event, it may appear twice in output: the original event (flagged as ON_BADPIX) plus what remains after removing the bright pixel.
  Bad pixels are read from the bad pixels extension added by badpix. Dead pixels are treated separately. Events on a pixel declared dead are flagged as ON_BADPIX whatever their PATTERN.
  In TIMING mode there are no bad pixels, only bad columns. The events are not reanalysed, but simply flagged with ON_BADPIX. The same happens in Imaging mode when analysepatterns is set to False. This may not be applied in Compressed Timing mode because most events do not have a valid RAWX in that mode.
• BINODAL. If the CCD was read through both nodes (mode PRI PART W6 IMAGING only), X-rays interacting close to the median column of the CCD have their charge cloud split over both nodes. BINODAL recognizes as only one event those which have been detected on both sides, using the same patterns as on-board (Fig. 1). This means also rejecting events which become larger than the accepted patterns. Only events with their maximum on this side of the border are kept in the list (i.e. the event list remains formally associated to one node). If the frame for the other node is flagged as bad, then its events should not be merged. Instead events immediately next to the other half of the CCD should be flagged as CLOSE_TO_CCD_BORDER.
  
• DIAGO. Diagonal patterns (26 – 29 on Fig. 1) are mostly due to two close-by single events. DIAGO forms two events out of one in that case. Both events are flagged with DIAGONAL to distinguish them from true single events. The second event is created only if its charge (i.e. E$_2$) is above the EMDH lower threshold. This operation does not respect the order of increasing RAWY within a frame. This routine is not applicable in TIMING mode.
  When either E$_1$ or E$_2$ is within one HWHM of the energy of Si K (1740 eV), the event can be due to partial absorption associated with Si fluorescence, caught in a neighbouring pixel. This appears as a line at that energy in the spectrum of diagonals. If keepsifluor is set to True, these events are not split in two but their PATTERN is changed from diagonal to bipixel (so that it receives the appropriate calibration), and it is flagged with DIAGONAL (to remember it was). As a side effect this creates a hole in the spectrum of diagonals at the energy of 1740 eV.
• CUT_GTI. All events whose frames were flagged for rejection by emframes (flag above 64) are flagged for rejection with IN_BAD_FRAME. Events whose frames were flagged below 64 by emframes are flagged with IN_SPOILED_FRAME. “cosmic-ray” events (patterns 30 and 31 in Fig. 1, read from CRPATi keywords) are flagged with COSMIC_RAY. CUT_GTI propagates the FRMTIME and CRPATi keywords.
• PUT_XY centers the events (telemetered positions are those of the upper-right corner of the 5x5 pattern area), subtracts the underscan (not relevant to the user) and adds 1 (for coherence with the FITS standard on images) so that coordinates run from 1 to 600. It also subtracts the underscans and adds 1 to the WINDOWX0 and WINDOWY0 keywords for coherence. Finally, it subtracts the under + overscans (in full frame mode) or 2 (in window mode) to the WINDOWDX and WINDOWDY keywords.
  It then computes the camera coordinates DETX, DETY, in the CAMCOORD2 coordinate system as described in cal, in units of 0.05 arcseconds. This includes by default randomisation (within a CCD pixel) to avoid Moiré effects. Randomisation may be switched off using randomizeposition=N. In TIMING mode the missing coordinates are replaced by the SRC_RAWX, SRC_RAWY keywords (or the center of the CCD if those keywords do not exist) for computing the camera coordinates, and double events (always centered on the left pixel) are moved half a pixel to the right.
  PUT_XY flags the (false) events outside the window with OUT_OF_CCD_WINDOW.
• PUT_TI (IMAGING mode) copies for each event of a given frame the same time computed as the middle between the start and end times of the current frame. Optionally time randomisation (within a frame) may be performed using randomizeposition=Y.
  PUT_TI (or PUT_TT) creates and fills the EXPOSURE extension, with precise time and duration of each frame and the effective fraction of observing time, corrected for dead-time using the CRRATIO column of the frame file. The (small) frame transfer time (during which the sky is actually observed but smeared over a column) is subtracted from the frame duration TIMEDEL. Following OGIP/93-003, the time is that of the center of each frame (i.e. the same as that of the events).
• PUT_TT (TIMING mode) computes the time for each event as a reference time (the start time of the current cycle) plus (y$_i$ + 0.5) times the clocking time. Precise corrections on the basis of the source position on the CCD are not done at this level. Times are computed as if the source was at the center of the CCD.
• REJECT_ROWS. Some instrumental effects result in several events following one another in the same row in one frame (particularly at small RAWY), while this is unlikely for normal X-rays. A simple way to reject this noise is to reject all events (of that frame) found in rows with many events in a given frame. This is done with flag ON_BADROW. The threshold may be set via maxeventsperrow.
  To avoid rejecting true events for bright extended sources or strongly piled-up sources, the average number of counts in that row plus twice its square root (2 $\sigma$ security) is added to maxeventsperrow.
  It is often the case that spurious events occur in nearby rows as well (in the same frame). This is addressed by checking rows within widthnexttorow of a bad one. As many events are rejected in those rows (by increasing distance to the bad row) as there are in excess of average.
• REJECT_E3 (IMAGING mode, not reduced IMAGING). Some instrumental effects result in wrong events associated with pathological (usually negative) charge values next to it. This information is known through the E$_3$ data. A simple way to reject this noise is to reject all events whose E$_3$ is less than a lower threshold (read from the E3THRES_ccd field in the XMM_MISCDATA CCF file). This is done with flag UNDERSHOOT, and has very little effect on true X-rays.
  Sometimes the offsets applied by the EDU are much larger than what they should be for normal event detection. This can be intentional (to neutralise a noisy column, as is done on both sides of the window) but it can also happen serendipitously (bit flips in the EDU memory). REJECT_E3 looks for such large offsets (64 or more above normal) by looking for systematically low E$_3$ along particular rows or columns and solving the linear equation relating E$_3$ to the offsets. The result (as well as the normal patched columns) is written in the OFFSETS extension. The events directly on such rows or columns with wrong offset are flagged with ON_BADOFFSET. The test on E$_3$ is applied after correction for the additional offsets. This automatic detection of bad offsets is not applied in Small Window mode because the additional electronic noise in that mode confuses the algorithm. The detection may also be switched off manually (in other modes) via the detectbadoffsets parameter.
• REJECT_FLICKERING (IMAGING mode). In several CCDs, a pixel may suddenly release charge over several frames, more or less randomly over the CCD. This can result in 10 events or so very close to each other, and can lead to spurious source detection. Because those events follow each other very closely in frame, they may be detected by looking at peaks in FRAME, RAWX, RAWY space. They cannot be mistaken with a flaring source because they are much more spatially peaked than a source (most events are in the same pixel).
  Cosmic-rays can also result in peaks in FRAME, RAWX, RAWY space. Many, but not all, associated events have a “cosmic-ray” PATTERN. They are not as spatially concentrated as the flickering events, but they can be distinguished from a flaring source because they are usually very elongated (they are due to particles at grazing incidence).
  The search is done in boxes whose half-size in FRAME, RAWX, RAWY is defined by triplets provided by the user via tolfxy. The default is optimised for the flickering events. tolfxy=“5 2 2 2 5 5” is better optimised for the cosmic-rays, but removes a small fraction of source counts (for that reason it is not default).
• SP_GATTI. In order to check the GATTI correction it is possible to compute the energy of events as it was seen by the ADC. This is done by adding the GATTI value and the offsets to all E$_1$ energies (the other E$_i$ are sums and therefore unsuitable to this purpose) and forming their spectrum (for events unflagged by CUT_GTI). All small scale (in energy) structures in the charge to ADU conversion should reappear in this spectrum. After dividing it by the direct spectrum of E$_1$ energies convolved by the histogram of (GATTI + offsets) values, this can be compared with a reference spectrum to look for variations (outside emevents).
  In parallel, SP_GATTI has an active part, flagging for rejection with REJECTED_BY_GATTI all events with E$_1$ + GATTI + offsetx(RAWX) + offsety(RAWY) = 4095 (range of the ADC), which should have been rejected by the EMDH upper threshold but were not due to the GATTI mechanism.
  In TIMING mode this test is restricted to single events, as ENGYE1E2 is the total charge over all pixels above threshold in the event. This routine is not applicable in Compressed TIMING mode (no PATTERN).

EV_REC, CUT_BAD, DIAGO and BINODAL may run only on a fresh ODF event file, not on the result of a previous run of emevents.
PUT_TIME, CUT_GTI and SP_GATTI require an associated frame file. If frameset is not set then an empty EXPOSURE extension is created to allow propagating the CCD-specific keywords after evlistcomb.

SP_GATTI and REJECT_E3 require an associated offset/variance file or extension. It is also advised to provide it for CUT_BAD and BINODAL. As it is not always obvious to know which offsets file is the right one (if several modes were used in an observation, there will also be several offsets files with different exposure numbers), emevents will select among a list of offsets files those compatible with the events file in terms of CCD, node, mode and window parameters. Among the compatible files emevents will select that with DATE-OBS closest to DATE-OBS of the events file, first within the offsets files obtained before the events file, then within those obtained after the events file if none was obtained before.
The first and last four column offsets (in the window) are patched to 4095 as is done in operations.
If no local offset/variance file is available (because the standard values were used), or if offvarsetsis not set emevents will read the offsets from the cal. If the offsets actually used were different, this will result in a large number of spGatti11 warnings and the flagging of events with truncated energy will be wrong.