ahtime - Calculate times and populate the TIME column for all science and housekeeping data


ahtime infile outfile timfile lookupfile


'ahtime' is a general mission task that assigns times to all science and HK data files. By default the calculated times are written in the column TIME (see parameter 'timecol') for science and HK data file and in the columns START and STOP for GTI files. Only for the HK files the times are also written as an UTC time in the columns YYYY, DDD, HH, MM, SS, US. The time calculation always requires the following supporting input files: a) the tim file (parameter 'timfile') containing the conversion TIME vs TI; b) the CALDB column definition file (parameter 'coldeffile') containing the columns names appropriate for the instrument; and c) the leap seconds file (parameter 'leapsec'). All science data also require the CALDB delay file (parameter 'delayfile') containing the delay added last to the calculated time. The SGD, HXI , SXS science data also require a look-up table stored in the instrument specific HK extension for fine time assignment. The delay file and the HK look-up table are not required when calculating the times for the HK file, but for the HXI and SGD. For the CAMS it is also necessary a CALDB file containing the offsets of the individual measurements relative to a time stamp.
The framework to assign time is based on a three-steps process using two different look-up tables. For the SGD, HXI and SXS science, 'ahtime' first derives the fine time, in unit of L32TI, using a look-up table in the instrument HK (step 1). The fine time is assigned internally by the instrument processor. Afterwards 'ahtime' derives the time using the look-up table in the TIM files providing the TI vs TIME relation (step 2). Last it adds, when appropriate, a delay time between the on board computer and the instrument (step 3). For HK data, step 1 and 3 are skipped because there is not need of fine time assignment. The exceptions are the CAMS and MXS HK where a delay time is added to the times (step 3). For the SXI science the step 1 is skipped because the event data has already fine time information included, but calculates the times considering the DATAMODE (if WINDOW1 or WINDOW2 or WINDOW1BURST and/or WINDOW2BURST) and requires the several keywords to be present in the event file (TIMEDEL, TIMTRANB, EXPDEADB, TIMTRANA, EXPDEADA, FLUSHIMB, LASTDEAD, LASTDEL, NOMEXPO, TIMEPIXR).
'ahtime' updates the following header keywords TSTART, TSTOP, DATE-OBS, DATE-END in the extension and in the primary that correspond to the smaller and largest values of the TIME column. If the file contains more than one extension as for the case of the HK, 'ahtime' calculates time in all extensions. The header keywords , in this case, are updated as follows: the primary header TSTART and STOP correspond to the lowest start and the largest stop considering all the extensions , while in each extension the TSTART and TSTOP are based on the smaller and largest time in the TIME column of the extension. The TIME column output from 'ahtime' is not time ordered.


infile [filename]
Name of the input file to calculate the times. This is either a science or HK file.

outfile [filename]
Name of output file with the times assigned.

timfile [filename]
Name of the input TIM file. This file contains the look-up table for the TI vs TIME conversion.

lookupfile [filename]
Name of the input HK file with local time information. This file contains the look-up table that is required only when times are calculated for the HXI, SGD, SXS science file and for the HXI/SGD HK.

(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.

(coldeffile = CALDB) [string]
Name of the input file with the column names to use for each instrument and HK for the time calculation. This is set by default to CALDB.

(delayfile = CALDB) [string]
Name of the input file with the time delays that are added to the science times. This is set by default to CALDB.

(offsetfile = CALDB) [string]
Name of the input file containing offsets specific for the CAMS subsystem. This is set by default to CALDB.

(timecol = TIME) [string]
Name of the column where the times are written. By default this is TIME.

(gticolums = START, STOP) [string]
Name of the column where the times are written in a GTI file. By default these are set to START and STOP.

(calctime = yes) [boolean]
Flag to perform time assignment.Valid only when processing an HK file.

(calcutc = yes) [boolean]
Flag to update UTC columns in the HK files. Valid only when processing an HK file.

(writekeys = yes) [boolean]
Flag to write the timing keywords in the header of the output file.

(interp = twopoint) [string]
Method of interpolation (nearest, twopoint, fourpoint)

(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).


1. Calculate times for an HK file, using the tim file infile,tim. For HK the 'lookupfile' is set to NONE

ahtime infile.tim NONE
2. Calculating times for a SXS science event file, infile.evt, using the tim file infile,tim. The SXS event requires a 'lookupfile' set to
ahtime sxsinfile.evt infile.tim



February 2, 2016