nucalcpha help file

NAME

nucalcpha -- Correct energy, calculate PHAS and assign event grades for NuSTAR event files.

USAGE

nucalcpha infile outfile [parameter = < value >]

DESCRIPTION

'nucalcpha' processes the NuSTAR event files to correct energies, reconstruct events, calculate PHAS values and assign to each event a grade.

For each event, the telemetry contains nine charge values, stored in the columns POSTPHAS and PREPHAS, corresponding to an array of 3x3 pixels, the central pixel and eight surrounding pixels. This task reads the nine elements of the POSTPHAS and PREPHAS columns and applies various corrections necessary to calibrate the energy of the events and writes the result in the PHAS column of the output file. The algorithm used to calculate the PHAS column is described below (steps 1-5).

The task also assign a grade value to each event (GRADE column of the output file). The grades are assigned following a charge pattern definition stored in the CALDB grade file (parameter 'gradefile'). The output event file contains calibrated 'PHAS', 'GRADE' and 'SWTRIG' columns. Optionally, the columns 'RAWPHAS', 'OFFPHAS' and 'TRPHAS' are also stored in the output file by setting the paramter 'cleancols=no'.

The algorithm used is summarized below.

For each event (3x3 pixels array) the task applies the following processing steps: 1) Computation of RAWPHAS (9 dimensional vector):

RAWPHAS[9] = POSTPHAS[9] - PREPHAS[9]

2) Offset correction, i.e. computation of 'OFFPHAS' (9 dimensional vector):

OFFPHAS[9] = RAWPHAS[9] - OFFSET[9]

where the 9 values of OFFSET[9] are read from the input CAP_OFFSET file and are dependent on:
- the coordinates (RAWX, RAWY) of the pixels (3X3 array)
- the capacitor number (S_CAP column) of the event
- the detector (DET_ID column)

3) Time of rise correction, i.e. computation of 'TRPHAS' (9 dimensional vector):

TRPHAS[9] = OFFPHAS[9] * (1+(NUMRISE/DENRISE)*TIMERISE[9])

where NUMRISE, DENRISE are read from the input event file. The 9 values of TIMERISE[9] are read by default from the input PHAPAR file and are dependent on:
- the coordinates (RAWX, RAWY) of the pixels (3X3 array)
- the detector (DET_ID column)

If the parameter 'phaparfile' is set to 'NONE', the 9 values are provided in input to the task through the specific parameter 'timerise' (default=0.0016).

4) Common mode correction, i.e. computation of 'PHAS' (9 dimensional vector):

4a) exclusion of the M pixels located out of the detector or falling on bad/hot pixels

4b) selection of the N pixels ("E+") with TRPHAS >= 'EVTTHR[9]' (not including the M pixels defined in point 4a)

4c) selection of the 9-N-M pixels ("E-") with TRPHAS < 'EVTTHR[9]'

The 9 values of EVTTHR[9] are read by default from the input PHAPAR file and are dependent on:
- the coordinates (RAWX, RAWY) of the pixels (3X3 array)
- the detector (DET_ID column)

If the parameter 'phaparfile' is set to 'NONE', the 9 values are provided in input to the task through the specific parameter 'evtthr' (default=55).

4d) calculation of the mean of the pixels with TRPHAS < 'EVTTHR[9]':
< E- >=(&sum E-)/(9-N-M)

4e) computation of PHAS (9 dim. vector) for the N pixels "E+":
PHAS[9] = TRPHAS[9] - < E->

4f) computation of PHAS (9 dim. vector) for the 9-N-M pixels "E-":
PHAS[9] = TRPHAS[9]

4g) setting to zero PHAS values for the M pixels out of detector::
PHAS[9] = 0

5) computation of 'SWTRIG' column (9 dimensional vector):

SWTRIG[9] = 1 for pixels with TRPHAS >= 'EVTTHR[9]'

SWTRIG[9] = 0 for pixels with TRPHAS < 'EVTTHR[9]'

6) grade classification, i.e. computation of 'GRADE':

reconstruction of the event split topology following the classification defined in the input GRADE file.

PARAMETERS

infile [file name]: Name of the input FITS event file.
outfile [file name]: Name of output FITS event file.
(offsetfile=CALDB) [filename]: Name of the input FITS CAP_OFFSET file. If set to CALDB (default), use the file in the Calibration Database.
(gradefile=CALDB) [file name]: Name of the input FITS GRADE file. If set to CALDB (default), use the file in the Calibration Database.
(phaparfile=CALDB) [file name]: Name of the input FITS PHAPAR file. If set to CALDB (default), use the file in the Calibration Database. If set to NONE, the 'evtthr' and 'timerise' input parameters are used.
(evtthr = 55) [integer]: Event software threshold (used only if phaparfile=NONE).
(timerise = 0.0016) [real]: Time of rise correction coefficient (used only if phaparfile=NONE).
(cleancols=no) [boolean]: If set to yes, delete the temporary columns 'RAWPHAS', 'OFFPHAS', 'TRPHAS', and 'PHAS' in the output FITS event file.
(clobber=no) [boolean]: If set to yes, overwrite the output file.
(history=yes) [boolean]: If set to yes, write parameter values and other information in HISTORY blocks.
(chatter = 2) [integer]: Chatter Level (min=0, max=5).

EXAMPLES

Calculate PHAS and GRADE values for the event file 'nu40060001001A_uf.evt'. The values of the event software threshold , the time of rise correction coefficients, the capacitor offset values and the GRADE classification are read from the specific CALDB files. The results are written in the output event file 'nu40060001001A_out.evt'.
```
 > nucalcpha infile=nu40060001001A_uf.evt outfile=nu40060001001A_out.evt
```

BUGS

LAST MODIFIED

March 2012