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

  1. 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).
  2.  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