NAME

mxstime -- Calculate the times of the MXS start and stop and generates coarse and fine GTI files

USAGE

mxstime infile outfile outgti timfile delayfile

DESCRIPTION

The Modulated X-ray Source (MXS) consists of two redundant pairs of LEDs, one direct and one indirect fluorescent source that illuminate, with a specific pulse length and spacing duty, the entire SXS array. The MXS may operate either one or both sources from one pair operating at a time. The telemetry information of the MXS is contained in the extension HK_SXS_FWE of the SXS housekeeping file.
'mxstime' by default always calculates the MXS start and stop times and generates coarse and fine GTI files. The parameters 'calctime' and 'calcgti' may be used to only calculate the start and stop times or only the gti file. 'mxstime' calculates the start and stop times of the four LEDs that are stored in the columns TIME_LED#_ON, TIME_LED#_OFF, where # has values 1 to 4, of the HK_SXS_FWE extension. These times are calculated using: a) the information in the columns TI_LED#_ON, TI_LED#_OFF, b) the header keywords TSTART and TSTOP, c) the column S_TIME, d) the TIM file associated to the observation, e) the caldb files containing the delay and the leapseconds. Note within a file the TI_LED#_ON/OFF have the same value unless the LED# is turned on or off.
'mxstime' also creates two gti files each containing four extensions, one for each LED. One GTI file records the coarse gtis corresponding to LED start and stop intervals. The coarse GTI output contains the START and STOP columns but also the PLSLEN and PLSSPC columns, recording the pulse length and spacing. Each extension of the coarse GTI also includes two keywords LED#LEN LED#SPC, recording length and spacing. These are set to positive numbers if there is only one pulse length and spacing for all coarse intervals, to negative otherwise and to 0 if that LED has not be turned on.
The second GTI file records the fine gti time corresponding to the individual pulses. The fine gtis are calculated using the telemetered information in the columns FWE_LED#_PLS_LEN FWE_LED#_PLS_SPC recording the pulse length and spacing. 'mxstime' by default always add a time to the stop time of each individual pulse (see the parameter 'dtdecay'). By setting the parameter 'afterglow=no' no time is added to the stop time of each pulse. If the 'dtdecay' is large enough to overlap with the next pulse, the gti are merged to avoid creating double exposure. In this case the fine GTI is effectively as the coarse GTI, except for the last stop time that is increased by 'dtdecay' (if the afterglow parameter is set to 'yes'..
For a given LED it is possible that the file only contains TI_LED#_ON or the TI_LED#_OFF value changes, but not both. In this case the GTIs are calculated starting from the TI_LED#_ON, going forward to the end of the file, or from the TI_LED#_OFF, going backward to the start of file, using the length and spacing appropriate for that LED.
To all MXS times an offset is added that is specified in the parameter 'mxsoffset'.

PARAMETERS

infile [filename]
Name of the input MXS file. The MXS telemetry information is in the SXS housekeeping file .hk1

outfile [filename]
Name of the output file. This is a copy of the input file where the start and stop time columns for each MXS LED are populated. To overwrite a preexisting file with the same name, prefix the name with an exclamation point '!' (or '\!' on the Unix command line), or else set the 'clobber' parameter = yes.

outgti [filename]
Root of output GTI files. The root name should contain an hash character (#) , ex myfile#, which is replaced by 'cs' and 'fn' words to create two GTI files. Each file has one extension per LED for a total of four extensions.

timfile [filename]
Name of input TIM file relating spacecraft time (TI) to time.

delayfile [string]
Name of input delay file specifying the time delay between the central processor and each MXS. By default this is set to CALDB.

(leapsecfile = REFDATA) [string]
Name of the input leap second file. If set to CALDB or REFDATA uses the leapsecond file in either CALDB or REFDATA area.

(stimecol = S_TIME) [string]
Name of S_TIME column.

(tioncol = TI_LED#_ON) [string]
Names of columns in the input file with LED-on TIs (#=1-4).

(tioffcol = TI_LED#_OFF) [string]
Names of columns in the input file with LED-off TIs (#=1-4).

(plslencol = LED#_PLS_LEN) [string]
Names of columns with LED pulse lengths (#=1-4).

(plsspccol = LED#_PLS_SPC) [string]
Names of columns with LED pulse spacings(#=1-4).

(timeoncol = TIME_LED#_ON) [string]
Names of columns to store the output LED-on TIME (#=1-4). Created if not already present.

(timeoffcol = TIME_LED#_OFF) [string]
Names of the columns to store the output LED-off TIME (#=1-4). Created if not already present.

(calctime = yes) [boolean]
If calctime=yes, start and stop times are assigned.

(calcgti = yes) [boolean]
If calcgti=yes, the GTI file is produced.

(afterglow = yes) [boolean]
If afterglow=yes, a time specified in the parameter 'dtdecay' is added to the stop times in the fine gti.

(dtdecay = CALDB) [string]
Time added to the stop time of each pulse (afterglow). By default 'dtdecay' is set to the values stored in CALDB else a time may be specified in seconds.

(mxsoffset = 0.015625) [real]
This time offset is added to all start and stop times.

(interp = twopoint) [string]
Method of interpolation (nearest, twopoint) used when assign time.

(buffer = -1) [integer]
Rows to buffer (-1=auto, 0=none, >0=numrows).

(clobber = no) [boolean]
Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]
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 filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.

(debug = no) [boolean]
Diagnostic output is printed out on the screen if set to yes (yes/[no]).

(history = yes) [boolean]
Records tool parameters in HISTORY ([yes]/no).

(mode = ql) [string ql|hl|q]
Mode to query the parameter file. Acceptable values include: 'ql' (query and learn/remember), 'hl' (hidden and learn/remember), 'q' (query but don't remember),'h' (hidden).

EXAMPLES

1. Assign time to the input MXS file mxstime mxs_hk_in.fits, writing the results into mxs_hk_out.fits; and, create the coarse (mxs_coarse.gti) and fine (mxs_fine.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

LAST MODIFIED

February 1, 2016