NAME

USAGE

DESCRIPTION

The sxspha2pi task calculates and populates the PI column in an SXS event file. This is executed by applying the data in the CALDB gain coefficients file that relates PHA to energy for three pixel temperatures, and the drift (or gain history) file created by the sxsgain task that contains the pixel temperature as a function of time (for the calibration pixel, or for all pixels, depending on the calibration method). The drift file includes temperatures derived by sxsgain from both fitted and average gain shifts, either of which may be utilized based on the setting of the 'method' parameter.

The task applies these corrections to the telemetered values in the PHA column to derive the EPI energy column [eV], and to the values in the column specified in the 'secphacol' parameter to derive the EPI2 energy column in eV (i.e., EPI2=EPI when 'secphacol=PHA'). The PI column (channel) is derived from EPI2. If the secondary grade events were corrected by the task sxsseccor, a new column with name PHA2 is present in the file, and these corrected values may be used to assign PI by setting 'secphacol=PHA2'.

If the drift file is constructed using the calibration pixel (pixel 12), a single correction is applied to all pixels. In this case, a CALDB scale file specified by the parameter 'scalefile' may be applied to adjust the gain per pixel by setting the 'scaleepi' parameter to yes. If the drift file is constructed using the MXS or the Filter Wheel Fe55 source, separate corrections are generated for each individual pixel in the array.

For each event, sxspha2pi derives a temperature based on the event time and the entries in the drift file, accounting for pixel if 'driftfile' was produced using the MXS or Filter Wheel Fe55 data. A temperature vs. energy table is then derived for the PHA of the event from the data in the gain coefficient CALDB file. By means of interpolation, the energy, and thus the EPI (or EPI2) value, corresponding to the temperature derived from the 'driftfile' parameter is then calculated. The EPI (or EPI2) column value for this event is set to NULL if there is no corresponding entry in the drift file for the relevant pixel within a time window relative to the event time determined by the 'gapdt' parameter.

The PI value is calculated from the equation PI=floor(((EPI2 - 0.5)/0.5) + 1.0). PI for SXS pixel events ranges from 0 to 32767, where the width for each channel is 0.5 eV. The PI value is set to NULL if EPI2 is NULL or if its calculated value is <0. If PI > 32767, PI is set to 32767. For SXS baseline events, the PI value ranges between -16384 and 16383. If a calculated baseline event PI falls outside this range, its PI value is set to NULL.

The UPI (uncorrected energy in eV) column is calculated if the 'calcupi' parameter is set to yes. This column is derived using the gain file for a single temperature defined by the parameter 'tempidx', and is not corrected for drift. By default 'tempidx' is set to -1 and the value of the TEMPIDX keyword in the 'driftfile' header is used. For diagnostic purposes, the PI calculation may be switched off by setting the 'calcpi' parameter to no, in which case only the UPI column is populated.

PARAMETERS

infile = sff_in.evt [filename]

Input SXS event file name.

outfile = sff_out.evt [filename]

Output SXS event file name.

(calcupi = yes) [boolean yes|no]

If 'calcupi=yes', the UPI column is calculated. If 'extended=yes', extended values are also calculated and written to a column named UPIE.

(calcpi = yes) [boolean yes|no]

If 'caclpi=yes', the PI column is calculated.

(driftfile = drift.fits) [filename]

Input drift correction (gain history) file created by the sxsgain task.

(gainfile = CALDB) [filename CALDB|file name]

Input file containing SXS gain coefficients for each pixel and resolution grade, and as a function of pixel temperature. If the parameter is set to CALDB, the file is read from the calibration database, CalDB.

(scalefile = CALDB) [filename CALDB|file name]

Input file containing SXS gain adjustments for each individual pixel. This adjustment is only valid if the gain correction has been calculated using the calpixel (pixel 12). There are two allowable formats for 'scalefile'. In the first format the file has two columns, PIXEL and HP, and the scale factors are applied to the event grades that are specified in the 'scalegrade' parameter. In the second format the file has four columns, PIXEL, HP, M, and L. In this case, scale factors are explicitly given in the column entries for each grade and the 'scalegrade' parameter is ignored. If the parameter is set to CALDB, the file is read from the CalDB.

(tempidx = -1) [integer]

Input temperature index to use in the UPI calculation. If 'tempidx=-1', the value of the TEMPIDX keyword in the 'driftfile' header is used.

(pxphaoffset = 0.0) [double]

Average offset added to PHA values before applying the gain, if 'randomize=yes'. A random offset that lies between -0.5+pxphaoffset and +0.5+pxphaoffset is added to each PHA value. For example, when pxphaoffset=0.5, the random offset is between 0 and 1.

(secphacol = PHA) [string]

Name of the column used to calculate EPI2. To account for corrections to secondary event PHA values, this should be set to the name of the column (PHA2, by default) populated by the task sxsseccor.

(addepicol = EPI2) [string]

Output energy column name for EPI as calculated using the PHA column specified by 'secphacol', that includes PHA correction to secondary events (if any). This parameter value is set to EPI2 and should not be changed. EPI2=EPI if secphacol = PHA (no secondary correction). If 'extended' is set to yes, sxspha2pi populates an extended energy column with name formed by appending an "E" to 'addepicol' (e.g., EPI2E).

(method = FIT) [string FIT|AVERAGE]

Specifies the column to use from 'driftfile' in applying the drift correction. If 'method=FIT', the TEMP_FIT column is used, if 'method=AVERAGE', the TEMP_AVE column is used.

(scaleepi = no) [boolean yes|no]

If 'scaleepi=yes', the scale file specified by the parameter 'scalefile' is used to adjust the gain per pixel.

(scalegrade = 0) [string]

Grade(s) (values in input file column specifed by the 'itypecol' parameter) to apply the scaling factor per pixel to. Multiple grades maybe be specified by a comma-separated list (e.g., 'scalegrade=0,1,2'). This parameter is used only when the 'scalefile' contains two columns (PIXEL and HP). If the 'scalefile' contains four columns, the scaling factors in the row entries for each grade are used.

(itypecol = ITYPE) [string]

Column containing event grade in 'infile'.

(extended = no) [boolean yes|no]

If set to yes, extended range energy and pulse invariant values are calculated and written in the EPIE, EPI2E, and PIE columns of the output file. The 'extended=yes' option is used in conjunction with parameters 'binwidth', 'offset', and 'tlmax'.

(binwidth = 1.0) [double]

PI bin width for extended energy range [eV].

(offset = 1.0) [double]

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

(tlmax = 32767) [integer]

Maximum PI channel for the extended energy range.

(gapdt = -1.) [double]

Time interval used to define a window around events where the file specifed by 'driftfile' is not applicable (no entries for the appropriate pixel with times within this interval relative to the event time); and, in which case, EPI and PI are set to their null values. If the value of this parameter is <0, this check is skipped.

(ntemp = 3) [integer]

Number of temperatures represented in 'gainfile' to use in (ntemp-point) interpolation. This must not exceed the total number in the file.

(writetemp = no) [boolean yes|no]

If 'writetemp=yes', the pixel temperature used to assign energy for each event is written to the output event file.

(extrap = no) [boolean yes|no]

If 'extrap=yes', extrapolation is allowed when calculating temperature.

(randomize = yes) [boolean yes|no]

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

(seed = 0) [integer]

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

(buffer = -1) [integer -1|0|N]

Rows to buffer (-1=auto, 0=none, N>0=numrows).

(clobber = no) [boolean yes|no]

Overwrites the existing output file if set to yes.

(chatter = 1) [integer 0|1|2|3]

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 DEFAULT|NONE|file name]

Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]

Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]

Records tool parameters in HISTORY.

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