.help hkexpand Feb98 ftools.heasarc
.ih
NAME
hkexpand -- Expand an ASCA Housekeeping data table in compressed format into a
full sized table with one column per HK parameter.
.ih
USAGE
hkexpand infile[ext#] outfile
.ih
DESCRIPTION
This task expands an ASCA compressed FITS Housekeeping data table.
A compressed table contains just 3 columns (time, parameter name,
and parameter value) which list the new value of every housekeeping (HK)
parameter whenever it has changed from its previous value.
The uncompressed table that is produced by this task has a separate
column for each HK parameter.  This is generally much larger than the
compressed format table because the value of every HK parameter must
be written to the table whenever any single parameter changes its value.


The input table is assumed to be sorted in increasing time order.  The 
time column is in double precision format.  The
output parameters can be either scalar(real or integer) or character
string(with maximum length of 30). You are free to choose 
whatever scalar data-type you like in the output file regardless of the 
data-type from the input file. However, you are not allowed to converted 
a string column in the input to  scalar columns in the output or vice versa.
 
.ih
PARAMETERS
.ls infile [filename]
The file name and extension number in square brackets of the
input compressed format HK table.
.le
.ls outfile [filename]
The name of the output expanded FITS table.
.le
.ls (param = " ") [string]
A list of House Keeping parameter names to be place in the expanded output
FITS file. A blank string signifies all parameters.
.le
.ls (dtime = 0.0) [double]
The time interval between writing current values of House Keeping
parameters to the output FITS file.  A Negative dtime value is only 
served as a flag. A value between -1 and 0( -1 < dtime <=0.0) indicates 
that parameters are  written  to the output file only for time stamps found in
the time ordered input FITS file. For dtime <= -1.0,
in addition to the previous feature,
the required parameters are only written to the output file
if  at least one of them has been changed.


.le
.ls (name = "name") [string]
The column name in the input table containing the housekeeping parameter names.
.le
.ls (value = "value") [string]
The column name in the input table containing the housekeeping parameter values.
.le
.ls (time = "time") [string]
The column name in the input table containing the housekeeping parameter time
stamp.
.le
.ls (tnull = " ") [string]
The TNULL keyword value for undefined table values. A blank
indicates no TNULL keywords are to be generated. However, for 
string values(type "A"), the tnull is always " " regardless of  
what tnull string is given.
.le
.ls (outtype = " ") [string]
The data type of output columns.
The outtype can be specified as "F" or"E" (single precision real), "R"
or "D"(double precision real), "B"(Byte), "S"(2 byte short integer), 
"I"(4 byte integer), and "A"(string with 30 characters). 
However, if none of the above is given, the type of the VALUE 
in the input file is used.
(OBSOLETE: If outtype is "R", the output columns are real numbers.  
If outtype is anything else, the output values are integer.)
.le
.ls (constdiv = "yes") [boolean]
If true, and if dtime > 0, then the output is written only at integral
multiples of dtime.  If false, and dtime > 0, then the output is
written at integral multiples of dtime, unless some parameter's
value changes within the interval, in which case the change is
also written out.  If dtime = 0, then constdiv is ignored.
.le
.ls (copyall = "no") [boolean]
If true, all the other extensions of the file are copied into the output
file.  If false, the task still copies the primary header, but no other
extensions.
.le
.ih
EXAMPLES
.nf
1.    Expand the HK FITS file hk0.fits into a file named exhk.fits
      where the parameter names are in the column  Name, their values
      are in the column Value, and the time are in the column Time:

      ft> hkexpand hk.fits exhk.fits
.fi
.ih
BUGS
The input HK parameter values must be numeric scalars or character
fields, not arrays, or
complex numbers.  The only available formats for output
parameter columns are byte, integer(short or long), real(single
precision or double precision), or string(30 characters). 
However, the string column   can not be converted to scalar column or vice versa. 
The extension type of the output table will be the
same as that of the input table.
.ih
SEE ALSO
hkunexpand
.endhelp
