NAME

USAGE

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

1. 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

2. 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

3. 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

LAST MODIFIED