NAME
rslflagpix - Flag XRISM Resolve events for antico and MXS event coincidence,
temporal proximity, and crosstalk
USAGE
rslflagpix infile inantfile outfile antpsp inmxsgti inmxsnolgogti
DESCRIPTION
The rslflagpix task flags Resolve events that satisfy a variety of conditions.
Events are flagged for coincidence with
antico detector or MXS events. Pairs of events occurring within a pre-specified critical time
interval are flagged for temporal proximity. Groups of events that occur in the same
Resolve quadrant are flagged for two types of electrical crosstalk (the two types have
different timescales). Events that occur in close temporal proximity to
a pixel 12 calibration line event (hereafter "calpixel" event), are flagged for recoil crosstalk, with
additional flagging based on the energies of the two events. General and
pixel-dependent GTI can also be specified for flagging events that occur
within the GTI start and stop times.
The resulting identifications are used to populate the STATUS column in
the output file, based on the input event file specified by 'infile' (over-writing any
previous entries in the STATUS column). The rslflagpix task excludes
lost and baseline pixel events, and events with RISE_TIME exceeding
127 if 'ckrisetime=yes', when considering event-to-event flagging
for temporal proximity and the three types of crosstalk (recoil, electrical 1, and electrical 2). It also
excludes events below specified PI thresholds, set by the parameter
'pxpithr', for the types of coincidence listed for the parameter
'usepxpithr'.
Any combination of flagging may be enabled by appropriately setting the
switch parameters 'calcant' (antico), 'calcprox' (proximity), 'calcctrec' (recoil crosstalk),
'calcctel' (electrical crosstalk), 'calcctel2' (electrical crosstalk
2), and 'calcmxs' (MXS). General and pixel-dependent GTI flagging can be
turned off by specifying "NONE" for the input parameter 'gtifile'.
If 'dtflag=yes', the time intervals between crosstalking events, and
between pixel events and their coincident antico events, are written
out to additional columns (DTCTEL for electrical crosstalk, DTCTEL2
for electrical crosstalk 2, DTCTREC for recoil crosstalk, and DTANT
for antico coincidence) if the corresponding flagging is enabled. An
antico event file, identified by the parameter 'inantfile', is
required for antico flagging.
The parameter 'inmxsgti' specifies the name of an MXS GTI file in which
the time intervals include afterglow. An optional additional MXS GTI file can
be specified by the parameter 'inmxsnoglogti', which contains time intervals
that exclude afterglow. If this second GTI is specified, rslflagpix
determines separate flagging for events that occur only during MXS afterglow
periods. Both MXS GTI files must have four extensions each, one for each of the
four MXS LEDs. The extensions must be named GTIMXSFNON1, GTIMXSFNON2, GTIMXSFNON3,
and GTIMXSFNON4, for LED 1, 2, 3, and 4 respectively. LEDs 1 and 3 correspond to
MXS direct mode, and LEDs 2 and 4 correspond to MXS indirect mode.
The task rslflagpix does not flag events based on
individual LED GTI, but instead flags events based on direct or indirect MXS modes.
The STATUS column has 16 bits, 14 of which are currently in use and
two of which are spares. For each pixel event in the input file that satisfies the validity criteria
described above, the 14 bits are assigned as flags for the
following conditions, where bit 0 is the left-most bit of the 16-bit word
in the STATUS column:
Bit 0: Pixel event lies within general GTI
Bit 1: Pixel event lies within pixel-dependent GTI
Bit 2: Pixel event is coincident with antico event
Bit 3: Pixel event is in close temporal proximity to another pixel event
Bit 4: Non-calibration pixel event is in close temporal proximity to a calpixel event
Bit 5: If Bit 4 is set and the two events satisfy specific energy criteria for recoil crosstalk, bit 5 is set
Bit 6: Event is in a group of pixel events that are separated by less than the electrical crosstalk 1 timescale
Bit 7: This bit is set if Bit 6 is set and the event has the maximum PHA value in the group
Bit 8: Pixel event lies within a GTI interval for MXS direct mode including afterglow
Bit 9: Pixel event lies within a time interval that includes only afterglow for MXS direct mode
Bit 10: Pixel event lies within a GTI interval for MXS indirect mode including afterglow
Bit 11: Pixel event lies within a time interval that includes only afterglow for MXS indirect mode
Bit 12: Event is in a group of pixel events that are separated by less than the electrical crosstalk 2 timescale
Bit 13: This flag is set if Bit 12 is set, and the event has the maximum PHA value in the group
The critical time interval parameters that are used to set the flags for non-GTI bits are
obtained by rslflagpix either from a CalDB file or input parameters.
Two GTI file formats are supported, consisting of general and/or
pixel-dependent components. If the input
GTI has a single GTI extension with no DETNAM keyword defined, it is
considered to be a general GTI. If the DETNAM keyword is
set to PIXEL in the first extension, the GTI file is identified as pixel-dependent.
Two formats for the pixel-dependent GTI files are allowed.
For the first format, files may contain up to two extensions:
1 general GTI with START and STOP columns, and 1 pixel-dependent
extension with columns START, STOP, and PIXEL.
For the second format, files may contain up to 37
extensions: 1 general GTI and/or up to 36 pixel-dependent GTI. In
this case, the pixel-dependent GTI DETNAM keyword values are PIXNN where "NN" is
the pixel number, e.g., PIX04 for pixel 4. In this format, all
extensions must contain START and STOP columns that define the
GTI. Note: if the events need to be filtered using
multiple general or pixel-dependent GTI files, the separate GTI must first be
merged into a single GTI file using the rslpixgti task.
The antico event file contains redundant entries for events processed through
both sides of the PSP (A and B). The rslflagpix task uses only those events
corresponding to the PSP side specified by the 'antpsp' parameter. If the value
of the 'infile' PSPCTGCY keyword is MIOAFAIL, no antico events from PSP-A are
present in 'inantfile' and the antico events from PSP-B will be used for antico
coincidence determination if the 'checkpsp' parameter is set to yes – regardless
of the setting of 'antpsp'. Similarly, if the value of the 'infile' PSPCTGCY
keyword is MIOBFAIL, no antico events from PSP-B are present in 'inantfile' and
the antico events from PSP-A will be used if the 'checkpsp' parameter is set to
yes, overriding the 'antpsp' setting if necessary. Only antico events with
FLG_BASELINE and FLG_LOST_EVENT columns set to 0, and with DURATION and PHA
column values greater than or equal to the threshold values set by the
'antdurthr' and 'antphathr' parameters respectively, are considered valid for
antico flagging.
The rslflagpix task flags pixel events that result from recoil
crosstalk with a calpixel Mn K X-ray emission event. An event is
considered as a recoil crosstalk event if its time lies within the
interval 'ctrecdt' following that of a calpixel event, in which
case STATUS bit 4 is set. In addition, if the energies of the pixel 12 event and
the other event in the pair satisfy certain conditions, a second recoil crosstalk flag is set.
Specifically, if the pixel 12 event energy is consistent with a Mn K-alpha
or Mn K-beta photon having lost energy to recoil, compared to theoretical values, and if
the sum of the energies of the pair of events is consistent with the
intrinsic energy of Mn K-alpha or Mn K-beta, then STATUS bit 5 is set.
Since the calibration lines have a finite energy width, windows are defined
for testing individual photon energies against the intrinsic centroid energies of the Mn K-alpha or Mn K-beta lines.
For Mn K-alpha, the lower and upper bounds of the window are set by the input parameters
'kalow' and 'kahigh' respectively. For Mn K-beta, the lower and upper bounds of the window are set by the input parameters
'kblow' and 'kbhigh' respectively. Both windows are inclusive of the boundary values.
The rslflagpix task flags electrical crosstalk across groups of
pixels that are in wiring proximity using tests for two different time
intervals -- one short, using the 'cteldt' parameter, and one long,
using the 'cteldt2' parameter. Two STATUS bits are used for flagging
each electrical crosstalk timescale. STATUS
bits 6 and 7 are assigned to the short timescale (electrical crosstalk 1),
and bits 12 and 13 are assigned to the long timescale
(electrical crosstalk 2), 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 Resolve
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 identified
by the '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 multiplicity digit
represents the number of events in the crosstalk group, and the
second digit represents the PHA rank of the event in the group, where 0 is
assigned to the event with the highest PHA. In order for events to
get flagged for the short-timescale electrical crosstalk, an additional
condition must be satisfied, which is that the largest ratio of PHA values
for a pair of events must exceed a threshold value that is set by the
parameter 'pharatiothr'.
The STATUS flags may be selectively reset to 0 using the 'resetflags'
parameter for any combination of the above flagging. This is effected
by setting 'resetflags' to PROX (proximity), CTEL (electrical
crosstalk), CTEL2 (electrical crosstalk 2), CTREC (recoil crosstalk),
ANT (antico), GTI (GTI file), MXS (MXS GTI), any comma-delimited list
of the aforementioned strings, NONE, or ALL. This may be used (in
combination with the parameters that switch off specific types of
flagging) to increase computational efficiency when applying a second
pass of rslflagpix to an event file for the purpose of reassigning a
targeted subset of STATUS bits.
PARAMETERS
- infile [filename]
- Input Resolve event file name. The file must have time assigned and
include a STATUS column.
- inantfile [filename NONE|file name]
- Input antico event file name. The file must have time assigned and
PHA calculated. The file is required if antico-flagging is switched on
('calcant=yes'). Otherwise, it may be set to NONE.
- outfile [filename]
- Name of the output event file with STATUS assigned or reassigned, with optional new or re-calculated time-difference output
columns.
- antpsp = A [string A|B]
- If 'antpsp=A', only antico events processed through PSP-A are
checked for antico coincidence; if 'antpsp=B', only antico events
processed through PSP-B are checked for antico coincidence.
- (checkpsp = yes) [boolean yes|no]
- If 'checkpsp=yes', the contingency mode PSPCTGCY keyword is queried.
The PSP side checked for antico coincidence is switched from A to B if
'antpsp=A' and PSPCTGCY=MIOAFAIL, and from B to A if 'antpsp=B' and
PSPCTGCY=MIOBFAIL.
- (antshift = CALDB) [string CALDB|time offset value]
- Time offset [s] between event time and the center of the time
window used for antico flagging determined by the 'antdtpre' and
'antdtfol' parameters. If the parameter is set to CALDB, the value is
read from a file in the calibration database.
- (gtifile = NONE) [filename NONE|file name]
- Input GTI file name. Events with times inside any intervals in any
valid Resolve GTI extension in this file are flagged. The GTI may
include pixel-independent, and/or pixel-dependent extensions in one
of two formats.
- (calcant = yes) [boolean yes|no]
- If 'calcant=yes', and if an antico input file ('inantfile') is specified, events occurring within the antico
events coincidence window are
flagged. If 'calcant=no', antico flagging is skipped.
- (antdtpre = CALDB) [string CALDB|time interval value]
- Time interval [s] preceding the time of an antico event (shifted
by 'antshift') used to define the lower limit of the window used for
antico flagging. If the parameter is set to CALDB, the value is
read from a file in the calibration database.
- (antdtfol = CALDB) [string CALDB|time interval value]
- Time interval [s] following the time of an antico event (shifted
by 'antshift') used to define the upper limit of the window used for
antico flagging. If the parameter is set to CALDB, the value is
read from a file in the calibration database.
- (antphathr = 71) [integer]
- PHA threshold for antico flagging. Only antico events with PHA
values equal to or higher than this value are considered for flagging.
- (antdurthr = 2) [integer]
- Duration threshold (in units of 80 microsecond ticks) for antico flagging.
Only antico events with a duration that is equal to or higher than this value are considered for flagging.
- (calcctrec = yes) [boolean yes|no]
- If 'calcctrec=yes', events are checked for recoil crosstalk
flagging; if 'calcctrec=no', this is skipped.
- (ctrecdt = CALDB) [string CALDB|time interval value]
- Time interval [s] that defines event crosstalk due to calpixel
recoil electrons. Events occurring within 'ctrecdt' of a calpixel
event are flagged if 'calcctrec=yes'. If the parameter is set to
CALDB, the value is read from a file in the calibration database.
- (calcprox = yes) [boolean yes|no]
- If 'calcprox=yes', events are checked for basic temporal proximity
with an event in any pixel; if 'calcprox=no', this is skipped.
- (proxdt = CALDB) [string CALDB|time interval value]
- Time interval [s] between events required for proximity to be
flagged. If the parameter is set to CALDB, the value is read from a
file in the calibration database.
- (calcctel = yes) [boolean yes|no]
- If 'calcctel=yes', events are checked for electrical crosstalk 1
flagging using the 'cteldt' time interval; if 'calcctel=no' this is
skipped.
- (pixdeffile = CALDB) [filename CALDB|file name]
- Input file containing the Resolve electrical pixel map. If the
parameter is set to CALDB, the file is read from the calibration
database.
- (cteldt = CALDB) [string CALDB|time interval value]
- Time interval [s] between events required for electrical crosstalk 1
to be flagged. If the parameter is set to CALDB, the value is read
from a file in the calibration database.
- (ctelnear = 1) [integer]
- Maximum wiring proximity [pixels] to be checked for electrical
crosstalk, where wiring proximity is defined in the file set by 'pixdeffile',
and restricted to quadrants of the Resolve detector (i.e. electrical
crosstalk cannot occur between events in different quadrants).
- (calcctel2 = no) [boolean yes|no]
- If 'calcctel2=yes', events are checked for electrical crosstalk 2
flagging using the 'cteldt2' time interval; if 'calcctel2=no', this is
skipped.
- (cteldt2 = CALDB) [string CALDB|time interval value]
- Time interval [s] between events required for electrical crosstalk
2 to be flagged. If the parameter is set to CALDB, the value is read
from a file in the calibration database.
- (ctelnear2 = 1) [integer]
- Maximum wiring proximity [pixels] to be checked for electrical
crosstalk 2, where wiring proximity is defined in the file set by
'pixdeffile', and restricted to quadrants of the Resolve detector
(i.e. electrical crosstalk cannot occur between events in different quadrants).
- (pxpithr = "600 600 600 600") [string]
- Events with PI values below one of the appropriate thresholds in the list 'pxpithr'
are excluded from the flagging types that are specified by the 'usepxpithr' parameter. The four threshold
values correspond to the four different pixel event-to-event flagging types, in
the following order: proximity, electrical crosstalk 1, electrical crosstalk 2, and
recoil crosstalk. Note that if only a single value is specified for 'pxpithr', rslflagpix assumes that the
single value applies to all four flagging types.
- (usepxpithr = ALL) [string ALL|NONE|PROX|CTEL|CTEL2|CTREC]
- A comma-delimited list specifying the types of flagging for which
events with PI values below a threshold set in the list 'pxpithr' are
excluded from consideration for flagging. The options for 'usepxpithr' include
ALL, or NONE. Other values that may be included in the list are PROX (proximity), CTEL
(electrical crosstalk 1), CTEL2 (electrical crosstalk 2), and CTREC
(recoil crosstalk).
- pharatiothr = 50.0 [double]
-
Pixel events in a time-interval group can only qualify for electrical crosstalk 1 flagging
if the ratio between the largest and smallest PHA value in the group is equal to or
greater than the threshold 'pharatiothr'.
- (calcmxs = yes) [boolean yes|no]
- If 'calcmxs=yes', events are checked for coincidence with MXS
events; if 'calcmxs=no', this is skipped.
- inmxsgti = gti.fits [filename]
- Input MXS GTI file name providing the MXS start and stop times, including afterglow.
The file is required if 'calcmxs=yes'. Events are flagged for coincidence
with MXS operation when their times fall within any of the intervals
in this file.
- inmxsnoglogti = noglogti.fits [filename]
- Optional input MXS GTI file name providing the MXS start and stop times, excluding afterglow.
Bits 9 and 11 of the STATUS column in the output events files are flagged for events
whose times coincide with MXS afterglow-only time intervals. The task rslflagpix
calculates the afterglow time intervals by subtracting the stop times in 'inmxsnoglogti' from
the stop times in 'inmxsgti'. If "NONE" is specified for 'inmxsnoglogti', then no events are
flagged for MXS afterglow (the afterglow interval is effectively 0.0 in this case).
- (kalow = 5860) [double]
- Lower bound of energy window [eV] defining a photon as originating from the Mn K-alpha calibration
line, and therefore used in the process of classifying the photon as a genuine calpixel event or not.
This window and other criteria described earlier,
are used for the energy tests for STATUS column bit 5 calpixel recoil crosstalk flagging.
- (kahigh = 5930) [double]
-
Upper bound of energy window [eV] defining a photon as originating from the Mn K-alpha calibration
line, and therefore used in the process of classifying the photon as a genuine calpixel event or not.
This window and other criteria described earlier,
are used for the energy tests for STATUS column bit 5 calpixel recoil crosstalk flagging.
- (kblow = 6450) [double]
-
Lower bound of energy window [eV] defining a photon as originating from the Mn K-beta calibration
line, and therefore used in the process of classifying the photon as a genuine calpixel event or not.
This window and other criteria described earlier,
are used for the energy tests for STATUS column bit 5 calpixel recoil crosstalk flagging.
- (kbhigh = 6520) [double]
-
Upper bound of energy window [eV] defining a photon as originating from the Mn K-beta calibration
line, and therefore used in the process of classifying the photon as a genuine calpixel event or not.
This window and other criteria described earlier,
are used for the energy tests for STATUS column bit 5 calpixel recoil crosstalk flagging.
- (dtflag = no) [boolean yes|no]
- If 'dtflag=yes', additional columns containing the time
differences used for the crosstalk and antico tests are written to the
output file.
- (ckrisetime = yes) [boolean yes|no]
- If 'ckrisetime=yes', events with RISE_TIME > 127 will not be
considered for flagging event-to-event coincidence, i.e. temporal
proximity, and electrical and recoil crosstalk.
- (resetflags = NONE) [string ALL|NONE|PROX|CTEL|CTEL2|CTREC|ANT|GTI|MXS]
- A comma-delimited list specifying which flagging types should have
their STATUS bits reset at the start of the task (or ALL, or NONE).
Other allowed values in the list are PROX (proximity), CTEL (electrical
crosstalk), CTEL2 (electrical crosstalk 2), CTREC (recoil crosstalk),
ANT (antico), GTI (GTI file), and MXS (MXS GTI).
- (buffer = -1) [integer -1|0|N]
- Rows to buffer (-1=auto, 0=none, N>0=numrows).
- (clobber = no) [boolean yes|no]
- Overwrites the existing output file if set to yes.
- (chatter = 1) [integer 0|1|2|3]
- 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 file name. If set to DEFAULT, uses the name of the task and, if
preceded by "!", overwrites the file if it exists. If set to NONE, no
log file is created.
- (debug = no) [boolean yes|no]
- Diagnostic output is printed to the screen if set to yes
.
- (history = yes) [boolean yes|no]
- Records tool parameters in HISTORY.
EXAMPLES
- Flag for coincidence with MXS operation assuming no afterglow,
for coincidence with antico events, and for recoil and electrical
crosstalk (both types), using the time parameters in CalDB. The output file is
identical to the input file, except that the STATUS column is set according
to the flagging results. The input and antico files are an example of using a
XRISM Resolve unfiltered event file from OBSID 100050020.
rslflagpix infile=xa100050020rsl_p0px1010_uf.evt inantfile=xa100050020rsl_a0ac_uf.evt outfile=rsl_out.fits \
inmxsgti=mxs.gti inmxsnoglogti=mxs.gti
- Flag for coincidence with MXS operation assuming no afterglow,
for coincidence with antico events, and for recoil and electrical
crosstalk (both types), using the time parameters in CalDB. Also flag events
falling within times defined by the intervals in the file hkflag.gti.
The input and antico files are an example of using a
XRISM Resolve unfiltered event file from OBSID 100050020.
rslflagpix infile=xa100050020rsl_p0px1010_uf.evt inantfile=xa100050020rsl_a0ac_uf.evt outfile=rsl_out.fits \
gtifile=hkflag.gti inmxsgti=mxs.gti inmxsnoglogti=mxs.gti
- Flag only for coincidence with MXS operation, with afterglow.
The input and antico files are an example of using a
XRISM Resolve unfiltered event file from OBSID 100050020.
rslflagpix infile=xa100050020rsl_p0px1010_uf.evt inantfile=xa100050020rsl_a0ac_uf.evt outfile=rsl_out.fits \
calcprox=no calcant=no calcctrec=no calcctel=no mxsgti=mxs.gti inmxsnoglogti=mxs_noafterglow.gti
SEE ALSO
xatime, rslanticopi, rslpixgti
LAST MODIFIED
March 23, 2022