NAME

USAGE

DESCRIPTION

The sxsflagpix task 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 resulting identifications are used to populate the STATUS column in the input event file specified by 'infile' (over-writing any previous entries in the STATUS column). The sxsflagpix task excludes lost and baseline pixel events, and events with RISE_TIME exceeding 127 if 'ckrisetime=yes', when determining event-to-event coincidence for temporal proximity and electrical and recoil crosstalk. It also excludes events below a PI threshold, set by the parameter 'pxpithr', for the types of coincidence listed in the parameter 'usepxpithr'.

Any combination of flagging may be enabled by setting the 'calcant' (antico), 'calcprox' (proximity), 'calcctrec' (recoil crosstalk), 'calcctel' (electrical crosstalk), 'calcctel2' (electrical crosstalk 2), and 'calcmxs' (MXS) switch parameters. If the parameter 'dtflag=yes', the time intervals between crosstalking events, and 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, identified by the parameter 'inantfile', is required for antico flagging. A GTI file identified by the parameter 'inmxsgti' that contains the times when the MXS is on is used to determine the MXS flagging. Events with times within the intervals in an additional GTI file, unrelated to the MXS, identified by the optional parameter 'gtifile', are also excluded. This file may contain multiple GTI extensions, with one applicable to all pixels and the remaining applicable to individual pixels.

The STATUS column has 16 bits, 14 of which are currently in use and two of which are spare. The first bit flags an event based on the GTI applicable to all pixels. The flag is set to 1 if the event is valid and inside the GTI, and 0 otherwise. The second bit flags events contained within a pixel-specific GTI. The flag is set to 1 if the event is valid and inside the GTI, and 0 otherwise. The third bit flags events that are coincident with antico events, and is set to 1 for coincidence. The fourth bit flags events that are temporally proximate (as defined by the parameter 'proxdt') to another event in any pixel, and is set to 1 if the proximity criterion is satisfied. 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 GTI file formats are supported, consisting of general and/or pixel-dependent components. General GTI are identified by the DETNAM keyword PIXEL. Files with the first format may contain up to 37 extensions: 1 general GTI and/or up to 36 pixel-dependent GTI. In this case, the pixel-dependent GTI keywords 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. Files with the second format 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. 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 considered 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 task.

The sxsflagpix task flags a pixel event with time t(pixel) as coincident with an antico event if the following condition is satisfied: antdtpre < t(pixel)-t(antico)+antshift < antdtfol, for any time t(antico) corresponding to any (valid; see below) antico event in the file specified by the 'inantfile' parameter. The value of the parameters 'antdtpre' and 'antdtfol' define the coincidence time window, and the parameter 'antshift' accounts for the arrival time offset for pixel, compared to, antico events. The antico event file contains redundant entries for events processed through both sides of the PSP (A and B). The sxsflagpix task uses only those events corresponding to the PSP side specified by the 'antpsp' parameter. Only antico events with FLG_BASELINE and FLG_LOST_EVENT columns set to 0, and with DURATION and PHA column values greater then the threshold values set by the 'antdurthr' and 'antphathr' parameters respectively, are considered valid in antico flagging.

The sxsflagpix task flags pixel events that result from recoil crosstalk with a calpixel (pixel 12) MnK X-ray event. An event is considered as a recoil crosstalk event if its time lies within the interval 'ctrecdt' following that of a calpixel event and satisfies the following energy condition: ENERGY <= 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', respectively. The fifth STATUS column bit is set to 1 if the timing criterion is met, and the sixth STATUS bit also set to 1 if the energy condition is met.

The sxsflagpix task flags electrical crosstalk across groups of pixels that are in wiring proximity using 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. The seventh and eighth STATUS bits are assigned to the short timescale, and the thirteenth and fourteenth bits 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 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 1 is assigned to the event with the highest PHA.

The sxsflagpix task flags pixel events that are coincident with MXS events defined by the input MXS GTI file ('inmxsgti' parameter). The ninth and tenth bits are reserved for event coincidence with the MXS operating in direct mode. The eleventh and twelth bits are reserved for event coincidence with the MXS in indirect mode. The ninth and eleventh bits are set to 1 when the event time lies within any MXS GTI; the tenth and twelth when the event time lies within the afterglow extension of the MXS time intervals set by the parameter 'mxsdt'.

The STATUS flags may be selectively reset to 0 using the 'resetflags' parameter for any combination of the above flagging. This is affected 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 sxsflagpix to an event file for the purpose of reassigning a targeted subset of STATUS bits.

PARAMETERS

infile sff_in.evt [filename]

Input SXS event file name. The file must have time assigned and include a STATUS column.

inantfile = atisff.evt [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 = sff_out.evt [filename]

Name of the output event file with STATUS assigned or reassigned.

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.

(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 '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 SXS 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', events coincident with antico events are flagged, and an antico input file is required. If 'calcant=no', this 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.

(antswitch = 1) [integer 0|1]

If 'antswitch=0', values in the antico DURATION column from 'inantfile' are used in place of 'antdtfol'. If 'antswitch=1', the 'antdtfol' parameter is used.

(antphathr = 71) [integer]

PHA threshold for antico flagging. Only antico events with PHA above this value are considered for flagging.

(antdurthr = 2) [integer]

Duration threshold (in units of 80 microsecond ticks) for antico flagging. Only antico events with duration above 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 flagging using the 'cteldt' time interval; if 'calcctel=no' this is skipped.

(pixdeffile = CALDB) [filename CALDB|file name]

Input file containing the SXS 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 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 proximity is defined in the file set by 'pixdeffile', and restricted to quadrants of the SXS detector.

(calcctel2 = no) [boolean yes|no]

If 'calcctel2=yes', events are checked for electrical crosstalk 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 proximity is defined in the file set by 'pixdeffile', and restricted to quadrants of the SXS detector.

(pxpithr = 600) [integer]

Events with PI values below this threshold are excluded from the flagging items that are specified by the 'usepxpithr' parameter.

(usepxpithr = ALL) [string ALL|NONE|PROX|CTEL|CTEL2|CTREC]

A comma-delimited list specifying the types of flagging from which events with PI values below the threshold set by 'pxpithr' are excluded from coincidence consideration (or ALL, or NONE). Values that may be included in the list are are PROX (proximity), CTEL (electrical crosstalk), CTEL2 (electrical crosstalk 2), and CTREC (recoil crosstalk).

(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; this 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.

(mxsdt = CALDB) [string CALDB|time interval value]

Time interval [s] 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 value is read from a file in the calibration database.

(kalow = 5860) [double]

Energy [eV] lower limit lying below the Mn K-alpha calibration line for flagging a calpixel recoil crosstalk event. If an event meets the temporal proximity criterion for calpixel recoil flagging, and its energy is lower than 'kalow', the event is flagged as a recoil crosstalk event satisfying the energy condition.

(kahigh = 5930) [double]

Energy [eV] upper limit lying above the Mn K-alpha calibration line for flagging a calpixel recoil crosstalk event. If an event meets the temporal proximity criterion for calpixel recoil flagging, and its energy is higher than 'kahigh' but lower than 'kbeta', the event is flagged as a calpixel recoil crosstalk event satisfying the energy condition.

(kbeta = 6450) [double]

Energy [eV] lower limit lying below the Mn K-beta calibration line for flagging a calpixel recoil crosstalk event. If an event meets the temporal proximity criterion for calpixel recoil flagging, and its energy is lower than 'kbeta' but higher than 'kahigh', the event is flagged as a calpixel recoil crosstalk event satisfying the energy condition.

(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). 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, 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 mxsgti=mxs.gti 

SEE ALSO

LAST MODIFIED