NAME

USAGE

DESCRIPTION

The task xtdgainfit calculates the time-dependent shift of the calibration source line energies for XRISM Xtend, which has ⁵⁵Fe calibration sources that emit Mn K lines and are mounted so that they illuminate one corner of each CCD. This task is a script that runs ahgainfit on Xtend event files, first allowing the user to select and reprocess the events that are input to ahgainfit. This task works with a single event file or list of files, and includes the following main options:

1. If 'rungtigen=yes', xtdgainfit creates a GTI file using the expression specified either in the parameter 'gtiexpr' and/or using the default expression label ('gtigenlabel' parameter) stored in the file specified by 'selectfile'. The expression label refers to entries listed in the input MKF file ('gtigen_infile'). The 'gtifile' parameter can be used to specify a separate GTI file or set of files that will be merged (logical AND) with any GTI generated by 'rungtigen' or used by itself if 'rungtige=no'.

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

3. If 'runselcal=yes', xtdgainfit selects only events in the regions illuminated by the ⁵⁵Fe calibration sources, using the filter expression "STATUS[2]==b1". See the help on xtdflagpix for more information on Xtend STATUS flags.

4. If 'runxtdpi=FULL' or 'PARTIAL', PI is recalculated for all selected events. If 'runxtdpi=FULL', xtdpi is run in its default mode. If 'runxtdpi=PARTIAL', xtdpi is run without charge trail or CTI corrections, and with split threshold iteration disabled. The xtdpi parameters 'hkfile', 'hkext', 'hkcolstem', 'hkvideoid', 'vtevnoddfile', 'chtrailfile', 'ctifile ', 'spthfile', 'gainfile', 'patternfile', 'randomize', and 'seed' may be set within xtdgainfit (see the xtdpi help file for details). If 'runxtdipi=no', xtdpi is not run and the existing PI values are used.

Once any screening and reprocessing of the event data is complete, ahgainfit is run on the remaining event lists. This task accumulates spectra from events that are consecutive in time with energy centered on the specified calibration feature, and compares each spectrum from the events with a theoretical model of the calibration feature profile. The relevant ahgainfit parameters used by xtdgainfit are described below, and more information about their function can be found in the ahgainfit help.

Two output files are produced by this xtdgainfit. The first, specified by 'outfile', is a gain correction file identical in structure to that produced by ahgainfit. The second output file contains the screened events created within xtdgainfit. The file name of the screened event file is formed by appending a suffix specified by 'outevtsuffix' to the input file root name.

PARAMETERS

infile [filename]

Name of input Xtend FITS event file. 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 root name of 'infile'.

outfile [filename]

Name of output gain correction file.

(rungtigen = no) [boolean yes|no]

If set to yes, ahgtigen is run to create GTI.

(runscreen = no) [boolean yes|no]

If set to yes, xascreen is run to filter the input file.

(runselcal = no) [boolean yes|no]

If set to yes, events in the calibration source regions are selected using the filter "STATUS[2]==b1".

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

If 'runxtdpi=FULL', PI values are recalculated using the default settings of of xtdpi. If 'runxtdpi=PARTIAL', charge trail and CTI corrections are skipped, and the split threshold iteration is disabled. If 'runxtdipi=no', xtdpi is not run and existing PI values are used.

(gtigen_infile = mkf.fits) [filename]

Name of input MKF file used to create the GTI used in screening. This parameter is ignored if 'rungtigen=no'.

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

Name of input GTI file, or name of text file with list of files, preceded by "@", if including multiple input GTI files to be merged. The GTI specified by this file is merged with any GTI produced if 'rungtigen=yes'. If 'gtifile=NONE', no input GTI file is used.

(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 calibration database (CalDB).

(gtigenlabel = NONE) [string NONE|labels]

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

(screenlabel = NONE) [string NONE|labels]

Labels to read from label file specified by 'selectfile' and used to screen input event file(s). To input multiple labels, use a comma-separated list. This parameter is ignored if 'runscreen=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=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=no'.

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

Name of input Xtend housekeeping (HK) file. This parameter is required to be a valid HK file if 'runxtdpi=FULL' or 'PARTIAL', and is ignored if 'runxtdpi=no'.

(hkext = HK_SXI_USR_USER_HK1) [string]

HK extension name from which the video temperature is read. This parameter is ignored if 'runxtdpi=no'.

(hkcolstem = SXI_USR_HKTBL_) [string]

Column name stem where the video temperature is recorded in the HK file. This parameter is ignored if 'runxtdpi=no'.

(hkvideoid = A,B,A,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 'runxtdpi=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. This parameter is required to be a valid file if 'runxtdpi=FULL' or 'PARTIAL', and is ignored if 'runxtdpi=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. This parameter is required to be a valid file if 'runxtdpi=FULL', and is ignored if 'runxtdpi=PARTIAL' or 'no'.

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

Name of CTI correction file. If set to CALDB, the file is read from the CalDB. This parameter is required to be a valid file if 'runxtdpi=FULL', and is ignored if 'runxtdpi=PARTIAL' or '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. This parameter is required to be a valid file if 'runxtdpi=FULL' or 'PARTIAL', and is ignored if 'runxtdpi=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. This parameter is required to be a valid file if 'runxtdpi=FULL' or 'PARTIAL', and is ignored if 'runxtdpi=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 required to be a valid file if 'runxtdpi=FULL' or 'PARTIAL', and is ignored if 'runxtdpi=no'.

(randomize = yes) [boolean yes|no]

If set to yes, PHA is calculated from PHAS using decimal randomization. This parameter is ignored if 'runxtdpi=no'

(seed = 2) [integer]

Random number generator seed. The system time is used if 'seed=0'. This parameter is ignored if 'runxtdpi=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 Xtend, this should be the SXI_MnK extension.

(energycol = PI) [string]

Name of event list energy column to use in gain fitting.

(splitcol = CCD_ID) [string]

Name of event list column 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.0) [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.0) [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.0) [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.0) [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=no', the profile width is fixed at this value.

(gridprofile = no) [boolean yes|no]

If 'gridprofile=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=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=yes', events in different time intervals in the GTI file ('gtifile') may be collected in the same spectrum to be fit. If 'spangti=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=NONE'.

(avgwinrad = -1.0) [double]

Radius of interval in units of 'binwidth', used only to update the initial shift estimate prior to fitting. If 'avgwinrad=-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 Xtend 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.

     xtdgainfit infile=xa100050020xtd_p0100004b0_uf.evt outfile=drift_out.fits outevtsuffix="_gainfit.evt" \
        linetocorrect=SXI_MnK energycol=PI splitcol=CCD_ID extraspread=20.0 evchannel=6.0 \
        broadening=12. fitwidth=yes
   

SEE ALSO

LAST MODIFIED

November 2, 2023