Chapter 3. Starting KST from the Command-line

A common use of KST is to quickly produce plots of data from the command-line. This method of producing plots requires almost no knowledge of KST's graphical user interface, yet produces immediate, useful results.

This tutorial uses a demo package of data files available here. Download and untar the package, and change to the resulting directory:

tar -zxvf kst_tutorialdata.tgz
cd kst_tutorialdata

To obtain an overview of all available KST command-line options, type:

kst --help

A syntax description and list of commands similar to the following will be displayed:

Usage: kst [Qt-options] [KDE-options] [options] [Files]

Kst: a data viewing program.

Generic options:
  --help                    Show help about options
  --help-qt                 Show Qt specific options
  --help-kde                Show KDE specific options
  --help-all                Show all options
  --author                  Show author information
  -v, --version             Show version information
  --license                 Show license information
  --                        End of options

Options:
  -F <dataFile>             Specify data file: used to override a kst file default [|]
  -y <Y>                    Field for Y axis (multiple allowed)
  --ye <equation>           Equation for Y axis (multiple allowed)
  -e <E>                    Field for Y errors (multiple allowed)
  -x <X>                    Field or range for X axis [INDEX]
  --xe <X>                  X vector for equations x0:x1:n [INDEX]
  -p <Y>                    Field for power spectrum (multiple allowed)
  -h <Y>                    Field for histogram (multiple allowed)
  -r <f>                    Sample rate for power spectrum [60.0]
  --ru <U>                  Units for psd sample rate [Hz]
  --yu <U>                  Units for y vectors [V]
  -l <P>                    Length of FFTs is 2^P [10]
  -f <F0>                   First frame to read [-2]
  -n <NS>                   Number of frames to read [-2]
  -s <NS>                   Number of frames to skip each read [-1]
  -a                        Apply boxcar filter before skipping frames
  -m <NC>                   Separate plots arranged in <NC> columns
  -d                        Display as points rather than curves
  -g                        Provide a legend box
  --print <file>            Print to file and exit [<none>]
  --png <file>              Save as a png file and exit [<none>]

Arguments:
  Files                     Data files (if -y given) or *.kst file

KST specific options are listed under the Options: section. Where appropriate, default values are indicated with square brackets at the end of the option descriptionsthese values will be used for any unspecified options.

We will first take a look at the ASCII file gyrodata.dat, included in the demo package. ASCII files are one of the many file types KST is capable of reading. In ASCII files, data is arranged in columns, with each column corresponding to a field, and the column numbers (beginning with 1 from left to right) corresponding to field names. This particular ASCII file contains 3 columns, and thus has field names 1, 2, and 3. To produce a plot of the first column, simply type:

kst -y 1 gyrodata.dat

All the data in the first column will be plotted:

Note that no field was specified for the X axis of the plot, so KST used the default INDEX vector, as expected. The INDEX vector is a special vector in KST that contains integers from 0 to N-1, where N is the number of data values in the corresponding Y axis vector. Close KST by selecting Quit from the File menu, or by typing Ctrl+Q.

gyrodata.dat contains 20000 frames, so you may wish to only look at a portion of the data. To only plot 10000 frames starting from frame 7000, type:

kst -y 1 -f 7000 -n 10000 gyrodata.dat

One of KST's strengths is its ability to plot real-time data. Imagine that new data was being continually added to the end of gyrodata.dat. In such a scenario, it would be useful to only plot the most recent portion of the data. To plot only the last 10000 frames of gyrodata.dat, enter the following:

kst -y 1 -n 10000 gyrodata.dat

If gyrodata.dat was being updated, the plot would continuously scroll to display only the last 10000 frames.

Instead of directly reading an input file, KST can use ASCII data from stdin as a data source. To specify stdin as an input, simply enter stdin as one of the filenames. There are many uses of this capability, such as using KST as part of a sequence of pipes:

cat gyrodata.dat | awk '{print $1 + 2}' | kst -y 1 stdin

The above command uses awk to add 2 to column one of gyrodata.dat before piping the result to KST.

Note that the description of the y option states that multiple instances of the option are allowed. This allows quick plotting of more than one curve, or even more than one plot. To plot all three fields in gyrodata.dat in separate plots, enter the following:

kst -y 1 -y 2 -y 3 -m 1 gyrodata.dat

The m option specifies that separate plots should be used instead of one single plot, as shown below: