NAME

USAGE

DESCRIPTION

The rslgain task calculates the time-dependent Resolve energy gain correction by comparing the theoretical and observed energies of a calibration line or line complex. For each run of the task, only one such line or complex may be specified. The source of calibration X-rays may be specified as either the Resolve calibration pixel ('calmethod=Cal-pix'), the Modulated X-ray Source ('calmethod=MXS'), or the Filter Wheel Fe55 source ('calmethod=Fe55'). In the first case, only the calibration pixel (pixel 12) correction is computed, otherwise distinct corrections are computed for each pixel. The output may subsequently be utilized by the rslpha2pi task to assign photon PI and energy values. This task requires that the TIME, PHA, PIXEL, and STATUS columns in the input file are populated.

The rslgain task accumulates spectra from events that are consecutive in time with energy centered on the calibration feature, and compares each spectrum from the events with a theoretical model of the calibration feature profile. The calibration feature used by rslgain is specified by the parameter 'linetocorrect', and the names and energies of the features are contained in a calibration file specfied by the parameter 'linefitfile'. The calibration feature may be composed of many atomic or nuclear line components that are listed in the calibration file. Each calibration line component is assumed to have a Lorentzian profile.

The energy range for the spectra constructed from the event file, as well as from the theoretical profile, may be specified in two different ways. The default energy range for the spectra spans the smallest and largest line component energies for the selected line or line complex recorded in 'linefitfile', that is then expanded with the 'extraspread' parameter, i.e. the energy range is [E_min - extraspread : E_max + extraspread]. It is recommended that 'extraspread' be set to a value larger than the sum of the natural width of the calibration feature, the value of the 'broadening' parameter, and the magnitude of the expected energy shift. The lower and upper bounds of the energy range are determined in this manner if the 'startenergy' and 'stopenergy' parameters are, respectively, negative. Alternatively, the energy range bounds may be specified by setting the 'startenergy' and 'stopenergy' parameters. If these parameters are non-negative, rslgain uses those limits in accumulating the spectra. The theoretical profile may be convolved with a Gaussian having a FWHM given by the 'broadening' parameter.

The rslgain task proceeds in two steps for each spectrum. In the first step, the PHA shift of the spectrum with respect to the theoretical profile is derived, using both fitting and averaging methods. In the second step, these shifts are used to compute pixel temperatures that may subsequently be used by rslpha2pi to assign PI.

Step 1:

In order to fit PHA spectra, the spectrum energy grid is converted to a PHA mesh by applying a reverse lookup using the appropriate set of gain coefficients. Gain coefficients for each pixel, resolution grade (High, Mid, and Low, or H, M, and L respectively), and calibrated pixel temperature are contained in the gain CalDB file specifed by the parameter 'gainfile'. For the spectrum in a particular pixel, the gain corresponding to that pixel, the grade specified by the 'gaincoeff' parameter, and temperature corresponding the value of the 'tempidx' parameter, are used to define this PHA mesh and to compute the theoretical profile at each mesh point.

The task proceeds by first constructing spectra within the prescribed PHA range for groups of events consecutive in time and in the same pixel. Only high-resolution primary events, or alternatively high- and mid-resolution primaries (if 'usemp=yes') are considered. Events may be excluded from the fitting by independently checking the relevant STATUS columns for antico, electrical crosstalk 1, electrical crosstalk 2, and recoil crosstalk flags if, respectively, 'ckant', 'ckctel', 'ckctel2', or 'ckctrec' parameters are set to yes. If 'ckrisetime=yes', events with RISE_TIME > 127 are likewise excluded. Finally, if 'ckclip=yes', events with FLAG_CLIPPING set to true are excluded. If a GTI file (see below for the GTI file format) is specified by the 'gtifile' parameter, events outside of the GTI intervals are excluded as well. If 'calmethod' is set to MXS, this GTI file should only include times when the MXS mode corresponding to 'linetocorrect' is producing MXS events. For direct mode the options for 'linetocorrect' are CuKa, CuKb, CrKa, or CrKb; for indirect mode the options for 'linetocorrect' are AlKa, AlKb, MgKa, or MgKb. Spectra are not accumulated across successive GTI unless 'spangti=yes'.

The number of events in each spectrum is defined by the 'numevent' and 'minevent' parameters. The task initially accumulates spectra with a number of events up to 'numevent'. However, if a spectrum has fewer than 'minevent' points, then it is combined with the previous spectrum, if possible. Therefore, all spectra have between 'minevent' and numevent+minevent-1 events. To avoid accumulating spectra across large gaps in time, the group of points in the spectrum is truncated when the time interval between consecutive events exceeds the value of the 'gapdt' parameter. Adjacent spectra in time may share a percentage of their events based on the value of the 'grpoverlap' parameter that may vary between 0 and 100. If 'grpoverlap' is set to 0, consecutive spectra share no points in common; if set to 100 they share all points in common but one.

For each accumulated spectrum, rslgain fits the theoretical profile to the data and also derives binned and unbinned PHA averages. A least-squares method is used in the fitting. The fitted parameters are energy shift, scaling factor, background (unless the 'background' parameter is set to NONE), and convolution width (if 'fitwidth=yes'). The background is fitted with a constant value if 'background' is set to CONST, and a linear function if set to SLOPE. The unbinned average PHA is the sum of the PHA in the spectrum divided by the number of events in the spectrum. The binned average PHA is the weighted average, which is constructed by summing the product of the PHA and number of events in each bin, over the whole spectrum, and then dividing by the total number of events in the spectrum. The fitted gain correction is computed from the fitted shift relative to the theoretical line profile. The binned average gain correction is computed from the difference between the spectrum and theoretical profile averages.

Step 2:

Once the fitting is completed for a spectrum in some pixel, the fitted and average pixel temperatures are determined and written to the output gain file specifed by the 'outfile' parameter, as follows. The gain coefficients contained in the gain calibration file specified by parameter 'gainfile' for this pixel and the grade specified by the 'gaincoeff' parameter, are used to build a temperature vs. energy table for the average PHA derived from the binned average, or from the fitting. The corresponding pixel temperatures at the average energy of the input calibration feature are then obtained using an n-point interpolation method, where n is the number of temperature-specific gain curves in 'gainfile' to be used, as specified by the 'ntemp' parameter.

The default values for the parameters used in the bisection method used in the least-squares fitting ('minwidth0', 'maxitcycle', 'r2tol', 'searchstepshift', 'maxdshift', 'bisectolshift', 'searchstepwidth', 'maxdwidth', 'bisectolwidth', and 'minwidth') need not be changed since these parameters are carefully optimized.

The output file has two extensions. The GRID_PROFILE extension contains the energies and amplitudes at each energy of the theoretical profile used in the fitting procedure, including any convolution applied based on the 'broadening' parameter. The DRIFT_ENERGY extension records the fitting results for each spectrum in the following columns: TIME (midpoint of the time interval over which the spectrum is collected if the 'useavgtime' parameter is set to no, or the mean of the times for the events used in the spectrum if if the 'useavgtime' parameter is set to yes), PIXEL, COR_FIT (energy correction factor from spectrum fit), COR_AVE (energy correction factor from spectrum average), CHISQ (reduced chi-squared of the fit), AVGUNBIN (average energy of events in spectrum prior to binning), AVGBIN (weighted spectrum average energy), AVGFIT (average energy from fit), SHIFT (fitted energy shift), SCALE (fitted vertical scaling factor), BGRND (fitted background), WIDTH (if 'fitwidth=no', same as broadening parameter; if 'fitwidth=yes', fitted width), TELAPSE (difference between times of the first and last event in the spectrum), EXPOSURE (sum calculated using the GTI), NEVENT (total number of events collected for this spectrum), BINMESH (array containing the count spectrum energy bins), SPECTRUM (array containing the observed binned count spectrum), FITPROF (array containing theoretical profile with fitted parameters applied), TEMP_FIT (temperature derived from fitted PHA, using the AVGFIT column), and TEMP_AVE (temperature derived from average PHA, using the AVGBIN column). If the 'calcerr' parameter is set to yes, one-sigma errors for the SHIFT and WIDTH are calculated. The errors are calculated using chi-squared and maximum-likelihood methods, and output in the columns SIGSHCHI2, SIGWDCHI2, SIGWDLIKE, and SIGWDLIKE, respectively. If the 'writeerrfunc' parameter is set, the chi-squared and likelihood calculated values are output in the arrays SHCHI2, SHLIKE, WDCHI2, and WDLIKE. The number of output values in these shift and width arrays are specified in the 'nerrshift' and 'nerrwidth' parameters, respectively. The extrema of these error arrays are specified by the parameters 'shifterrfac' and 'widtherrfac'. If W is the quadrature of the fitted width and the natural width, the shift error arrays range from SHIFT - (shifterrfac*W) to SHIFT + (shifterrfac*W); and, the width error arrays range from [WIDTH - (W/widtherrfac)] to [WIDTH + (W*widtherrfac)].

Two formats are supported for the GTI file. The first format contains up to 37 extensions: 1 general GTI and 36 pixel-dependent GTI. The DETNAM keyword for the general GTI must be PIXEL, and the DETNAM keyword values for the pixel-dependent GTI are PIXNN where "NN" is the pixel number, e.g. PIX04 for pixel 4. In this format, all extensions must contain columns START and STOP which define the GTI. The second format may have up to two extensions: 1 general GTI with START and STOP columns, and 1 pixel-dependent extension with columns START, STOP, and PIXEL. In the second format the DETNAM keyword is set to PIXEL for both extensions. If the input GTI has a single GTI extension with no DETNAM keyword defined, it is treated as a general GTI. If the events need to be filtered using multiple general or pixel-dependent GTI files, they must first be merged into a single GTI file using the rslpixgti task.

PARAMETERS

infile [filename]

Input event file name.

outfile [filename]

Output drift correction (gain history) file name.

(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 = NOM) [string]

Input temperature index for selecting gain function to convert energy to PHA profiles during fitting. If set to NOM, the gain function corresponding to the middle (nominal) temperature will be selected.

(gaincoeff = H) [string H|M|L]

Type of gain coefficients to use, H for high-resolution, M for mid-resolution, and L for low-resolution.

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

Input CALDB file containing parameters of the Lorentzian components used to construct the theoretical line profile. If the parameter is set to CALDB, the file is read from the CalDB.

(linetocorrect = MnKa) [string MnKa|MnKb|CuKa|CuKb|CrKa|CrKb|AlKa|AlKb|MgKa|MgKb]

Calibration line to use for the energy correction. Features in the CalDB file relevant to Resolve are the following: Mnka and Mnkb (from the calpixel or Fe55 filter wheel source); Cuka, Cukb, Crka, and Crkb (MXS direct mode), Alka, Alkb, Mgka, and Mgkb (MXS indirect mode).

(itypecol = ITYPE) [string]

Column name where the event grade type is stored.

(ntemp = 3) [integer]

Number of temperatures represented in 'gainfile' to use in (ntemp-point) interpolation. This must be greater than 1, but not exceed the total number represented in 'gainfile'.

(calmethod = Fe55) [string Cal-pix|MXS|Fe55]

If 'calmethod' is set to Cal-pix, the energy correction is calculated for the calibration pixel (pixel 12) only. If 'calmethod' is set to MXS, the energy correction is calculated for all pixels, but using only events detected during MXS operation as specified by the 'gtifile' parameter. If 'calmethod' is set to Fe55, all pixels and all relevant events are used.

(useavgtime = no) [boolean yes|no]

If 'useavgtime' is set to yes, the time associated with a fit to an accumulated spectra is calculated as the mean of the arrival times for the events that make up the spectrum. If 'useavgtime' is set to no, the time associated with a fit to an accumulated spectra is calculated as the average of the minimum and maximum for the events that make up the spectrum.

(numevent = 1000) [integer]

Number of events collected for each spectrum used to calculate a single gain correction.

(minevent = 200) [integer]

Minimum number of events required for a spectrum. If the length of a group is less than 'minevent', those points are appended to the previous group for processing, if possible.

(gtifile = NONE) [filename NONE|file name]

Input GTI file name containing the time intervals to use for filtering events in calculating the gain. Set to NONE to use the entire input file.

(gapdt = -1.) [double]

The upper limit to the time interval between two consecutive events in the same spectrum used in fitting. Two consecutive events separated in time by more than this amount are assigned to different groups. If 'gapdt=-1' no limit is imposed.

(grpoverlap = 50.) [double]

The percentage overlap between adjacent groups. For 'grpoverlap=100', adjacent groups are shifted by one event. For 'grpoverlap=0', adjacent groups are independent and share no events.

(startenergy = -1.) [double]

Lower limit of energy range [eV] over which the spectra are collected. If 'startenergy' is negative, the first energy is automatically determined by the lowest energy in the file specified by 'linefitfile' for the selected calibration feature, adjusted by the 'extraspread' parameter.

(stopenergy = -1.) [double]

Upper limit of energy range [eV] over which the spectra are collected. If 'stopenergy' is negative, the last energy is automatically determined by the highest energy in the file specified by 'linefitfile' for the selected calibration feature, adjusted by the 'extraspread' parameter.

(extraspread = 10.0) [double]

Energy [eV] by which the energy range is extended on either side, beyond the lowest and highest energies in the file specified by 'linefitfile', for the selected calibration feature. This parameter may be overridden by the 'startenergy' and 'stopenergy' parameters.

(pxphaoffset = 0.0) [double]

The PHA bins used to construct the fitting spectra are shifted by this amount. If the PHA value in 'gainfile' represents the left boundary of the PHA bin, then 'pxphaoffset' should be 0; if instead it represents the center of the bin, 'pxphaoffset' should be 0.5.

(broadening = 1.0) [double]

FWHM of the Gaussian [eV] used to initially broaden the theoretical line profile. If 'fitwidth' is set to no, the profile width is fixed at this value.

(gridprofile = no) [boolean yes|no]

If 'gridprofile' is set to yes, only the theoretical profile, including any convolution due to the broadening parameter is calculated and output; no fitting is conducted.

(fitwidth = yes) [boolean yes|no]

If 'fitwidth' is set to yes, fit the width of each spectrum in addition to the energy shift.

(background = CONST) [string NONE|CONST|SLOPE]

Fitted background type. The background is assumed constant with PHA if set to 'CONST' and a linear function of PHA if set to 'SLOPE'. If 'background' is set to NONE no background is included in the gain fitting.

(spangti = yes) [boolean yes|no]

If 'spangti' is set to yes, events in different time intervals in 'gtifile' may be collected in the same spectrum to be fitted. If 'spangti' is set to no, groups of events used to construct the spectra must be from the same GTI. This parameter is ignored if 'gtifile' is set to NONE.

(usemp = no) [boolean yes|no]

If 'usemp' is set to no, only high-resolution primaries are included in the fitted spectra. If 'usemp=yes', mid-resolution primaries are also included.

(ckrisetime = yes) [boolean yes|no]

If 'ckrisetime' is set to yes, events with RISE_TIME > 127 are not used in fitting.

(ckclip = yes) [boolean yes|no]

If 'ckclip' is set to yes, events with FLAG_CLIPPING set to true are not used in fitting.

(calcerr = no) [boolean yes|no]

If 'calcerr=yes', SHIFT and WIDTH uncertainties are computed.

(writeerrfunc = no) [boolean yes|no]

If 'writeerrfunc=yes', the output includes the array of chi-squared and likelihood values calculated for SHIFT and WIDTH.

(ckant = yes) [boolean yes|no]

If 'ckant' is set to yes, events identified as coincident with antico events according to the STATUS column are not used in fitting.

(ckctrec = yes) [boolean yes|no]

If 'ckctrec' is set to yes, events identified as recoil crosstalk according to the STATUS column are not used in fitting.

(ckctel = yes) [boolean yes|no]

If 'ckctel' is set to yes, events identified as electrical crosstalk 1 according to the STATUS column are not used in fitting.

(ckctel2 = no) [boolean yes|no]

If 'ckctel2' is set to yes, events identified as electrical crosstalk 2 according to the STATUS column are not used in fitting.

(extrap = no) [boolean yes|no]

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

(avgwinrad = 30.) [double]

Radius of interval (in units of 'binwidth') used only to update the initial shift estimate prior to fitting. This is not used in calculating the average results.

(minwidth0 = 8.0) [double]

Smallest width (in units of 'binwidth') allowed as the initial value in width fitting. This parameter provides a lower limit to the initial estimate of the width as computed by the fitting algorithm. Its value must be greater than zero.

(maxitcycle = 5) [integer]

Maximum number of fitting iterations.

(r2tol = 0.001) [double]

Convergence criterion for R-squared, the coefficient of determination for least-squares fitting. Once R-squared changes by less than this amount between fitting iterations, the procedure is finished.

(searchstepshift = 2.0) [double]

Step size (in units of 'binwidth') used when searching for best-fit energy shift in either direction from the initial shift estimate based on the spectrum average. The final shift is obtained using the bisection method.

(maxdshift = 10.0) [double]

Largest allowed deviation (in units of 'binwidth') from initial estimate of energy shift. If no solutions are found within this deviation at smaller or larger shifts from the initial estimate, the fitting procedure fails.

(bisectolshift = 0.001) [double]

When the bisection method determines the energy shift to within this amount (in units of 'binwidth'), the fitting procedure is completed.

(searchstepwidth = 5.0) [double]

Step size (in units of 'binwidth') used when searching for best-fit convolution width in either direction from the initial width estimate based on the difference between the profile and spectrum statistical variances. The final width is obtained using the bisection method.

(maxdwidth = 10.) [double]

Largest allowed deviation (in units of 'binwidth') from initial estimate of convolution width. If no solutions are found within this deviation at smaller or larger widths from the initial estimate, the fitting procedure fails.

(bisectolwidth = 0.001) [double]

When the bisection method determines the convolution width to within this amount (in units of 'binwidth'), the fitting procedure is completed.

(minwidth = 0.5) [double]

Since the least-squares fitting function is undefined when the width is zero, one must define a minimum allowed fitted width. If the fitting routine attempts to fit a width smaller than this value (in units of 'binwidth'), the fitting procedure fails.

(nerrshift = 100) [integer]

Number of shift values used in uncertainty calculations.

(nerrwidth = 100) [integer]

Number of width values used in uncertainty calculations.

(shifterrfac = 3.0) [double]

Factor for determining the range of the shift error arrays.

(widtherrfac = 4.0) [double]

Factor for determining the range of the width error arrays.

(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. Calculate the gain for XRISM Resovle event file (OBSID 100050020) based on fitting calpixel events with a line profile based on the theoretical Mn K-alpha profile convolved with a Gaussian with width determined by fitting.

   rslgain infile=xa100050020rsl_p0px1010_uf.evt outfile=gain_out.fits

2. Calculate the gain for XRISM Resovle event file (OBSID 100050020) based on fitting calpixel events with a line profile based on the theoretical Mn K-alpha profile convolved with a Gaussian of fixed 5 eV FWHM.

   rslgain infile=xa100050020rsl_p0px1010_uf.evt outfile=gain_out.fits broadening=5.0 fitwidth=no

3. Calculate the gain for XRISM Resovle event file (OBSID 100050020) based on fitting MXS events with a line profile based on the theoretical Cu K-alpha profile using a GTI file indicating when the direct MXS sources were on (mxson13.gti).

   rslgain infile=xa100050020rsl_p0px1010_uf.evt outfile=gain_out.fits linetocorrect=Cuka calmethod=MXS gtifile=mxson13.gti

SEE ALSO

LAST MODIFIED