NAME

USAGE

DESCRIPTION

The sxssecid task identifies associations of SXS 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, sxssecid 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'.

SXS 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 sxssecid 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). SEQ is set to 999 if there are more than 9 events in a 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 STATUS column, (d) the 'ckctel' parameter is set to yes and the event is flagged as an electrical crosstalk event in the STATUS column, (e) the 'ckant' parameter is set to yes and the event is flagged as coincident with an antico event in the STATUS column. If the 'usepxpithr' parameter is set to 'ALL', events with PI below the threshold specified by the 'pxpithr' parameter are considered orphans, and skipped for grade reassignment if 'regrade=yes'

PARAMETERS

infile [filename]

Input SXS event file name. The file must have the TIME column assigned.

outfile = out.fits [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] that distinguishes primary from secondary events. If the parameter is set to CALDB, the value is read from the calibration database (CalDB).

(dtlowmid = CALDB) [string]

Time interval [ms] that distinguishes low- from mid-resolution events. If the parameter is set to CALDB, the value is read from the CalDB.

(dtmidhigh = CALDB) [string]

Time interval [ms] that distinguishes high- from mid-resolution events. If the parameter is set to CALDB, the value is read from the CalDB.

(tol = 2.0) [double]

Tolerance [ns] allowed in event association.

(pxpithr = 600) [double]

If 'usepxpithr=ALL' events with PI below this value are labeled as orphans, and skipped during regrading if 'regrade=yes'.

(usepxpithr = ALL) [string ALL|NONE]

If 'usepxpithr=ALL', events with PI < pxpithr are defined as orphans, and skipped during regrading if 'regrade=yes'. If 'usepxpithr=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 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.

   sxssecid infile=event_in.fits outfile=event_out.fits

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

   sxssecid infile=event_in.fits outfile=event_out.fits dtprimary=80 regrade=yes dtlowmid=20 dtmidhigh=80 itypecol=ITYPE2

SEE ALSO

LAST MODIFIED