NAME

rslsecid - Associate XRISM Resolve secondary events with primary events in groups, optionally reassigning event grades prior to grouping

USAGE

rslsecid infile outfile

DESCRIPTION

The rslsecid task identifies associations of Resolve secondary events with primary events, assigning them as members of groups that include one (and only one) primary and zero or more secondaries (secondaries not associated with any primary are referred to as "orphans"). If the 'regrade' parameter is set to yes, rslsecid reassigns all grades first and then uses the recalculated grades to make the associations. If 'regrade=no', the grades are not recalculated and the associations are made using the original grade designations in the column specified in the parameter 'itypecol'.

Resolve event grades consist of two components. (1) They are considered either primary or secondary based on the time interval from the proximate preceding event in the same pixel: primary when this interval is greater than the value specified by the 'dtprimary' parameter, secondary when there is at least one preceding event within this interval. (2) They are considered either high-, mid-, or low-resolution based on the time interval to the proximate preceding or following event in the same pixel: high when there are no events within 'dtmidhigh', mid when there are none within 'dtlowmid' (but at least one within 'dtmidhigh'), low if there is at least one event within 'dtlowmid'. Five possible grades result from combining these criteria: (a) Hp events with no preceding event within 'dtprimary' and none within 'dtmidhigh'; (b) Mp events with no preceding events within 'dtprimary' but at least one following event within 'dtmidhigh' (but none within 'dtlowmid'); (c) Lp events with no preceding events within 'dtprimary' but at least one following event within 'dtlowmid'; (d) Ms events with at least one preceding event within 'dtprimary' but none (preceding or following) within 'dtlowmid'; and, (e) Ls events with at least one preceding event within 'dtprimary' and at least one (preceding or following) event within 'dtlowmid'. In general, 'dtprimary'='dtmidhigh'.

When 'regrade=yes', new grades are written to a new column specified by the 'itypecol' parameter, using the on-board processing convention: 0 for Hp, 1 for Mp, 2 for Ms, 3 for Lp, 4 for Ls, 5 for Baseline (BL), 6 for Lost (EL), and 7 for Rejected (Rj). The name of the new column may not be set to the name of the pre-existing column, ITYPE.

The rslsecid task associates secondaries with 'parent' primary events in the same pixel. The primary-secondary association uses the grade information in the 'itypecol' column and the time spacing between events. Beginning with each primary event, all subsequent events within 'dtmidhigh' of the previous event are associated with that primary until the next primary occurs. Each event is labeled using three columns: INDEX, a unique counter for each event; GROUPS, a group identifier consisting of the INDEX of the primary event in the group (hence, GROUP=INDEX for Hp, Mp, and Lp events); and SEQ, that encodes the grades of all events in a group and their ordering. SEQ, which is identical for all events in a group, is formed by concatenating an integer representation of the grades of each event equal to ITYPE+1 (e.g., the sequence Mp Ms Ms is represented in the SEQ column as 233). If there are more than 9 events in a group SEQ is formed by appending 999 to that same grade integer representation (ITYPE+1) of the primary event for that group. For orphan events, the value of GROUPS is set to the negative of the INDEX value of the previous primary in the same pixel, and the value in the SEQ column is set to NULL.

Events are excluded from regrading and from consideration in associating events in groups (in which case the GROUPS value is set to NULL) if (a) they are baseline (BL) or lost (EL) events based on the 'itypecol' column values, (b) the 'ckrisetime' parameter is set to yes and the value of the column RISE_TIME > 127, (c) the 'ckctrec' parameter is set to yes and the event is flagged as a recoil crosstalk event in the relevant STATUS columns (is in close temporal proximity to a Calpixel event and meets the recoil crosstalk energy criteria), (d) the 'ckctel' parameter is set to yes and the event is flagged as an electrical crosstalk 1 event in the relevant STATUS columns (is part of an electrical crosstalk 1 grouping, but does not have the maximum PHA value in the group), (e) the 'ckctel2' parameter is set to yes and the event is flagged as an electrical crosstalk 2 event in the relevant STATUS columns (is part of an electrical crosstalk 2 grouping), (f) the 'ckant' parameter is set to yes and the event is flagged as coincident with an antico event in the STATUS column. If the 'usegrpxpithr' parameter is set to 'ALL', events with PI below the threshold specified by the 'grpxpithr' parameter are considered orphans, and skipped for grade reassignment if 'regrade=yes' as well as for inclusion in a GROUP.

PARAMETERS

infile [filename]
Input Resolve event file name. The file must have the TIME column assigned.

outfile [filename]
Output file name. The output file is a copy of the input file with INDEX, GROUPS, and SEQ (and 'itypecol' if 'regrade=yes') columns populated.

(itypecol = ITYPE) [string]
Name of the column used to identify grades for the primary/secondary association and grade sequence. If 'regrade=yes', 'itypecol' may not be set to ITYPE.

(dtprimary = CALDB) [string]
Time interval [ms] used to distinguish primary from secondary events in the grade calculation. The default value corresponds to the current on-board software setting; it generally should not be modified. If the parameter is set to CALDB, the value is read from a file in the calibration database (CalDB).

(dtmidhigh = CALDB) [string]
Time interval [ms] used to distinguish mid- from high-resolution events. The default value corresponds to the current on-board software setting; it generally should not be modified. If the parameter is set to CALDB, the value is read from a file in the CalDB.

(dtlowmid = CALDB) [string]
Time interval [ms] used to distinguish low- from mid-resolution events. The default value corresponds to the current on-board software setting; it generally should not be modified. If the parameter is set to CALDB, the value is read from a file in the CalDB.

(tol = 2.0) [double]
Tolerance [ns] allowed in event association.

(grpxpithr = 600) [integer]
If 'usegrpxpithr=ALL' events with PI below this value are labeled as orphans, and skipped during regrading if 'regrade=yes'.

(usegrpxpithr = ALL) [string ALL|NONE]
If 'usegrpxpithr=ALL', events with PI < grpxpithr are defined as orphans, and skipped during regrading if 'regrade=yes'. If 'usegrpxpithrm=NONE', PI is not considered in associating and regrading events.

(ckctrec = no) [boolean yes|no]
If 'ckctrec=yes', events identified as recoil crosstalk in the STATUS column are assigned GROUPS = NULL, and are not regraded if 'regrade=yes'.

(ckctel = no) [boolean yes|no]
If 'ckctel=yes', events identified as electrical crosstalk 1 in the STATUS column are assigned GROUPS = NULL, and are not regraded if 'regrade=yes'.

(ckctel2 = no) [boolean yes|no]
If 'ckctel2=yes', events identified as electrical crosstalk 2 in the STATUS column are assigned GROUPS = NULL, and are not regraded if 'regrade=yes'.

(ckant = no) [boolean yes|no]
If 'ckant=yes', events identified as coincident with antico events in the STATUS column are assigned GROUPS = NULL, and are not regraded if 'regrade=yes'.

(ckrisetime = yes) [boolean yes|no]
If 'ckrisetime=yes', events with RISE_TIME > 127 are assigned GROUPS = NULL, and are not regraded if 'regrade=yes'.

(regrade = no) [boolean yes|no]
If 'regrade=yes', events are regraded based on their assigned times and the 'dtprimary', 'dtlowmid', and 'dtmidhigh' parameter values. The newly calculated grades are written in the column specified by the 'itypecol' parameter.

(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 DEFAULT|NONE|file name]
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. Find the associated primaries for secondaries in the file event_in.fits, based on their original grades and the definition of secondaries given by the value of 'dtmidhigh' in the CalDB. Create event_out.fits with INDEX, GROUPS, and SEQ columns, populated accordingly.
  2.    rslsecid infile=event_in.fits outfile=event_out.fits
    
  3. Regrade the events, writing the new grades to the newly created ITYPE2 column, and calculate the event associations using these new grades based on a revised set of grade time criteria.
  4.    rslsecid infile=event_in.fits outfile=event_out.fits dtprimary=80 regrade=yes dtlowmid=20 dtmidhigh=80 itypecol=ITYPE2
    

SEE ALSO

rslflagpix

LAST MODIFIED

August 5, 2024