NAME
mxstime - Generate coarse and fine GTI files for the Hitomi MXS, and populate
the appropriate columns in an SXS HK file with MXS start and stop
times for the different LED sources.
USAGE
mxstime infile outfile outgti timfile delayfile
DESCRIPTION
The Modulated X-ray Source (MXS) consists of two, redundant, pairs of
LEDs, each consisting of one direct and one indirect fluorescent
source that illuminates all pixels of the SXS array with a specific
pulse length and time spacing (duty cycle). One or both sources of a
single LED pair may be in operation at a given time. The MXS telemetry
information is contained in the extension HK_SXS_FWE of the SXS
housekeeping (HK) file.
The mxstime task calculates the start and stop times of the four LED
sources and stores the values in the columns TIME_LED#_ON and
TIME_LED#_OFF of the HK_SXS_FWE extension, where "#" takes on integer
values 1 through 4 (1 and 3 representing the MXS in direct mode, and 2
and 4 the corresponding indirect mode). These times are calculated
using: (a) the information in the columns TI_LED#_ON and TI_LED#_OFF,
(b) the header keywords TSTART and TSTOP, (c) the column S_TIME, (d)
the TIM file associated with the observation, and (e) the CALDB files
containing the time delay and leap second information. Note that
within a file, the TI_LED#_ON/OFF column entries are constant unless
the relevant LED was turned on or off during the time interval covered
by the file.
By default (parameter 'calcgti=yes') the mxstime task also creates two
GTI files, each containing four extensions, one for each LED. One GTI
file records the coarse GTI corresponding to LED start and stop time
intervals. In addition to these START and STOP columns, the coarse GTI
output includes PLSLEN and PLSSPC columns, which record the pulse
length and pulse spacing, respectively. Each extension of the coarse
GTI also includes two keywords, LED#LEN and LED#SPC, corresponding to
the recorded pulse length and spacing, respectively. These are set to
positive numbers when there is only one value for all coarse
intervals, set to negative numbers (with magnitudes corresponding the
values in the first GTI) if there is more than one value, and to 0 if
that LED has not been turned on.
A second GTI file records the fine GTI corresponding to the individual
LED pulses. The fine GTI are calculated using the telemetered
information in the columns FWE_LED#_PLS_LEN and FWE_LED#_PLS_SPC that
record the pulse length and pulse spacing, respectively. By default,
the mxstime task increases the stop time of each individual pulse by
an amount set by the parameter 'dtdecay' to account for
afterglow. This may be disabled by setting the parameter 'afterglow'
to no. If 'dtdecay' is large enough to extend into the next pulse, GTI
are merged to avoid creating overlapping exposure intervals. In this
case, fine GTI become, effectively, equivalent to coarse GTI except
for the last stop time in the case where 'afterglow=yes' where the
stop time is extended by 'dtdecay'.
For a given LED, it is possible that the value of either TI_LED#_ON or
TI_LED#_OFF changes in the input file, but not both. In the first case
the GTI are calculated starting from when TI_LED#_ON changes, going
forward to the end of the file. In the second case
the GTI are calculated starting from when TI_LED#_OFF
changes, going backward to the start of file.
An offset to all MXS GTI start and stop times may be applied by
setting the parameter 'mxsoffset' to a nonzero value.
PARAMETERS
- infile = mxs.in [filename]
- Input SXS HK file containing the MXS telemetry information.
- outfile = mxs.out [filename]
- Output HK file. This is a copy of the input file with start and stop
time columns in the appropriate extension populated for each MXS
LED.
- outgti = mxs_#.gti [filename]
- Root name, including a hash character (#) to be replaced by the
strings "cs" and "fn", for coarse and fine output GTI files,
respectively. Each file has four extensions, one per LED.
- timfile = test.tim [filename]
- Input TIM file relating spacecraft time (TI) to time.
- delayfile = CALDB [filename]
- Input delay file specifying the time delay between the central
processor and each MXS. If the parameter is set to CALDB, the file is
read from the calibration database.
- (leapsecfile = REFDATA) [filename REFDATA|CALDB|file name]
- Name of the leap second file. If the parameter is set to CALDB or
REFDATA, the file in CALDB or the REFDATA area respectively, is used.
- (stimecol = S_TIME) [string]
- Name of S_TIME column.
- (tioncol = FWE_TI_LED#_ON) [string]
- Input TI columns with LED turned on (the hash character, "#"
takes values 1 to 4, inclusive).
- (tioffcol = FWE_TI_LED#_OFF) [string]
- Input TI columns with LED turned off ("#" takes values 1 to 4, inclusive).
- (plslencol = FWE_LED#_PLS_LEN) [string]
- Input pulse length columns ("#" takes values 1 to 4, inclusive).
- (plsspccol = FWE_LED#_PLS_SPC) [string]
- Input pulse spacing columns ("#" takes values 1 to 4, inclusive).
- (timeoncol = TIME_LED#_ON) [string]
- Output LED-on time columns ("#" takes values 1 to 4, inclusive).
- (timeoffcol = TIME_LED#_OFF) [string]
- Output LED-off time columns ("#" takes values 1 to 4, inclusive).
- (calctime = yes) [boolean yes|no]
- If 'calctime' is set to yes, time is assigned in the output HK
file. Note that GTI cannot be calculated without the time assignment
calculation.
- (calcgti = yes) [boolean yes|no]
- If 'calcgti' is set to yes, GTI files are produced.
- (afterglow = no) [boolean yes|no]
- If 'afterglow' is set to yes, the fine GTI intervals are extended
by the afterglow decay time set by the parameter 'dtdecay'.
- (dtdecay = CALDB) [string]
- Afterglow decay time [s]. If the parameter is set to CALDB, the
decay time is obtained from a file that is read from the calibration database.
- (mxsoffset = 0.015625) [double]
- Time offset [s] added to all start and stop times.
- (interp = TWOPOINT) [string NEAREST|TWOPOINT]
- Interpolation method used in time assignment.
- (buffer = -1) [integer -1|0|N]
- Rows to buffer (-1=auto, 0=none, N>0=number of rows).
- (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]
- 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
- Assign time to the input MXS file mxs_hk_in.fits, writing the
results into mxs_hk_out.fits, and create the coarse (mxs_cs.gti) and
fine (mxs_fn.gti) MXS GTI files, using the TIM file (timfile.fits) and
the delay file (delay_caldb.fits).
mxstime mxs_hk_in.fits mxs_hk_out.fits mxs_#.gti timfile.fits delay_caldb.fits
SEE ALSO
ahtime, mxsgti
LAST MODIFIED
August 2, 2024