NAME
sgdgainfit - Calculate the Hitomi SGD time-dependent energy gain corrections
for events from comparison with known calibration lines
USAGE
sgdgainfit infile outevtsuffix outfile
DESCRIPTION
The sgdgainfit task is a script that runs ahgainfit on SGD event files and
allows the user to select the events input into ahgainfit. The
description of ahgainfit and its parameters also used
by sgdgainfit are described below.
(a) If 'rungtitgen=yes', sgdgainfit creates a GTI file. The GTI are
created using the expression either specified 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, the
single GTI file or a list of GTI files specified is also used.
(b) If 'runscreen=yes', sgdgainfit 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 CALDB
file specified by the 'selectfile' parameter.
The sgdgainfit task 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 sgdgainfit. The file name of
the screened event file is the same as the input file with a suffix
(see 'outevtsuffix' parameter) appended.
The ahgainfit task:
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 SGD 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 = in.fits [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 rootname.
- outfile [filename]
- Output gain correction file name.
- (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.
- (gtigen_infile = mkf.fits) [filename]
- Input MKF file used to create a 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) [string NONE|CALDB|file name]
- CALDB or user input label file with labels and expressions. If the parameter is set to CALDB,
the file is read from the calibration database. If the parameter is set to NONE, this file is not used.
- (gtigenlabel = NONE) [string]
- 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' is set
to no.
- (screenlabel = NONE) [string]
- 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' 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 = line.in) [filename CALDB|file name]
- Input CALDB 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 calibration database.
- (linetocorrect = MnK) [string 103mRh|127mTe|129mTe|125mTe|123mTe|115mIn|511keV]
- Calibration line to use for the gain correction. The value must
match an extension in 'linefitfile'.
- (energycol = PI) [string]
- Name of energy column to use in gain fitting.
- (splitcol = SIDE) [string]
- Column name used to separate the data.
- (numevent = 1000) [integer]
- Number of events collected for each spectrum used to calculate a
single gain correction.
- (minevent = 750) [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. 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 = 500) [double]
- Energy [eV] by which the energy range is extended on either side
beyond the lowest and highest energies in 'linefitfile' for the
selected calibration feature. This parameter may be overridden by the
'startenergy' and 'stopenergy' parameters.
- (evchannel = 100) [double]
- Conversion factor from channel number (for 'energycol') to energy
[eV/channel].
- (binwidth = 1.0) [double]
- Energy bin width [channel] to use when collecting spectra.
- (broadening = 200) [double]
- FWHM [eV] of the Gaussian 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 = yes) [boolean yes|no]
- If 'fitwidth' is set to yes, fit the width of each spectra in
addition to the energy shift.
- (background = CONST) [string NONE|CONST|SLOPE]
- Fitted background type.
- (spangti = yes) [boolean yes|no]
- If 'spangti' is set to yes, events in different intervals in '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 GTI. This parameter is ignored if 'gtifile' is set to NONE.
- (avgwinrad = -1.) [double]
- Radius of interval ['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.
- (writeerrfunc = no) [boolean yes|no]
- Output the array of chi-squared and likelihood calculated for the
SHIFT and WIDTH.
- (minwidth0 = 1.0) [double]
- Smallest width ['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 = .01) [double]
- Convergence criterion on 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 completed. This parameter should not normally need to
be changed from the default value.
- (searchstepshift = 2.0) [double]
- Step size ['binwidth'] used when searching for 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 ['binwidth'] from initial
estimate of energy shift. If no solutions are found within this
deviation at smaller or larger shifts from the initial estimate,
the fitting procedure fails for the spectrum.
- (bisectolshift = 0.1) [double]
- When the bisection method determines the energy shift to within
this amount in units of 'binwidth', the fitting procedure is
completed.
- (searchstepwidth = 5.0) [double]
- Step size ['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 ['binwidth'] from initial
estimate of convolution width. If no solutions are found within this
deviation at smaller or larger widths from the initial estimate,
the fitting procedure fails for the spectrum.
- (bisectolwidth = 0.2) [double]
- When the bisection method determines the convolution width to within
this amount in units of 'binwidth', the fitting is procedure is completed.
- (minwidth = 0.5) [double]
- Since the least-squares fitting functional 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 ['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 domain of shift uncertainty arrays.
- (widtherrfac = 4.0) [double]
- Factor for determining domain of width uncertainty 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 = no) [boolean yes|no]
- Records tool parameters in HISTORY.
EXAMPLES
- Compute the gain correction for an SGD event file using the MnK lines
as the theoretical profile. The theoretical profile is convolved with
a 200 eV Gaussian and gains are computed separately for each SIDE (the
default values).
sgdgainfit infile=event_in.fits outevtsuffix=clean outfile=drift_out.fits
SEE ALSO
ahgainfit, ahscreen, ahgtigen
LAST MODIFIED
February 22, 2024