HK-ASCII Format

HK-ASCII format is a human-readable text-based table format for storing IRAC Housekeeping and Special Engineering Data. The HK data analysis programs HKHisto and HK2D require this format as input. The data base query program HKQuery accepts the format as input and produces it by default as output (it can also read and produce FITS files).

Components of an HK-ASCII File

A portion of a sample HK-ASCII format file is given below:

# HK-ASCII
#
# HK-TRACK: User: spitzak
# HK-TRACK: Program: HKQuery 1.0
# HK-TRACK: Command: HKQuery -e CTTEMP,CTTEMP6 -m ../report_integrated.txt
# HK-TRACK: Input file: ../20020518_lff_a.hk.fit
     SCLK (TDOUBLE)      SCET (TSTRING:21)        CTTEMP (TINT32BIT)        CTTEMP6 (TINT32BIT)     
D 706212179.1340000629 2002/138-18:02:59.134            9854                      51129             
D 706212209.1340000629 2002/138-18:03:29.134            9855                      51129             
D 706212239.1340000629 2002/138-18:03:59.134            9857                      51129             
D 706212269.1579999924 2002/138-18:04:29.158            9858                      51129             
D 706212299.1340000629 2002/138-18:04:59.134            9859                      51129             
D 706212329.1340000629 2002/138-18:05:29.134            9861                      51129             
E 706212350.5102100372 2002/138-18:05:50.510  SEQ4     VM_DELAY_TAG                                        00 00 00 03 I
E 706212358.5116100311 2002/138-18:05:58.512  SEQ4     IRAC_FPE_READOUT                                    f0 (FPA1ON_FPA2ON_FPA3ON_FPA4ON_Full_Array) 00
D 706212359.1340000629 2002/138-18:05:59.134            9863                      51129             
E 706212360.5094599724 2002/138-18:06:00.509  SEQ4     IRAC_DOIT                                           00 00 00 27 '9..!
D 706212389.1340000629 2002/138-18:06:29.134            9864                      51129             
D 706212419.1340000629 2002/138-18:06:59.134            9866                      51129             
D 706212449.1340000629 2002/138-18:07:29.134            9867                      51129             
E 706212461.5107300282 2002/138-18:07:41.511  SEQ4     VM_DELAY_TAG                                        00 00 00 03 I
E 706212469.5127700567 2002/138-18:07:49.513  SEQ4     IRAC_DOIT                                           00 00 00 27 '9.."
D 706212479.1340000629 2002/138-18:07:59.134            9868                      51129             
D 706212509.1570000648 2002/138-18:08:29.157            9870                      51129             
D 706212539.1340000629 2002/138-18:08:59.134            9872                      51129             

This sample shows the three major components of an HK-ASCII file:

1. Header Information: The first few lines of the file which begin with the "#" character are the file header. The header contains a line identifying the file as HK-ASCII, which is used by HKQuery and the plotting programs HK2D and HKHisto to determine that the file is HK-ASCII, and thus readable. Following it are several lines of "tracking" information which tell the history of the creation of the HK-ASCII file - who created it using what command and which input files.

   Note that in general a "#" as the first character in a line identifies that line as a comment. These can appear anywhere in an HK-ASCII file, and may be added to denote parts of a file of specific interest. However, any line beginning with the characters "# HK" will be considered part of the header information.
   
   

2. Table Header: The next line identifies the HK/SED components which are included as data in the file, using the names from the HK/SED data files. These names will be used by the plotting programs to identify each data component as well. Following each name in parenthesis is a description of the data type using a slightly expanded CFITSIO convention.

   Under most circumstances the first two data items in the table header will be the floating point time "SCLK" and its character string translation "SCET". All HK programs use the SCLK to track time - the SCET is provided only for readability.
   
   

3. Data: Following the table header are the table data. These data are in time order, and can take one of two forms:
   • Real Data lines, which have one data component for each item in the table header. These lines begin with a "D" character.
   • Event lines, which in addition to the SCLK and SCET timestamps contain three character string fields - a "type" (up to 8 characters, no spaces), a "command" (up to 50 characters, no spaces), and a "comment" (the rest of the line, no space restrictions). These lines begin with an "E" character.
   While the data lines are pretty straight-forward, event lines bear some clarification. Normally, events are IRAC HK commands, included in an HK-ASCII file by HKQuery from a Commands file (see Merging Commands Files in the HKQuery documentation). However, an event can be added by hand, as long as the time and character string fields are filled in correctly. Why would you want to do this? Events can be plotted along the SCET timeline of a HK2D plot (see Plotting Events in the HK2D documentation), allowing a specific string (the "command" string) to be included on the X-axis of the plot at a specific time. This might be useful for annotating plots.