NAME

hkplot - HK parameter PLOTting and GTI creation task

SYNOPSIS

hkplot [infile=] <file_name> [paramlist=] <col_names> [parameter=value ...]

DESCRIPTION

hkplot is used to create time series plots of SAX/LECS and SAX/MECS HK parameters and, optionally, define GTIs from those plots by making time range selections with the mouse cursor. Up to 8 different parameters can be simultaneously displayed in different, vertically arranged panels. In each of those panels the user may define an arbitrary number of time intervals from which a standard GTI FITS file is generated that can subsequently be used for event selection. The QDP/PLT package which is based on the graphics library PGPLOT is used for plotting purposes. Thus, hkplot supports all graphics output devices for which the underlying PGPLOT module has been configured.

After the corresponding data have been read in from the HK input file, hkplot outputs the requested plots to the specified device and enters the interactive PLT environment, allowing to modify the appearance of the plot (rescaling, adding labels, etc.). The user exits from PLT with 'Quit' and then has the possibility to define individual time intervals with the mouse cursor (if input device has this capability). Actions are triggered by pressing keys/mouse buttons:

      Key / Mouse Button   Function
      ----------------------------------------------------
      'A' / Left           begin/finish an interval
      'D' / Middle         delete last point/time interval
      'X' / Right          delete all GTIs defined so far
      'x','q'              exit GTI definition

After exiting with 'x' or 'q', a standard GTI file comprising the interval definitions made is generated. Its name is derived from the name of the HK input file.

PARAMETERS

The following command line parameters are recognized by the program:

infile = "" [string]

The name of the HK input file.



paramlist = "" [string]

A list of HK parameters represented by their corresponding column names in the HK Bintable extension of the input file. Case is not significant and all names have at least one unique abbreviation, e.g. 'ct' for CELL_TEMPERATURE. To get a list of all valid HK parameter names together with possible abbreviations, invoke hkplot with paramlist = '?'.



merge = "OR" [string: "AND|OR"]

This parameter determines how GTIs defined in different HK plot panels are merged together. In the default OR mode, the final set of GTIs is constructed by logically ORing all single intervals. In AND mode, the final set of GTIs consists merely of those intervals that are common to all GTIs from the various HK panels. Panels for which no GTIs have been defined are not considered. Example:

     GTI 1:               |-------------|
     GTI 2:                         |----------|

     resulting OR-GTI:    |--------------------|
     resulting AND-GTI:             |---|





times = "-" [string]

A comma or semi-colon separated list of time intervals referring to the time tags in the HK input file. For each interval specified, a separate plot window will be generated displaying merely the HK parameter evolution during this period. The default is times = "-" meaning to display the whole time period covered by the input file in only one window. "-" given as an lower or upper limit of a time interval specification is taken as the smallest and largest time tag of the input file respectively. Example: times = -100,130-140,150- will pop up three plot windows (one after another) displaying the HK parameter time evolution during the periods [min_t, 100], [130, 140], and [150, max_t].



device = "/XWIN" [string]

A string specifying the desired output device for plotting. Each device for which the PGPLOT library has been configured is valid.



pltcmd = "" [string]

Any legal PLT command that is appended to the list of default PLT commands automatically generated to label the axes and provide a title of the plot based on the input file name. If pltcmd is in the form @filename the generation of default commands is suppressed. Instead, the file filename.pco in the current working directory is taken as a source for PLT commands to be interpreted.



gtidef = yes [boolean: yes|no]

A boolean switch pertaining to the interactive definition of GTIs. If set to "no", the program merely creates the requested HK time series plots without prompting the user to make interval selections.



verbosity = 1 [integer: 0|1|2|3]

Specifies the program verbosity level, i.e. the amount of screen output that will be issued during program execution. Level 0 means "mute", only fatal error messages will be printed. Default is level 1.



help = no [boolean: yes|no]

If set to "yes", issue a brief on-screen description of all available command line parameters together with the current program version number.

EXAMPLES

1. Display the time evolution of the three HK parameters cell temperature, cell pressure, and EU temperature in the interval t = 1000 - 2000 s from file "cont5_hkp.fits". GTIs defined in different plot panels should be AND-merged in the end:

        hkplot cont5_hkp.fits "ct cp eut" times=1000-2000 merge=and
   

2. Plot the HK parameters CELL_HIGH_VOLTAGE and PMT_HIGH_VOLTAGE for the whole time period spanned by the input file sample_hkp.fits. The definition of GTIs is not required:

        hkplot sample_hkp.fits "CELL_HIGH_VOLTAGE PMT_HIGH_VOLTAGE" gtidef-
   

FURTHER DOCUMENTATION

1. The SAX LECS Data Analysis System - Software User Manual,
   U. Lammers, Doc. SAX/LEDA/0010

BUGS

None known.

SEE ALSO

fplot, fltime (both FTOOLS)