NAME

sxssecid -- Associate SXS secondary events to the primary and allow to recalculate event grades

USAGE

sxssecid infile outfile

DESCRIPTION

'sxssecid' executes in two calculations using the SXS event file : a) recalculate the grade for each event; b) associate secondary events to the primary. The setting of the parameter 'regrade' determines the order in which sxssecid executes the two functions. If 'regrade' is set to 'yes', 'sxssecid' first recalculates the grades and after associates secondary to the primary using the new recalculated grades. If 'regrade' set to 'no', the grade are not recalculated and 'sxssecid' only associates secondary to the primary using the column specified in the parameter 'itypecol' (d/f ITYPE). In both calculations events are excluded if : 1) they are flagged as baseline (BL) or event lost (EL) in the on-board graded column ITYPE and/or 2) any of the parameters 'ckrisetime' (event with risetime >127), 'ckctrec', 'ckctel', 'ckant' (event flagged in the STATUS column) are set to yes. By default all events below a PI threshold (see parameter 'pxpithr') are set to orphans when associate the secondary to the primary and skipped when assign new grade if regrade = yes.

Regrading Calculation
There are two components in the grade definition : 1) if an event is primary or secondary and 2) if an event is High Mid or Low resolution. 'sxssecid' regrades the events per pixel by first identifying if an event is primary or secondary, using the parameter 'dtprimary', and after if it is High or Mid or Low resolution with the parameters 'dtmidhigh' and 'dtlowmid'. These parameters are used as follows. A primary event is defined as having no preceding event within 'dtprimary' and a secondary event has at least one preceding event within 'dtprimary'. An High-res event has no events within 'dtmidhigh' on either side, and Mid-res none within 'dtlowmid' on either side.
Combining the two definitions : a) Hp events have no preceding event within 'dtprimary' and none within 'dtmidhigh'. b) Mp events have no preceding events within 'dtprimary' and must have the following event within 'dtmidhigh' and 'dtlowmid'. Lp events have no preceding events within 'dtprimary' and must have the following event within 'dtlowmid'. Ms events have at least one preceding event within 'dtprimary' and no event within 'dtlowmid'. Ls events have at least one preceding event within 'dtprimary' and one event within 'dtlowmid'.
The new grades are written to a new column specified by the 'itypecol' parameter using the same on-board convention which is : 0 for Hp, 1 for Mp, 2 for Ms, 3 for Lp, 4 for Ls, 5 for Baseline-BL, 6 for Lost - EL, 7 for Rejected - Rj. The name of the column may not be set to 'ITYPE' since a column named ITYPE already exist in the event file with the grades determined on on-board.

Identification of the secondary
The on-board processing assigns grades to each event however does not link the secondary to its parent primary. 'sxssecid' associates secondaries to its parent event that occurs within the same pixel. The primary-secondary association uses the grade definition as well as a timing test. The grade information is defined in a column of the event file (see parameter 'itypecol'). The timing test attempts to locate primary-secondary within the same pixel that are within a time interval specified in the parameter 'dtmidhigh'. It assumes that there is only one primary either an Hp and/or Mp and/or Lp for each pixel and all the secondaries are associated to these primary before next primary occurs.
The output of the primary-secondary association uses three columns: INDEX provides a unique index for each event, GROUPS links the secondary to the primary, SEQ records the sequence of the associated events in a group. The GROUPS column is populated as follows: Hp Mp and Ls events have GROUPS=INDEX; secondaries have GROUPS set equal to the index of the parent primary ; secondary events that do not have a primary within 'dtmidhigh' (orphans) have GROUPS set to a negative value with magnitude equal to the INDEX of the previous primary in the same pixel; events classified as baseline (BL) or lost (EL) have GROUPS set to NULL; GROUPS is set to NULL also for events that satisfy the condition set by the parameters 'ckrisetime' (event with risetime >127), 'ckctrec', 'ckctel', 'ckant' (event flagged in the STATUS column) if they are set to yes. The sequence in the SEQ column is assigned using the ITYPE+1 on the events in that sequence. For example the sequence Mp Ms Ms is recorded as 233 where each digit is ITYPE+1. All events that belong to the same sequence have the same value in the SEQ column. The value in SEQ is set to NULL if the event is an orphan and set to 999 if there more than 9 events in a group.

PARAMETERS

infile [filename]
Input SXS event file name. The file must have time assigned.

outfile [filename]
Name of the output file. This is a copy of the input file where the INDEX, GROUPS and SEQ columns (and the itypecol column if regrade=yes) are populated.

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

(dtprimary = CALDB) [string]
Time interval [ms] that distinguishes primary and secondary events. Used in the event regrading if regrade=yes. If set to CALDB, the parameter is read from the calibration database.

(dtlowmid = CALDB) [string]
Time interval [ms] that distinguishes low and mid-resolution events. Not used for primary/secondary association identification, but may be used for regrading of events if regrade=yes. If set to CALDB, the parameter is read from the calibration database.

(dtmidhigh = CALDB) [string]
Time interval [ms] that distinguishes high and mid-resolution events. Used for regrading of events if regrade=yes. If set to CALDB, the parameter is read from the calibration database.

(tol = 2.) [real]
Allowed tolerance in ns for associating secondaries and primaries.

(pxpithr = 600) [real]
If usepxpithr = ALL, events with PI below this value are labeled as orphans.

(usepxpithr = ALL) [string]
If usepxpithr = ALL, then events with PI < pxpithr are defined as orphans with no associated primary event. If regrade = yes, then such events are skipped when assigning a new grade.

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

(ckctel = no) [boolean]
If ckctel = yes, events identified as electrical crosstalk according to the STATUS column are assigned GROUPS=NULL, and are not regraded even if regrade=yes (yes/[no]).

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

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

(regrade = no) [boolean]
If regrade = yes, the events are regraded based on their assigned times and the dtprimary, dtlowmid, and dtmidhigh parameters. The newly calculated grade is written into the column specified by the setting of the 'itypecol' parameter. (yes/[no]).

(buffer = -1) [integer]
Rows to buffer (-1=auto, 0=none, >0=numrows).

(clobber = no) [boolean]
Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]
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 filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.

(debug = no) [boolean]
Diagnostic output is printed out on the screen if set to yes (yes/[no]).

(history = yes) [boolean]
Records tool parameters in HISTORY ([yes]/no).

(mode = ql) [string ql|hl|q]
Mode to query the parameter file. Acceptable values include: 'ql' (query and learn/remember), 'hl' (hidden and learn/remember), 'q' (query but don't remember), 'h' (hidden).(Optional)

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 CALDB. Create event_out.fits with INDEX, GROUPS and SEQcolumns populated accordingly.

      sxssecid infile=event_in.fits outfile=event_out.fits

2. Find the associated primaries for secondaries in the file event_in.fits based on a regrading with secondaries defined as those with preceding events within 60 ms, and high/mid/low resolution defined, respectively, as events with no events within 80 ms, at least one event within 80 (but not within 20) ms, and at least one event within 20 ms. Write the new grades to a new ITYPE2 column, and use this for identifying secondaries.

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

SEE ALSO

sxsflagpix

LAST MODIFIED

27 January 2016