NAME

USAGE

DESCRIPTION

'sxspha2pi' calculates and populates the PI column in the SXS event file. 'sxspha2pi' first derived an energy column, EPI and EPI2 (energy in eV), and after calculates the PI column(channel). By default the gain correction uses the PHA column that contains the telemetered values and the computed energy value is written in the EPI column. If the secondary events were corrected using the task 'sxsseccor', a new column containing a combination of the telemetered PHA values for primary events and corrected PHA values for the secondary events is present in the file. The name of the column is PHA2, if 'sxsseccor' is run with the default values. To use this column for the gain correction, users may specify the column name using the parameter 'secphacol'. The ouput of the gain calculation using the 'secphacol' is written in EPI2. NOTE: if the 'secphacol' is set to PHA, the EPI and EPI2 contains the same values. 'sxspha2pi' always calculates the PI value using the EPI2 column.
The EPI (or EPI2) is obtained by using the 'driftfile' derived with the 'sxsgain' task and the gain CALDB file. The gain CALDB file contains gain curves at three temperatures The 'driftfile' provides the relation of PHA versus temperature so that the calibration line is at the correct energy. The relation is computed with two methods average and fit and either result may be used in 'sxspha2pi' (see parameter 'method'). If the drift file is constructed using the calibration pixel (pixel 12), there is only one correction, for each method, that is applied to all pixels. A CALDB scale file may adjust the gain per pixel if specified in the parameter 'scalefile' and if 'scaleepi' is set to yes. If the drift file is constructed using the MXS sources or the Fe55 filter the corrections are for each individual pixel in the array.
'sxspha2pi' reads the 'driftfile' and for each event searches the appropriate correction in time, within a time interval defined by the parameter 'gapdt' and pixel if the driftfile is from the MXS of the FE55 filter. After read the energy, 'sxspha2pi' constructs using the gain table from CALDB curves of temperature versus energy using the event PHA value. Then 'sxspha2pi' reads the 'driftfile' and searches for the temperature, within a time interval defined by the parameter 'gapdt' around the time of the event and pixel if the driftfile is from the MXS of the FE55 filter. The temperature vs Energy table is interpolated to get the EPI corresponding to the temperature from the driftfile. The EPI (or EPI2) column is set to null if there is not corresponding entry in the drift file within the time interval of the event and pixel.. 'sxspha2pi' treats all the events as primary when calculating the EPI. The PI value is calculated as PI=floor((EPI2-0.5)/0.5 + 1.0 ) For SXS good events, the PI ranges between 0 and 32767 in channel where each channel is 0.5 eV. The PI is set to null if the EPI2 is null or the PI < 0. If the PI > 32767, PI is set to 32767. For SXS baseline event the PI ranges -16384 and 16383. If a baseline event is outside this range the PI is set to null.
The UPI column is calculated if 'calcupi' parameter is set to yes. This column is in energy (eV) derived using the gain file for a single temperature not corrected for the drift. The temperature is defined in the parameter 'tempidx' and by default is set to the value written in the TEMPIDX keyword of the 'driftfile'. For diagnostic purpose the PI calculation may be switched off by setting the 'calcpi' parameter to no, and only the UPI column is populated.

PARAMETERS

infile [filename]

Input SXS event file name.

outfile [filename]

Name of the output file name.

(calcupi = yes) [boolean]

Calculate UPI column ([yes]/no). If 'extend' is et to yes the value are written in a column named UPIE.

(calcpi = yes) [boolean]

Calculate PI column ([yes]/no).

(driftfile = CALDB) [filename]

Input file containing drift correction file. This is the output of sxsgaindrift.

(gainfile = CALDB) [filename]

Input file containing SXS energy scale (gain) coefficients, or CALDB.

(scalefile = CALDB) [filename]

Input file containing SXS gain adjustments for each individual pixels, or CALDB. This adjustment is only valid if the gain has been calculated using the pixel 12. There are two allowable formats for the scalefile. The first format has two columns, PIXEL and HP, and the scale factors are applied to the event grades as specified in the scalegrade parameter. The second format has three columns, PIXEL, HP, M, and L, giving the specific scale factors for each grade. The scalegrade parameter is ignored when the task is given a scalefile with the second format.

(tempidx = -1) [integer]

Input temperature index to use in the UPI calculation. If -1 use the temperature index in the 'driftfile'.

(pxphaoffset = 0.0) [float]

Average offset added to PHA values before applying the gain. A random offset is added to each PHA between -0.5+pxphaoffset and +0.5+pxphaoffset. So, when pxphaoffset=0.5, the random offset is between 0 and 1.

(secphacol= PHA) [string]

Input column name to use for the gain correction. The default is PHA containing the telemetered values. If the secondary were corrected (see task sxsseccor) a new PHA column is present in the file (default PHA2) and the user may specified this new column name to apply the gain.

(addepicol = EPI2) [string]

Output energy column name for EPI with secondary correction applied. The value is set to EPI2 and should not be changed. If 'extended' is set to yes, 'sxspha2pi' uses the value in the 'addpicol' as root name and add 'E'(e.g. EPI2E).

(method = FIT) [string]

Correction method (FIT or AVERAGE). If FIT, the TEMP_FIT column in the driftfile is used; if AVERAGE the TEMP_AVG column is used.

(scaleepi= no) [boolean]

Scale EPI for each pixel using the values in the CALDB file entered in the parameter scalefile (yes/[no]).

(scalegrade= 0) [string]

Grade to which the scaling factor per pixel is applied. By default the task applies the scaling factor only to grade 0. Other grades maybe be specified by a comma separated list, e.g. "0,1,2". This parameter is only used when the scalefile contains a single column (HP).

(itypecol = ITYPE) [string]

Column containing event grade in infile.

(extended = no) [boolean]

Use extended energy range (yes/[no]). If the parameter is set to yes, the output of the gain calculation is written in the EPIE and EPI2E columns and the channel is written in the column PIE. NOTE: This option should be used in conjunction with parameters 'binwidth', 'offset' and 'tlmax'. It is advised to use the values recommended in the Hitomi user guide or step by step guide

(binwidth = 1.0) [double]

PI bin width for extended energy range [eV].

(offset = 0.5) [double]

Offset for first PI for extended energy range [eV].

(tlmax = 32767) [int]

Maximum PI channel for extended energy range.

(gapdt = -1.) [double]

Time [s] between events to define a gap (or <0). Events must have entries appropriate to its pixel value in driftfile within this interval; otherwise, EPI and PI are set to their null values.

(ntemp = 3) [int]

Number of temperatures from gain file to use in interpolation. The energy at each of these temperatures is calculated from the PHA of the event, and used to derive the event energy by ntemp-point interpolation.

(writetemp = no) [boolean]

Write temperature used for each event to output event file (yes/[no]).

(extrap = no) [boolean]

Allow extrapolation when determining drift temperature (yes/[no]).

(randomize = yes) [boolean]

If randomize = 'yes', decimal randomization is applied to PHA (an integer) before applying the gain to obtain energy (a double).

(seed = 0) [integer]

Random number generator seed; uses system time for seed=0.

(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).

EXAMPLES

1. Assign PI for events in event_in.fits. Use the gain (energy scale) coefficients in CALDB and the drift file mxs.drift

      sxspha2pi event_in.fits event_out.fits driftfile=mxs.drift.

SEE ALSO

LAST MODIFIED