The sxsgain task calculates the time-dependent SXS 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 SXS 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 sxspha2pi 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 sxsgain 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 sxsgain 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, sxsgain 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 sxsgain 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 sxspha2pi to assign PI.
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 STATUS column for antico, electrical crosstalk, and recoil crosstalk flags if, respectively, 'ckant', 'ckctel', or 'ckctrec' parameters are set to yes. If 'ckrisetime=yes', events with RISE_TIME > 127 are likewise 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, sxsgain 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.
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 temperatures, as specified by the 'ntemp' parameter, in the gain calibration file.
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), 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 (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 sxspixgti task.
sxsgain infile=event_in.fits outfile=gain_out.fits
sxsgain infile=event_in.fits outfile=gain_out.fits broadening=5.0 fitwidth=no
sxsgain infile=event_in.fits outfile=gain_out.fits linetocorrect=Cuka calmethod=MXS gtifile=mxson13.gti