NAME

nucalcpi -- Calculate PI column values of NuSTAR event files

USAGE

nucalcpi infile hkfile outfile [parameter = < value >]

DESCRIPTION

'nucalcpi' calculates the Pulse Invariant (PI) values of NuSTAR event files. For each event the PI values are calculated taking into account the detector, its position on the detector ('RAWX', 'RAWY' columns), its grade ('GRADE' column) and for changes of the gain with temperature and time. Also, specific charge-loss corrections for multiple pixels events are applied. The computed values are stored in the PI column of the output file. The task also computes the PI values for the 3x3 array pixels below the software threshold and stores the result in the SURRPI column.

The gain coefficient values have been evaluated from ground calibration data at three fixed temperature of the detector and could be periodically updated using the results of the flight calibration data analysis. The gain information is stored in the NuSTAR calibration gain file which is included in the CALDB. The charge loss correction is applied to events with grades 1-8 using the information stored in the input CALDB Charge Loss Correction and Charge Loss Correction Filter files.

The PI calculation is the result of an interpolation on temperature and on time. First, for each event the two rows valid for the epochs closest to the time of the event are chosen. Then for each row, given the temperature associate to the event, the task performs a temperature interpolation of the gain coefficients between the two nearest temperatures, thus obtaining two sets of coefficients for two contiguous times. Finally, a second interpolation with respect to time between these two sets of coefficients is performed.

The temperature of each event is read from the input Housekeeping file (input parameter 'hkfile'). Optionally, by setting 'hkfile' to 'NONE', the temperature associated to all the events is read from the input parameter 'temperature'.

The unit of the PI column is set to 40 eV per channel.

PARAMETERS

infile [file name]
Name of the input FITS Event File.

outfile [file name]
Name of output FITS Event File.

hkfile [file name]
Name of the input Housekeeping FITS File or NONE.

(temperature=5) [real]
Temperature of the detector (Celsius). This parameter is used only if parameter 'hkfile' is set to NONE.

(gainfile=CALDB) [filename]
Name of the input FITS gain File. If set to CALDB (default), use the file in the Calibration Database.

(clcfile=CALDB) [filename]
Name of the input charge loss correction File. If set to CALDB (default), use the file in the Calibration Database.

(clcfilterfile=CALDB) [filename]
Name of the input charge loss correction filter File. If set to CALDB (default), use the file in the Calibration Database.

(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

  1. Calculate PI values for the input event file 'nu40060001001A_uf.evt'. The detector temperature associated to each event is read from the input file 'nu40060001001A.hk'. The results are written in the output event file 'nu40060001001A_out.evt'. 

     > nucalcpi infile=nu40060001001A_uf.evt outfile=nu40060001001A_out.evt
   hkfile=nu40060001001A_fpm.hk
  2. Calculate PI values for the input event file 'nu40060001001A_uf.evt'. The detector temperature associated to all the events is 3.5 Celsius degrees. The results are written in the output event file 'nu40060001001A_out.evt'. 

     > nucalcpi infile=nu40060001001A_uf.evt outfile=nu40060001001A_out.evt
   hkfile=NONE temperature=3.5

BUGS

SEE ALSO

LAST MODIFIED

March 2012