'sxsgain' calculates time-dependent SXS energy gain corrections by comparing the theoretical and observed energies of a calibration line or line complex. For each run of the task, only one line may be specified to calculate the gain correction (see parameter 'linetocorrect'). 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 energy and PI values. This task requires that the TIME, PHA, and STATUS columns in the input file are populated.
'sxsgain' 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' as a string, and the names and energies of the features are specified in a calibration file (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 is assumed to be Lorentzian.
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. (1) The default energy range for the spectra is the smallest and largest energies of the line components, and expanded with the 'extraspread' parameter, i.e. [E_min - extraspread : E_max + extraspread]. It is recommended to set 'extraspread' 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. (2) Alternatively, the energy range may be specified by setting the 'startenergy' and 'stopenergy' parameters. If these parameters are non-negative 'sxsgain' uses their values to accumulate the spectra, instead of the range derived using the 'extraspread' setting. The profile may be convolved with a Gaussian having the FWHM given by the 'broadening' parameter.
'sxsgain' 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.
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 are contained in the gain CALDB file (see parameter 'gainfile') for each pixel, resolution grade -- (H)igh, (M)id, and L(ow), and pixel temperature. For a given spectrum in a pixel, the gain corresponding to that pixel, grade given by the 'gaincoeff' parameter, and temperature given by the 'tempidx' parameter are used to define this mesh and to evaluate the theoretical profile on the PHA mesh.
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 risetime>127 are likewise excluded. If a GTI file (see below GTI 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 should only include times when the MXS mode corresponding to 'linetocorrect' (direct mode for 'linetocorrect=CuKa, CuKb, CrKa, or CrKb'; indirect mode for 'linetocorrect=AlKa, AlKb, MgKa, or MgKb') are producing MXS events. Spectra are not accumulated across GTI intervals unless 'spangti=yes'.
The number of events in each spectrum is defined by the 'numevent' and 'minevent' parameters. The task accumulates spectra with a number of events between 'minevent' and 'numevent'. However, if a spectrum has fewer than 'minevent' points, then it is combined with the previous spectrum if possible. Therefore all spectra have a size between 'minevent' and ('numevent+minevent-1'). To avoid having spectra accumulated over large gaps in time, the group of points in the spectrum is truncated when the time interval between consecutive events is greater than the 'gapdt' parameter. Adjacent spectra in time may share a percentage of their points based on the 'grpoverlap' parameter that may vary between 0 and 100. If 'grpoverlap' is set to 0, the 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 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 fit with a constant value if 'background' is set to CONSTANT, and a power-law 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 derived by summing, over bins in the spectrum, the product of the PHA and number of events per bin, and then dividing by the total number of events in the spectrum. The fitted gain correction is computed from the fitted shift with respect to the theoretical line profile. The binned average gain correction is computed from the difference between the profile and spectrum averages.
Step 2: Once the fitting is completed for a spectrum in a pixel, the fitted and average pixel temperatures are determined, and written to the output gain file. The gain coefficients contained in the gain CALDB file (parameter 'gainfile') for this pixel and the grade given 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 in the gainfile to be used (see 'ntemp' parameter).
The default values for the parameters used in the fitting method ('minwidth0', 'maxitcycle', 'r2tol', 'searchstepshift', 'maxdshift', 'bisectolshift', 'searchstepwidth', 'maxdwidth', 'bisectolwidth', and 'minwidth') should not need to change since already optimized.
The output file has two extensions. One extension, GRID_PROFILE, contains the energies and amplitudes of the theoretical profile used in the fitting procedure, including any convolution from the 'broadening' parameter. The other extension, DRIFT_ENERGY, reports the fitting results for each spectra 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 first and last event in 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; AVGFIT column), TEMP_AVE (temperature derived from average PHA; AVGBIN column). If the 'calcerr' parameter is set to 'yes', one-sigma errors for the SHIFT and WIDTH are calculated. The errors are calculated with chi-squared and maximum-likelihood methods and output in the columns SIGSHCHI2, SIGWDCHI2, SIGWDLIKE and SIGWDLIKE respectively. If 'writeerrfunc' parameter is set, the chi-squared and likelihood calculated valued are output in the arrays SHCHI2, SHLIKE, WDCHI2 and WDLIKE. The numbers of values output in these arrays are specified in the 'nerrshift' and 'nerrwidth' parameters, respectively.
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 GTIs 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'.
1. Calculate the gain based on fitting cal-pixel events with a line profile based on the theoretical Mn K-alpha profile convolved with a Gaussian with width determined by fitting.
sxsgain infile=event_in.fits outfile=gain_out.fits
2. Calculate the gain based on fitting cal-pixel events with a line profile based on the theoretical Mn K-alpha profile convolved with a Gaussian of fixed 5 eV FWHM.
sxsgain infile=event_in.fits outfile=gain_out.fits broadening=5.0 fitwidth=no
3. Calculate the gain 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 were on, mxson13.gti.
sxsgain infile=event_in.fits outfile=gain_out.fits linetocorrect=Cuka calmethod=MXS gtifile=mxson13.gti