'ahgainfit' calculates time-dependent 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'). 'ahgainfit' is a general task that is used directly in the scripts 'sxigainfit', 'hxigainfit', 'sgdgainfit' for the SXI HXI, and SGD respectively. For the SXS, the 'sxsgain' tasks uses the same core fitting function of 'ahgainfit'.
'ahgainfit' takes as input an event file with time and energy columns, and requires that the events are time ordered. The 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 'ahgainfit' 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.
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 'ahgainfit' uses their values to accumulate the spectra, instead of the range derived using the 'extraspread' setting. The energy column used to accumulate the spectra is specified by the 'energycol' parameter. The energy column is expected to be in units of channel, where the eV per channel is set by the 'evchannel' parameter. The spectra are binned according to the 'binwidth' parameter, where the 'binwidth' is in units of 'energycol' channels. The theoretical profile is constructed on a mesh defined by this energy range and 'binwidth', where each calibration line is assumed to be Lorentzian. The profile may be convolved with a Gaussian having the FWHM given by the 'broadening' parameter.
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.
The spectra events may be simultaneously collected based on the value of a column present in the event file, given by the 'splitcol' parameter. This option may be used, for example, to find the gain correction for each layer of the HXI detector ('splitcol=LAYER'). If a GTI file is specified by the 'gtifile' parameter, events outside of these GTI intervals are excluded. Spectra are not accumulated across GTI intervals unless the 'spangti' parameter is set to 'yes'.
For each accumulated spectrum, 'ahgainfit' 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, optionally, 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 energy (as specified by 'energycol') is the sum of the energies in the spectrum divided by the number of events in the spectrum. The binned average energy is the weighted average derived by summing, over bins in the spectrum, the product of the energy and number of events per bin, and then dividing by the total number of events in the spectrum. The fitted gain corrections 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.
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), splitcol (value of splitcol for spectrum as given by the 'splitcol' parameter; this column is absent if 'splitcol=NONE'), 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). 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.
1. Compute the gain correction for an SXI event file using Mn K lines as the theoretical profile. The theoretical profile is convolved with a 12 eV Gaussian and gains are computed separately for each CCD_ID.
ahgainfit infile=event_in.fits outfile= drift_out.fits linetocorrect=Mnka energycol=PI splitcol=CCD_ID extraspread=20. \ evchannel=6. broadening=12. fitwidth=yes
Compute the gain correction for an HXI event file using Mn K lines as the theoretical profile. The theoretical profile is convolved with a 200 eV Gaussian and gains are computed separately for each SIDE.
ahgainfit infile=event_in.fits outfile=drift_out.fits linetocorrect=Mnka energycol=PI splitcol=SIDE extraspread=400. evchannel=100. \ broadening=200. fitwidth=yes
Compute the gain correction for an SGD event file using the Sn119 line as the theoretical profile. The theoretical profile is convolved with a 1500 eV Gaussian and gains are computed separately for each MATTYPE.
ahgainfit infile=event_in.fits outfile=drift_out.fits linetocorrect=Sn119 energycol=PI splitcol=MATTYPE extraspread=2500. evchannel=1750. \ broadening=1500. fitwidth=yes