HKHisto draws a histogram of HK/SED data using the HK-ASCII format output by HKQuery as input. It allows the user to plot any data column in the input file, consult statistics on the data, adjust sizes, labels, and data content, and produce Encapsulated PostScript files as output.
Being a java program, HKHisto must be run with the "java" command:
java HKHisto ...
Input data must be in HK-ASCII format (the human-readable format created by HKQuery by default). These data must be in a single file which is either specified on the command line or is assumed to be from stdin if it is not. HKHisto is not terribly clever about checking the file format, so if you feed it a strange file it may just crash.
HK-ASCII files can contain "events" lines and the human-readable time stamp "SCET".
HKHisto ignores these items. Events can not be plotted as part of a histogram,
and time can only be represented by the floating point "SCLK".
The histogram drawn by HKHisto can be manipulated in a number of
ways using the Pop-up Menu. This menu is obtained by clicking anywhere on the
plot with the left mouse button. Drag the left mouse button to pick any of
the options.
The Pop-up Menu options are described in detail below.
By default, HKHisto does not give the histogram a title. This
behavior can be changed using the command line argument "-title". Alternatively,
a title may be added by choosing "Plot Title" from the pop-up menu, which will
bring up the Plot Title window:
Choosing "Bins" from the pop-up menu will generate the Histogram Bins Window.
This window allows the user to change the start and stop values and the sizes
of the bins in the histogram.
By default, HKHisto will try to pick bins which fit the data.
The bin values can also be changed using the "-bins" command line option.
HKHisto will automatically scale the limits and labels of a plot
to the data when it is started or when a new data column is chosen. An
effort is made to choose "nice" values for all, but this may not be 100%
successful.
Axis limits and labels can be specified on the command line, or they can
be changed using the "X Limits" or "Y Limits" options from the popup menu.
These options will bring up a "Limits Menu" for their respective axis, where
limits and labels can be explicitly set.
The Limits Menu will also allow the "title" of the axis to be set.
By default the Y axis has no title ("N" is assumed), and the X axis is
given the name of the HK/SED keyword being plotted.
The "Statistics" option will generate a new window containing statistics
on the data contained in the histogram. The number of points used to compute
the statistics, as well as the number of points inside and outside the plot
limits are given as well. Unlike other pop-up windows, the statistics window
does not need to be dismissed before the histogram can be manipulated. Click
"OK" to make it go away.
All HK/SED data columns in the input file are available for plotting. By
default, HKHisto uses the first non-SCET, non-SCLK data column for the
histogram. This behavior can be changed using the "-name" command line argument.
Alternatively, the "Histo Data" option in the pop-up menu can be used to
pick any other column. This option produces a submenu containing all of the
HK/SED keywords in the input file. Choosing one will cause the histogram to
be rescaled and redrawn to hold the new data column (this will throw
away any user-selected limits and labels).
The limits on a histogram can be interactively changed using the "zoom"
capability. To use this function, click and drag the right mouse button
to define a box. A red overlay will be drawn to represent the area as
you drag. Then use the left mouse button to choose the "Zoom In" option
on the pop-up menu.
The histogram will be redrawn such that its X limits match the
position of the defined box (zoom operations only change the X axis
limits in HKHisto). Labels will also be redrawn to match the new limits.
A zoom operation can be "undone" by choosing the "Zoom Out" option
from the pop-up menu. The histogram will return to its previous limits.
If "Zoom In" is chosen without defining a box, HKHisto will zoom
in to the most recent zoomed limits (if they exist). Repeated zoom operations
can be performed on a histogram, and the "Zoom In" and "Zoom Out" options
can be used to zoom in and out of a hierarchy of limits.
HKHisto can create an Encapsulated PostScript file which will draw
its current state at any time. Choosing the "Print"
option is from the pop-up menu will bring up the
Print Output window which allows the name of
the PostScript output to be specified (if you use the name "stdout", HKQuery
will assume you want the output to stdout, and not a file called
"stdout"). The printout can be produced in "landscape" format using the
checkbox.
The PostScript file will only be created if the "OK" button is pushed.
Each operation creates a new PostScript file (it does not append to an existing
file), so if you make changes and print multiple times, make sure you specify
a new output file each time if you want to keep all of the print outs.
The output file can also be chosen from the command line (using the
"-out" argument - see below).
HKHisto provides help from the command line when it sees the "-help"
command line argument. Help can either
be general, which you get by running with the "-help" option
without any further arguments:
or it can be about a specific subtopic:
The subtopics provide more detailed information, generally about a specific
command line argument. Subtopics available are:
Pop-up Menu
Setting the Plot Title
Setting Bin Sizes and Limits
Changing Limits and Labels ("Y Limits" and "X Limits")
Generating Statistics for Plotted Data
Choosing Data Columns
Zoom In/Out
Print (Encapsulated PostScript Output)
Other Nifty Features
Help
java HKHisto -help
java HKHisto -help [subtopic]
box x yl
bins xl ylabels
data xlabels ylimits
frame xlimits yt
help xt ytics
name xtics ytitle
nbins xtitle
title