NAME

USAGE

DESCRIPTION

The task sxigainfit is a script that runs ahgainfit on SXI event files and allows the user to select and reprocess the events input into ahgainfit. The description of the task ahgainfit and the parameters that are also used by sxigainfit are described below. The task sxigainfit works with a single event file or list of files.

The SXI has ⁵⁵Fe calibration sources that emit Mn K lines and are mounted so that they illuminate one corner of each CCD. The task sxigainfit calculates the time-dependent shift of the calibration source line energies. It includes options to (a) create GTI (see parameter 'rungtigen'), (b) screen the events ('runscreen'), (c) select the calibration source region ('runselcal'), and (d) recalculate the PI ('runsxipi') prior to running ahgainfit.

(a) If 'rungtigen=yes', sxigainfit creates a GTI file. The GTI are created using the expression specified either in the parameter 'gtiexpr' and/or using the default expression label ('gtigenlabel' parameter) stored in a CALDB file ('selectfile' parameter). The expression label refers to entries listed in the input MKF file ('gtigen_infile' parameter). If the 'gtifile' parameter is set, a single GTI file or a list of GTI files specified is also used.

(b) If 'runscreen=yes', sxigainfit screens the input event data with the expression specified in the parameter 'expr' and/or using the default expression label ('screenlabel' parameter) stored in the file specified by the 'selectfile' parameter.

(c) If 'runselcal=yes', a region selection is applied to include only events from the calibration source locations.

(d) If 'runsxipi' is set to 'FULL' or 'PARTIAL', the PI is recalculated. If 'runsxipi=FULL', sxipi is run in its default mode. If 'runsxipi=PARTIAL', sxipi is run with no charge trail correction, no CTI correction, and does not enable the split threshold iteration. The sxipi parameters 'hkfile', 'hkext', 'hkcolstem', 'hkvideoid', 'vtevnoddfile', 'chtrailfile', 'ctifile ', 'spthfile', 'gainfile', 'patternfile', 'randomize', and 'seed' may be set within sxigainfit (see the sxipi help file for details). If 'runsxsipi=no', sxipi is not run and the existing PI values are used.

The task sxigainfit creates two outputs. The first is a gain correction file identical in structure to that produced by ahgainfit. The second is the screened event file created within sxigainfit. The file name of the screened event file is formed by appending a suffix to the input file root name, where the suffix is set by the parameter 'outevtsuffix'.

ahgainfit:

The task 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'). The ahgainfit task is a multi-instrument one and is used directly by the scripts sxigainfit, hxigainfit, sgdgainfit for SXI, HXI, and SGD respectively. For SXS, the sxsgain task uses the same core fitting function as that used by ahgainfit.

The task 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 determined by the smallest and largest energies of the line components that are then expanded with the 'extraspread' parameter, i.e. [E_min - extraspread : E_max + extraspread]. It is recommended to set 'extraspread' to be larger than the sum of the natural width of the calibration feature and then taking into account the value of the 'broadening' parameter, as well as 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 '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, where the FWHM is 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' events, 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 intervals of 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 spectral events may be conditionally 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 fitted with a constant value if 'background' is set to CONST, 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 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.

The default values for the parameters used in the fitting method ('minwidth0', 'maxitcycle', 'r2tol', 'searchstepshift', 'maxdshift', 'bisectolshift', 'searchstepwidth', 'maxdwidth', 'bisectolwidth', and 'minwidth') need not be changed since these parameters have already been optimized.

The output file has two extensions. One extension, named 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 spectrum 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 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 extend between SHIFT +/- (shifterrfac*W), and the width error arrays extend between [WIDTH - (W/widtherrfac)] and [WIDTH + (W*widtherrfac)].

PARAMETERS

infile [filename]

Input event file name. Input file may be a single file or a list of files (the name of the text file with the list preceded by the "@" character).

outevtsuffix [string]

Screened output file name suffix. This string is appended to the first input file root name.

outfile [filename]

Output gain correction file name.

(runselcal = no) [boolean yes|no]

If set to yes, run to select calibration source events.

(runsxipi = FULL) [string FULL|PARTIAL|no]

If 'runsxipi' is set to FULL, recalculate PI using the default mode of sxipi. If 'runsxipi' is set to PARTIAL, skip charge trail correction, CTI correction, and do not enable the split threshold iteration. If 'runsxsipi' is set to no, do not run sxipi.

(rungtigen = no) [boolean yes|no]

If set to yes, run ahgtigen to create GTI.

(runscreen = no) [boolean yes|no]

If set to yes, run ahscreen to filter input file.

hkfile [filename NONE|file name]

Name of input SXI housekeeping (HK) file. If set to NONE, then this file is not used for the even-odd correction and results in an error unless 'evnoddcor' is set to no. This parameter is ignored if 'runsxipi' is set to no.

(hkext = HK_SXI_USR_USER_HK1) [string]

HK extension name from which the video temperature is read. This parameter is ignored if 'runsxipi' is set to no.

(hkcolstem = SXI_USR_HKTBL) [string]

Column name stem where the video temperature is recorded in the HK file. This parameter is ignored if 'runsxipi' is set to no.

(hkvideoid = A,B,B,B) [string]

Video card IDs used for the even-odd correction for CCD1, CCD2, CCD3, and CCD4. This parameter must consist of 4 characters of A or B separated with commas. This parameter is ignored if 'runsxipi' is set to no.

(vtevnoddfile = CALDB) [filename CALDB|NONE|file name]

Name of even-odd video temperature correction file. If set to CALDB, the file is read from the calibration database (CalDB). If set to NONE, the task does not use this calibration information and results in an error unless 'evnoddcor' is set to no. This parameter is ignored if 'runsxipi' is set to no.

(chtrailfile = CALDB) [filename CALDB|NONE|file name]

Name of charge trail correction file. If set to CALDB, the file is read from the CalDB. If set to NONE, the task does not use this calibration information and results in an error unless 'chtrailcor' is set to no. This parameter is ignored if 'runsxipi' is set to no.

(ctifile = CALDB) [filename CALDB|NONE|file name]

Name of CTI correction file. If set to CALDB, the file is read from the CalDB. If set to NONE, the task does not use this calibration information and results in an error unless 'cticor' is set to no. This parameter is ignored if 'runsxipi' is set to no.

(spthfile = CALDB) [filename CALDB|NONE|file name]

Name of split threshold values file. If set to CALDB, the file is read from the CalDB. If set to NONE, the task does not use this calibration information and results in an error unless 'spthcaldb' is set to no. This parameter is ignored if 'runsxipi' is set to no.

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

Name of gain file for PHA to PI conversion. If set to CALDB, the file is read from the CalDB. If set to NONE, the task does not use this calibration information and results in an error unless 'gaincor' is set to no. This parameter is ignored if 'runsxipi' is set to no.

(patternfile = CALDB) [filename CALDB|NONE|file name]

Name of file for grade hit pattern. If set to CALDB, the file is read from the CalDB. This parameter is ignored if 'runsxipi' is set to no.

(randomize = yes) [boolean yes|no]

If set to yes, PHA is calculated from PHAS using decimal randomization. If 'startcol' is PHAS_EVENODD, PHAS_TRAILCORR, or PHAS_CTICORR, this parameter is ignored since those columns are floating point values. This parameter is ignored if 'runsxipi' is set to no.

(seed = -1457) [integer]

Random number generator seed. The system time is used if 'seed=0'. This parameter is ignored if 'runsxipi' is set to no.

(gtigen_infile = mkf.fits) [filename]

Input MKF file used to create the GTI used in screening. This parameter is ignored if 'rungtigen' is set to no.

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

Input GTI file, or name of text file with list of files, preceded by "@" if including multiple input GTI files to be merged. If the parameter is set to NONE, no input GTI file is used. This parameter is ignored if 'rungtigen' is set to no.

(selectfile = NONE) [filename NONE|CALDB|file name]

Name of the select file or user input label file with labels and expressions. If the parameter is set to CALDB, the file is read from the CalDB.

(gtigenlabel = NONE) [string NONE|labels]

Labels to read from label file specified by 'selectfile' and applied to 'gtigen_infile' to create GTI, or NONE. To input multiple labels, use a comma-separated list. This parameter is ignored if 'rungtigen' is set to no.

(screenlabel = NONE) [string NONE|labels]

Labels to read from label file specified by 'selectfile' and used to screen input event file(s), or NONE. To input multiple labels, use a comma-separated list. This parameter is ignored if 'runscreen' is set to no.

(gtiexpr = NONE) [string NONE|expression]

Expression, or label to read from label file specified by 'selectfile', used to create GTI. If the parameter is set to NONE, no expression is used. This parameter is ignored if 'rungtigen' is set to no.

(expr = NONE) [string NONE|expression]

Additional event screening expression used to screen input event file(s). If the parameter is set to NONE, no expression is used. This parameter is ignored if 'runscreen' is set to no.

(linefitfile = CALDB) [filename]

Input 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 = SXI_MnK) [string]

Calibration line to use for the gain correction. The value must match an extension in 'linefitfile'. For SXI, this should be the SXI_MnK extension.

(energycol = UPI) [string]

Name of energy column to use in gain fitting.

(splitcol = PIXEL) [string]

Column name used to select a subset of the input events.

(numevent = 250) [integer]

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

(minevent = 150) [integer]

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

(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 = 0) [double]

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

(startenergy = -1.) [double]

Beginning 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 'linefitfile' for the selected calibration feature, adjusted by the 'extraspread' parameter.

(stopenergy = -1.) [double]

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

(extraspread = 10.) [double]

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

(evchannel = 1.) [double]

Conversion factor from channel number (for 'energycol') to energy [eV/channel].

(binwidth = 1.) [integer]

Energy bin width [channels] to use when collecting spectra.

(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 output the theoretical profile including any convolution due to the 'broadening' parameter; no fitting is conducted.

(fitwidth = no) [boolean yes|no]

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

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

Fitted background type.

(spangti = no) [boolean yes|no]

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

(avgwinrad = -1.) [double]

Radius of interval in units of 'binwidth', used only to update the initial shift estimate prior to fitting. If 'avgwinrad' is set to -1, this radius is automatically calculated based on the theoretical line profile and the 'broadening' parameter. This is not used in calculating the average results.

(calcerr = no) [boolean yes|no]

Compute uncertainties on shift and width of the fitted line.

(writeerrfunc = no) [boolean yes|no]

Output the arrays of chi-squared and likelihood calculated for the SHIFT and WIDTH fitted line parameters.

(minwidth0 = 1.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. The value must be greater than zero.

(maxitcylce = 5) [integer]

Maximum number of fitting iterations.

(r2tol = 0.01) [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. In normal cases, the default value for this parameter should be sufficient.

(searchstepshift = 2.0) [double]

Step size, in units of 'binwidth', used when searching for the 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 (see 'bisectolshift').

(maxdshift = 5.0) [double]

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

(bisectolshift = 0.1) [double]

When the bisection method does not change the fractional energy shift by more than 'bisectolshift', in units of 'binwidth', the fitting procedure is terminated.

(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 (see 'bisectolwidth').

(maxdwidth = 10.0) [double]

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

(bisectolwidth = 0.2) [double]

When the bisection method does not change the fractional convolution width by more than 'bisectolshift', in units of 'binwidth', the fitting procedure is terminated.

(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 for the spectrum.

(nerrshift = 100) [integer]

Number of shift values in uncertainty calculations.

(nerrwidth = 100) [integer]

Number of width values 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.

(cleanup = yes) [boolean yes|no]

Delete temporary files if 'cleanup=yes'.

(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 task parameters in HISTORY.

EXAMPLES

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 Gaussian with a FWHM of 12 eV, and gains are computed separately for each CCD_ID.

    sxigainfit infile=event_in.fits outfile=drift_out.fits linetocorrect=SXI_Mnk energycol=PI splitcol=CCD_ID extraspread=20.0 \
    evchannel=6.0 broadening=12. fitwidth=yes
   
   

SEE ALSO

LAST MODIFIED

November 1, 2023