NAME

hxievtid -- Reconstructs HXI events

USAGE

hxievtid infile outfile remapfile fluorefile badpixfile enecutfile

DESCRIPTION

'hxievtid' determines whether the signals in an occurrence constitute a valid event and computes the event position and the energy deposited in the detector. The input file to 'hxievtid' is an SFF file with variable length array columns where each row contains an occurrence with multiple signals recorded at a given time. The output event file, specified by the parameter 'outfile', has a different structure and do not contain columns with variable length arrays. In this output file, each row corresponds to a reconstructed event and the columns 'RAWX', 'RAWY' and 'PI' contain the reconstructed position and energy of that event along with additional columns containing other event characteristics, as described below.

The HXI consists of five detector layers in a vertical stack: four Si strip detectors at the top and a single CdTe detector at the bottom. Each layer is a strip detector with top side strips running perpendicular to bottom side strips. Signals in more than one layer are rejected unless they are reconstructed with an X-ray fluorescence event. Signals below the threshold PHA values given in badpixfile are not used in the reconstruction. The only localization patterns recognized as a valid signal are: 1. One signal on the top side and one signal on the bottom side. 2. One signal on the top side and two signals in adjacent strips on the bottom side. 3. Two signals in adjacent strips on the top side and one signal on the bottom side. 4. Two signals in adjacent strips on the top side and two signals in adjacent strips on the bottom side. Occurrences with signals matching one of the template patterns in both the CdTe layer and one Si layer may be accepted, if the reconstructed energy deposited in the Si layer is within one of the ranges for a fluorescence X-ray from the CdTe layer.

The reconstructed energy of an event is computed using the signal EPI values calculated in hxisgdpha. For events occurring in a single layer, the event energy (EPI) in keV is taken to be the sum of the one or two signals in the top layer for Si or the bottom layer for CdTe. For events with signals in a single Si layer and the CdTe layer, the EPI is taken from the one or two bottom layer signals in the CdTe layer. The PI value of the event is calculated using a channel size of 0.1 keV. The coordinate location (RAWX, RAWY) is evaluated by taking the strip number associated with the signal with the larger EPI in both top (RAWY) and bottom (RAWX) sides. In the case of an occurrence with both signals equally split and having the same EPI, then the signal determining the position is chosen randomly. For events with signals in two layers,one on Si and one on CdTe, the position this procedure is applied for signals in the CdTe layer.

Reconstruction results for each occcurrence are in the output file specified by the 'outfile' parameter. Columns copied from the input SFF are TIME, OCCURRENCE_ID, CATEGORY, FLAG_SEU, FLAG_LCHK, FLAG_TRIG, FLAG_TRIGPAT, FLAG_HITPAT, FLAG_FASTBGO, LIVETIME, PROC_STATUS, and STATUS.

Output file columns populated by the reconstruction are as follows:
EVTCAT: event category = 1 for 'one hit, good', 2-5 for 'two hits, good', 6 for 'energy test failed', 7 for 'two hits, both Si layer', 8 for 'invalid hit or hits', 9 for 'no hits found', 10 for 'reconstruction failed, more than two hits, 11 for 'no reconstruction, output set to NULL'
SIGNAL: number of signals per side
SIGPOS: signal position per side (X or Y)
GOODBAD: good (0) or bad (1) flag per side
VALIDHITS: hit validity per layer
LAYER: layer number = 0-3 for Si or 4 for CdTe
ENE_TOTAL: sum of EPI per occurrence
PI: pulse invariant
RECO_STATUS: bit flags describing the reconstruction of each occurrence (see below)
RAWX, RAWY: HXI RAW pixel coordinates of each reconstructed event
EPITOP: total EPI for top layers
EPIBOT: total EPI for bottom layers
EPICUT: code for energy cut = 0 for OK, 1 for 'exclude high', 2 for 'exclude low', 3 for 'no signal', 4 for 'below threshold', or -999 as a null value

Addditional coordinate columns are added to the file but populated later by task 'coordevt': ACTX, ACTY, DETX, DETY, FOCX, FOCY, X, and Y.

The bit flags in the RECO_STATUS (reconstrunction status) column are as follows:

 Bit  Description
 ------(Occurrence mode identification)-------------------------------
  0    Mode is Am 241
  1    Mode is PSEUDO
  2    Mode is CALMODE
  3    Mode is READALL
  4    Mode is NOTSURE
 ------(Event reconstruction skipped for this occurrence)-------------
  5    Bad PROC_STATUS
  6    Mode is READALL or CALMODE and SKIPRECO option is YES
  7    Occurrence has no signals
  8    FASTBGO or HITPAT flag is set and REJECTBGO option is YES
 ------(Event reconstruction outcome)---------------------------------
  9    Event could not be reconstructed

PARAMETERS

infile [filename]
Input HXI event date file. This is the SFF, output of the hxisgdpha task.

outfile [filename]
Output event file.

remapfile = CALDB [filename]
File containing the remapping of ASIC and READOUT numbers. If the parameter is set to CALDB, the default, the file is read from the calibration database.

fluorefile = CALDB [filename]
File containing the energy ranges of fluorescence electrons in CdTe and Si. If the parameter is set to CALDB, the default, the file is read from the calibration database.

badpixfile = CALDB [filename]
File containing the energy threshold defining a real signal for each readout. If the parameter is set to CALDB, the default, the file is read from the calibration database.

enecutfile = CALDB [filename]
File containing criteria for rejecting events with a large difference between the top- and bottom-side energies in a layer If the parameter is set to CALDB, the default, the file is read from the calibration database.

(occurrenceid = -1) [integer]
If greater than zero, the task only expands this single occurrence.

(rejectbgo = no) [boolean]
Reject events (the default) for which BGO trigger occurred. (yes/[no])

(outcalfile = NONE) [filename]
Output a file containing the reconstruction information for each occurrence by detector side. This file is used is used for calibration and not usefull for science analysis. The default is to set this parameter to NONE.

(datamode = NONE) [string]
Substitute DATAMODE in place of event value (or NONE)

(skipreco = no) [boolean]
By default skip the reconstruction of READALL and CALMODE events.(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]
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).

EXAMPLES

1. Reconstruct HXI events using the default values of all hidden parameters. This option produces no extra output file.
hxievtid infile=HXI_SFF.fits outfile=HXI_output.fits remapfile=CALDB fluorefile=CALDB badpixfile=CALDB enecutfile=CALDB
2. Reconstruct HXI events and produce an extra output file.
hxievtid infile=HXI_SFF.fits outfile=HXI_output.fits remapfile=CALDB fluorefile=CALDB badpixfile=CALDB enecutfile=CALDB outcalfile="extra.fits" clobber=yes
3. Reconstruct HXI events for a single occurrence.
hxievtid infile=HXI_SFF.fits outfile=HXI_output.fits remapfile=CALDB fluorefile=CALDB badpixfile=CALDB enecutfile=CALDB occurrenceid=2 clobber=yes

SEE ALSO

hxisgdsff hxisgdpha sgdevtid gainfit

LAST MODIFIED

February 2016