NAME

USAGE

DESCRIPTION

The rslpha2pi task calculates and populates the PI column in a XRISM Resolve event file. This is executed by applying the data in the CalDB gain coefficients file that relates PHA to energy for multiple pixel temperatures, and the drift (or gain history) file created by the rslgain 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 rslgain 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 rslseccor, the PHA2 column records the corrected value of PHA and these corrected values are used to assign PI for the setting 'secphacol=PHA2'.

For each event, rslpha2pi derives a temperature based on the event time and the entries in the drift file, using separate temperatures for each 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 coefficients CalDB file ('gainfile'). To assure the accuracy of the energy used for gain calibration, quadratic interpolation is used to calculate the energy, and thus the EPI (or EPI2) value, corresponding to the temperature derived from the 'driftfile' parameter. If the 'ntemp' parameter is greater than 3, the three gain file temperatures closest to the event-time temperature are used. The EPI, EPI2, PI, and TEMP (created if 'writetemp=yes') column values for this event are 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 - offset)/binwidth) + 1.0) where 'offset=0.5' and 'binwidth=0.5' when default values are used. PI for Resolve pixel events ranges from 0 to 59999, 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 > 59999, PI is set to 59999. For Resolve 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 [filename]

Input Resolve event file name.

outfile [filename]

Output Resolve event file name.

(calcupi = yes) [boolean yes|no]

If 'calcupi=yes', the UPI column is calculated.

(calcpi = yes) [boolean yes|no]

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

(driftfile) [filename]

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

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

Input file containing Resolve 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.

(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=no', 'pxphaoffset' is added to each PHA value before application of the gain. If 'randomize=yes', a random offset between -0.5+pxphaoffset and +0.5+pxphaoffset is added. For example, when 'pxphaoffset=0.5' the random offset is between 0 and 1.

(secphacol = PHA2) [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 rslseccor.

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

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

(itypecol = ITYPE) [string]

Column containing event grade in 'infile'.

(binwidth = 0.5) [double]

PI channel bin width [eV].

(offset = 0.5) [double]

Offset for first PI [eV].

(tlmax = 59999) [integer]

Maximum PI channel (default corresponds to 30 keV).

(gapdt = -1.) [double]

Time interval used to define a window around events where the file specifed by 'driftfile' is not applicable. If there are no entries for the appropriate pixel with times within this interval ('gapdt') relative to the event time, then EPI, EPI2, PI and TEMP (created if 'writetemp=yes') 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. In practice, no more than three are used.

(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 = 2) [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 the event file from OBSID 100050020. Use the gain (energy scale) coefficients in the CalDB and the gain history file from the same observation.

   rslpha2pi infile=xa100050020rsl_p0px1010_uf.evt outfile=event_out.fits gainfile=CALDB driftfile=xa100050020rsl_010_pxcal.ghf

SEE ALSO

LAST MODIFIED