XMM-Newton Science Analysis System
emevents (emevents-8.2.4) [xmmsas_20041122_1834-6.1.0]
Meta Index / Home Page
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.
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).
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):
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 and E
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
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
(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.
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.
If the CCD was read through both nodes (mode PRI PART W6 IMAGING only),
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
This means also rejecting events which become larger than the accepted
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.
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)
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 or E 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.
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.
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
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
- 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
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 + 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.
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 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 data.
A simple way to reject this noise is to reject
all events whose E 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 along particular rows or columns
and solving the linear equation relating E 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 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
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
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 energies
(the other E 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 energies convolved by the histogram of (GATTI + offsets) values,
be compared with a reference spectrum to look for variations
In parallel, SP_GATTI has an active part,
flagging for rejection with REJECTED_BY_GATTI all events with
E + 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
SP_GATTI and REJECT_E3 require an associated offset/variance file
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),
will select among a list of offsets files those
compatible with the events file in terms of CCD, node, mode and
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
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.
XMM-Newton SOC/SSC -- 2004-11-22