NAME
sxsflagpix -- Flag SXS events for antico and MXS event coincidence,
temporal proximity, and crosstalk
USAGE
sxsflagpix infile inantfile outfile antpsp inmxsGTI
DESCRIPTION
'sxsflagpix' identifies SXS events for coincidence with antico
detector events and mxs events, temporal proximity between two
events in any pixel, and electrical and recoil crosstalk. The
identifications are written in the STATUS column. 'sxsflagpix'
excludes lost and baseline pixel events, and events with risetime
exceeding 127 if 'ckrisetime=yes', when determining event-to-event
coincidence for temporal proximity, electrical and recoil crosstalk.
It also excludes events below a PI threshold, set in the parameter
'pxpithr', for any coincidence defined in the parameter 'usepxpithr'.
Any combination of flagging may be enabled by setting the 'calcant'
(antico), 'calcprox' (proximity), 'calcctrec' (recoil crosstalk),
'calcctel' (electrical crosstalk), 'calctel2' (electrical crosstalk
2), and 'calcmxs' (MXS) switch parameters. If the parameter
'dtflag=yes', the time intervals between crosstalking events, or
between pixel events and their coincident antico events, are written
out to additional columns (DTCEL for electrical crosstalk, DTCEL2
for electrical crosstalk 2, DTCTREC for recoil crosstalk, and DTANT
for antico coincidence) if the corresponding flagging is enabled. An
antico event file is required for antico flagging (see parameter
'inantfile'). A GTI containing the times when the MXS is on is used
to determine the MXS flagging (see parameter 'inmxsgti'). There is
an option to input an additional GTI file, unrelated to the MXS, to
flag events within that GTI (see 'gtifile' parameter). This file may
contain multiple GTI extensions, one applicable to all pixels and
the remaining applicable to each individual pixel.
The STATUS column has 16 bits, 14 of which are currently in use and
two of which are spare. The first bit flags events that are out or invalid
(0) or in and valid (1) of the GTI file applicable to all pixels.
The second bit flags the events that are out or invalid (0) or in
and valid (1) of the GTI file
applicable to individual pixels. The third bit flags events that are
coincident with antico events (1). The fourth bit flags events that
are within a temporal proximity (defined by parameter 'proxdt') of
another event in any pixel (1). The fifth and sixth bits flag events
for recoil crosstalk. The seventh and eight, and thirteenth and
fourteenth, bits flag electrical crosstalk. The ninth through twelfth
bits flag coincidence with MXS events.
Two formats are supported for the GTI file. The first format contains
up to 37 extensions: 1 general GTI and 36 pixel-dependent GTI. The DETNAM
keyword for the general GTI must be PIXEL and the DETNAM keyword values for
the pixel-dependent GTIs are PIXnn where nn is the pixel number, e.g. PIX04
for pixel 4. In this format, all extensions must contain columns START and
STOP which define the GTI. The second format may have up to two
extensions: 1 general GTI with START and STOP columns and 1 pixel-dependent
extension with columns START, STOP, and PIXEL. In the second format the
DETNAM keyword is set to PIXEL for both extensions. if the input GTI has
a single GTI extension with no DETNAM keyword defined, it is treated as a
general GTI. If the events need to be filtered using multiple general or
pixel-dependent GTI files, they must first be merged into a single GTI file
using the 'sxspixgti'.
Antico flagging: 'sxsflagpix' flags a pixel event as coincident
with and an antico event if the following condition is satisfied:
antdtpre < t(pixel)-t(antico)+antshift < antdtfol. The value of the
parameters 'antdtpre' and 'antdtfol' are time intervals that define
the window of coincidence, and the antico time is adjusted by the
parameter 'antshift' to account for the differences in time
assignment of a pixel event compared to an antico event. The antico
event file contains redundant entries for events channeled through
both sides of the PSP (A and B). 'sxsflagpix' uses only events from
one side. This is specified as either A or B by the 'antpsp'
parameter. Only antico events with duration and PHA greater then
the threshold values determined by the 'antdurthr' and 'antphathr'
parameters are considered in antico flagging.
Recoil crosstalk flagging: 'sxsflagpix' flags a pixel event if it is
a recoil crosstalk event with a cal-pixel (pixel 12) MnK X-ray
event. An event is considered as a recoil crosstalk event if its
time is within the time interval 'ctrecdt' of a calpixel event and
satisfies the following condition: ENERGY(EVENT) <= ENERGY(MnKa_low)
or ENERGY(MnKa_high) < ENERGY(EVENT) < ENERGY(MnKb_high), where
ENERGY(MnKa_low), ENERGY(MnKa_high), and ENERGY(MnKb_high) are set
by the parameters 'kalow', 'kahigh', and 'kbeta'.
Electrical crosstalk flagging: 'sxsflagpix' flags electrical
crosstalk across groups of pixels that are in wiring proximity,
using two different time intervals (one short, 'cteldt' parameter,
and one long, 'cteldt2' parameter). For each time scale, the
flagging uses two bits. STATUS bits 7-8 are assigned to the short
timescale, and bits 13-14 to the long timescale as follows: 00 - no
crosstalk, 10 - multiple pixels active within that timescale, 11 -
multiple pixels active within that timescale and this is the event
with the largest PHA in the multiple-pixel crosstalk group. Two
electrically crosstalking pixels must be in the same quadrant of the
SXS detector, and must have pixel indices within the quadrant
separated by no more than the number given by the 'ctelnear' (short
timescale) or 'ctelnear2' (long timescale) parameters. These
quadrant assignments and indices are stored in the CALDB pixel map
(see 'pixdeffile' parameter). If one or both of the electrical
crosstalk flagging options is enabled, the crosstalk multiplicity is
recorded in the two-digit CTMULT (short timescale) and/or CTMULT2
(long timescale) columns as follows. The first digit gives the
number of events in the crosstalk group, and the second digit the
PHA rank of the event in the group where 1 is assigned to the event
with the highest PHA.
MXS flagging: 'sxsflagpix' flags pixel events that are coincident
with MXS events defined using the MXS GTI (see 'inmxsgti'
parameter). Bits 9-10 are reserved for events coincidence with MXS
direct mode, 11-12 are reserved for events coincidence with MXS
indirect mode. Specifically, events with time within the MXS GTI set
bits 10 and 12. Events within the interval set by the parameter 'mxsdt'
(the MXS afterglow) set bits 9 and 11.
PARAMETERS
- infile [filename]
- Input SXS event file name. The file must have time assigned and
include a STATUS column.
- inantfile [filename]
- Input antico event file name. The file must have time assigned and
PHA calculated. Required if antico-flagging is switched on
(calcant=yes). Otherwise can be set to NONE.
- outfile [filename]
- Name of the output event file with STATUS assigned or reassigned.
- antpsp [string]
- If antpsp = "A" antico events processed through PSP-A only are
checked for antico coincidence; if antpsp = "B" antico events
processed through PSP-B only are checked for antico coincidence.
- (antshift = CALDB) [string]
- Time offset in seconds between event time and central time for
defining the window used for antico flagging. If set
to CALDB, the parameter is read from the calibration database.
- (gtifile = NONE) [filename]
- Input GTI filename. Events with times outside of all of the
intervals are flagged, for all valid SXS GTI extensions. The GTI may be
applied to all pixels in the SXS array if the extension header
includes the PIXEL DETNAM keyword. Pixel-specific GTI files are
identified by the PIXNN DETNAM header keyword, where NN=00,
01... 35).
- (calcant = yes) [boolean]
- If calcant = yes, events coincident with antico events are
flagged and an antico input file is required; if calcant = no this is
skipped ([yes]/no).
- (antdtpre = CALDB) [string]
- Time interval in seconds preceding the time of an antico event
(shifted by antshift) used to define the lower limit of the window
used for antico flagging. If set to CALDB, the parameter is read from
the calibration database.
- (antdtfol = CALDB) [string]
- Time interval in seconds following the time of an antico event
(shifted by antshift) used to define the upper limit of the window
used for antico flagging. If set to CALDB, the parameter is read from
the calibration database.
- (antswitch = 1) [integer]
- If antswitch = 0, values in the antico DURATION column from
inantfile are used in place of antdtfol; if 1 the antdtfol parameter
is used. Expected to always be 1.
- (antphathr = 71) [integer]
- PHA threshold for antico flagging. Only antico events with PHA
above this value are considered.
- (antdurthr = 2) [integer]
- Duration threshold for antico flagging. Only antico events with
duration above this value are considered.
- (calcctrec = yes) [boolean]
- If calcctrec = yes, events are checked for recoil crosstalk
flagging; if calcctrec = no this is skipped ([yes]/no).
- (ctrecdt = CALDB) [string]
- Time interval in seconds that defines event crosstalk due to
cal-pixel recoil electrons. Events occurring within ctrecdt of a
cal-pixel event are flagged if calcctrec = yes. If set to CALDB, the
parameter is read from the calibration database.
- (calcprox = yes) [boolean]
- If calcprox = yes, events are checked for basic temporal proximity
with any other event ([yes]/no).
- (proxdt = CALDB) [string]
- Time interval between events in seconds required for proximity
crosstalk to be flagged. If set to CALDB, the parameter is read from
the calibration database.
- (calcctel = yes) [boolean]
- If calcctel = yes, events are checked for electrical crosstalk
flagging using the cteldt time interval; if calcctel = no this is
skipped ([yes]/no).
- (pixdeffile = CALDB) [filename]
- Input file containing the SXS electrical pixel map. If set
to CALDB, the file is read from the calibration database.
- (cteldt = CALDB) [string]
- Time interval between events in seconds required for electrical
crosstalk to be flagged. If set to CALDB, the parameter is read from
the calibration database.
- (ctelnear = 1) [integer]
- Number of nearby pixels to be checked for electrical crosstalk,
where proximity is defined by pixdeffile and restricted to quadrants
of the SXS detector.
- (calcctel2 = no) [bool]
- If calcctel2 = yes, events are checked for electrical crosstalk
flagging using the cteldt2 time interval; if calcctel2 = no this is
skipped. (yes/[no])
- (cteldt2 = CALDB) [string]
- Time interval between events in seconds required for electrical
crosstalk 2 to be flagged. If set to CALDB, the parameter is read
from the calibration database.
- (ctelnear2 = 1) [integer]
- Number of nearby pixels to be checked for electrical crosstalk 2,
where proximity is defined by pixdeffile and restricted to quadrants
of the SXS detector.
- (pxpithr = 600) [integer]
- Events with PI values below this threshold are excluded from
flagging checks given by the usepxpithr parameter.
- (usepxpithr = ALL) [string]
- A comma-delimited list specifying which flagging types should use
the pxpithr parameter for excluding events. Allowed values in the list
are ALL, NONE, PROX (proximity), CTEL (electrical cross talk),
CTEL2 (2nd electrical cross talk), and CTREC (recoil cross talk).
Events that do not belong to the types specified in the list are excluded
from flagging regardless of their PI value.
- (calcmxs = yes) [boolean]
- If calcmxs = yes, events are checked for coincidence with MXS
events; if calcmxs = no this is skipped ([yes]/no).
- inmxsgti = mxs.gti [filename]
- Input MXS GTI filename providing the MXS start and stop times;
required if calcmxs = yes. Events are flagged for coincidence with MXS
operation when their times fall within any of the intervals in this
file.
- (mxsdt = CALDB) [string]
- Time interval by which the MXS pulse stop times given in the MXS
GTI are extended to account for MXS afterglow. If set to CALDB, the
parameter is read from the calibration database.
- (kalow = 5860) [real]
- Input Mn K-alpha minimum PHA value. A cal-pixel recoil event with
PHA less than this value has an additional flag set specifying that
the cal-pixel recoil crosstalk energy condition is met.
- (kahigh = 5930) [real]
- Input Mn K-alpha maximum PHA value. A cal-pixel recoil event with
PHA greater than this value (but less than kbeta) has an additional
flag set specifying that the cal-pixel recoil crosstalk energy
condition is met.
- (kbeta = 6450) [real]
- Input Mn K-beta PHA value. A cal-pixel recoil event with PHA less
than this value (but greater than kahigh) has an additional flag set
specifying that the cal-pixel recoil crosstalk energy condition is
met.
- (dtflag = no) [boolean]
- Add delta-time columns for cross-talk and antico (yes/[no]).
- (ckrisetime = yes) [boolean]
- Do not flag, and do use for flagging, events with RISE_TIME > 127
([yes]/no).
- (resetflags = NONE) [string]
- A comma-delimited list specifying which flagging types should have
their STATUS bits reset at the start of the task. Allowed values in the
list are ALL, NONE, PROX (proximity), CTEL (electrical cross talk),
CTEL2 (2nd electrical cross talk), CTREC (recoil cross talk),
ANT (antico), GTI (GTI file), and MXS (MXS GTI).
- (buffer = -1) [integer]
- Rows to buffer (-1=auto, 0=none, >0=numrows).
- (clobber = no) [boolean]
- Overwrites the existing output file if set to yes (yes/[no]).
- (chatter = 1) [integer]
- Chatter level for output. Set to 0 to suppress output,
or to 1, 2, or 3 for increasing the chatter of the output.
- (logfile = !DEFAULT) [string]
- Log filename. If set to DEFAULT uses the name of the task and, if
preceded by '!', overwrite the file if it exists. If set to NONE no
log file is created.
- (debug = no) [boolean]
- Diagnostic output is printed out on the screen if set to yes
(yes/[no]).
- (history = yes) [boolean]
- Records tool parameters in HISTORY ([yes]/no).
- (mode = ql) [string ql|hl|q]
- Mode to query the parameter file.
Acceptable values include: "ql (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).(Optional)
EXAMPLES
1. Flag for coincidence with MXS operation assuming no afterglow,
coincidence with antico events, and for recoil and electrical
crosstalk, using the time parameters in CALDB. The output file is
identical to the input file, but with the STATUS column set according
to the flagging results.
sxsflagpix infile=sxs_in.fits inantfile=antico.fits outfile=sxs_out.fits inmxsgti=mxs.gti mxsdt=0
2. Flag for coincidence with MXS operation assuming no afterglow,
coincidence with antico events, and for recoil and electrical
crosstalk, using the time parameters in CALDB. Also flag events
falling within times defined by the intervals in the file hkflag.gti.
sxsflagpix infile=sxs_in.fits inantfile=antico.fits outfile=sxs_out.fits gtifile=hkflag.gti inmxsgti=mxs.gti mxsdt=0
3. Flag, only, for coincidence with MXS operation with afterglow given by CALDB.
sxsflagpix infile=sxs_in.fits inantfile=antico.fits outfile=sxs_out.fits calcprox=no calcant=no calcctrec=no calcctel=no mxfgti=mxs.gti
SEE ALSO
ahtime, sxsanticopi
LAST MODIFIED
27 July 2016