# The &kst; Tutorial

Barth Netterfield

    kst@kde.org

Rick Chern

    kst@kde.org

2004 The University of British Columbia
&FDLNotice;
2004-06-23
0.98

&kst; is a data plotting and manipulation program with powerful plugin support.

KDE kdeextragear kdeextragear-2 Kst plotting plot

## Welcome

Welcome to &kst;! In a few minutes, you will be on your way to exploring the rich features of this plotting and data manipulation package. Here are just some of the tasks you can accomplish using &kst;:

- Quickly plot multiple graphs using only the command-line.

- Analyze data using an extensive set of tools including histograms, power spectra, and custom equations.

- Effortlessly zoom in and out of interesting areas of plots using either the mouse or keyboard

- Monitor live streaming data using &kst;'s real-time plotting capabilities.

This tutorial covers the basics of installing, running, and working with &kst;. You are invited to further investigate any features at any time. All features are documented in the official Kst Handbook, available by selecting Kst Handbook from the Help menu of &kst;.

## Installation

In most cases, performing a basic installation of &kst; is easy. The only prerequisites for &kst; are versions 3.1 or greater of &kde; and &Qt;. However, optional libraries such as the &GNU; Scientific Library enable &kst; to be compiled with additional plugin and file support functionality, and are highly recommended as they are required for certain portions of this tutorial.

If you use a package management system, you may use it to install &kst; instead. However, be aware that the version available in the repository may not be the latest version.

First, you should make sure that the required &kde; and &Qt; libraries have been installed on your system. &kst; v0.99 requires &kde; 3.1 and &Qt; 3.1. Almost all major &Linux; distributions have packages for &kde; and &Qt;, so it is recommended that you refer to your particular distribution's documentation for &kde; installation. More information is available on the &kde; website.

The &GNU; Scientific Library provides a variety of mathematical operations for the built-in &kst; plugins. The library can be found at ftp://ftp.gnu.org/gnu/gsl/. Alternatively, you can find GSL under `/gnu/gsl` on the mirrors listed at http://www.gnu.org/prep/ftp.html. Download `gsl-[ver].tar.gz`, where [ver] is the greatest version number found in the directory. Then unzip and untar the file:

    tar -zxvf gsl-[ver].tar.gz

replacing [ver] with the version number of the downloaded file.

Read the `INSTALL` file in the resultant directory for detailed installation instructions. For most systems, the following will work:

    cd gsl-[ver]
    ./configure
    make
    make install

The second optional (but highly recommended) library is the CFITSIO library. It provides support for reading and writing to the FITS (Flexible Image Transport System) data format. The libary can be found at ftp://heasarc.gsfc.nasa.gov/software/fitsio/c/. Download `cfitsio[ver].tar.gz`, where [ver] is the greatest version number found the directory. Then unzip and untar the file:

    tar -zxvf cfitsio[ver].tar.gz

replacing [ver] with the version number of the downloaded file.

Read the `README` file in the resultant directory for installation instructions. For most systems, the following will work:

    cd cfitsio
    ./configure --prefix=/usr
    make
    make install

You may need to modify the `--prefix` option for your particular system, but for most systems, `/usr` will work.

Once all of the prerequisites have been met on your system you can compile and install &kst;. Download the latest source package separately from the &kst; website . Then, type the following:

    tar -zxvf kst-[ver].tar.gz
    cd kst-[ver]
    ./configure --enable-final --prefix=`kde-config --prefix`
    make
    make install

replacing [ver] with the version of &kst; you have.

Note that `kde-config --prefix` is surrounded by backquotes. It is very important that the `kde-config` utility returns the correct path (most likely `/usr`), otherwise &kst; will not install properly. You can double-check by running it directly:

    kde-config --prefix

Ensure that a non-null path is displayed.

You can read through the messages displayed by the `configure` script—if it reports any missing libraries (such as GSL) that should not be missing, please go back and ensure that the libraries and header files have been correctly installed in the appropriate locations. If installation was successful, you can now go on to the next section of this tutorial.

## 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 descriptions—these 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:

## A Quick Tour of the Data Wizard

While using &kst; from the command-line is fast and convenient, there may be situations in which it is easier to import data from the graphical user interface—for example, if you already have &kst; open with other data loaded. Or, you may simply prefer using the graphical user interface. Becoming familiar with both methods of importing data will allow you to make more efficient use of &kst;.

The Data Wizard provides a quick and easy way of creating vectors, curves, and plots in &kst; from data files. To launch the wizard, select Data Wizard... from the Data menu or click the button on the toolbar. You will be prompted to select a data source. Browse to the `gyrodata.dat` file used in the command-line examples and click Next. The following window will be displayed.

Data Wizard Screen 2
Data Wizard Screen 2

The fields available in `gyrodata.dat` are listed to the left. You may filter the list of highlighted fields by entering a string to match (wildcards such as `*` are supported) into the text box above the list. Enter `*` to match anything (i.e. highlight all the the available fields), and then click Check Selected to select all the highlighted fields (which in this case happens to be all the fields).

The Data Range section is used to specify the range of data to read from the selected vectors in the input file. The following discussion assumes knowledge of frames. In brief, a frame is simply a number of data samples, and each data file is composed of a number of frames. For a detailed description of this concept, see the Kst Handbook.

Starting frame, Count from end, Number of frames, and Read to end

  Using these four settings, the lower and upper boundaries of the data range can be set. As an example, select Count from end and enter 10000 for Number of frames to read only the last 10000 frames. If `gyrodata.dat` was being updated in real-time, subsequent additions to the end of the file would be read.

Read 1 sample per N frames and Boxcar filter first

  In addition to the lower and upper range boundaries, the samples to read from the selected range can be set. If Read 1 sample per N frames (where N is the entered value) is not selected, all samples in the selected range will be read. Alternatively, frames in the data file can be skipped by selecting Read 1 sample per N frames For now, deselect Read 1 sample per N frames.

Power Spectrum and X axis settings can be specified within the Plot Types section.

XY, Power Spectrum, and XY and Power Spectrum

  Select XY and Power Spectrum to produce plots of both the data itself and its power spectrum.

X Axis Vector

  The vector to be used as the independent vector for the plots. You may select a field from your data file, or the INDEX vector. Since `gyrodata.dat` does not contain an X axis vector, leave the selection as INDEX.

The FFT Options subsection in the Plot Types section is available only if a power spectrum is to be plotted. This tutorial will not deal with the details of power spectra, so use the default settings for this subsection.

Once you are satisfied with all the settings, click Next to advance to the next window.

Data Wizard Screen 3
Data Wizard Screen 3

From here, you can change general plotting settings. Most of the settings are self-explanatory. Select 1 new plot per curve for Curve Placement and In new window for Plot Placement. This will place all six plots (three curves and three power spectra) in the same window.

Once you are satisfied with all the settings, click Finish and the plots will be generated:

The Generated Plots
The Generated Plots

Generating these plots took a bit of effort, so we should save the current &kst; session (it will be used in the next section of this tutorial). Select Save As... from the File menu, and save the session as `mykstsession.kst`:

Saving a KST session
Saving a KST session

Saving a &kst; session saves all the plots, data objects (you will learn about these later), and layouts that exist at the time of saving.

Once the file has been saved, you can exit &kst;.

## The Basics of Plot Manipulation

Now that you are comfortable with creating plots in &kst;, we can explore some of the plot manipulation features available through the &kst; graphical user interface. Start &kst; from the command-line with the `mykstsession.kst` file you saved earlier:

    kst mykstsession.kst

All the plots you created earlier should now be loaded in &kst;. Examine the plot with the y axis label of `PSD of Column 2 (V/Hz^{1/2})`. To take a closer look at the plot, right click on it and select the Maximize menu item, as shown below:

Maximizing a plot
Maximizing a plot

The plot is now maximized within the current window. Note that anything beyond about 4 Hz does not look interesting in this plot, so it would be useful to view only the area of the plot that looks interesting. To do so, make sure you are in XY Mouse Zoom mode (select XY Mouse Zoom from the Plots menu, or click the toolbar button). Then, simply drag a rectangle from approximately (4, 0.025) to (0,0), as shown below. Note that the coordinates of the mouse cursor are displayed in the lower right corner of the &kst; window (if they are not, ensure that Show Statusbar is checked in the Settings menu).

Zooming in on a plot
Zooming in on a plot

The plot axes will change to zoom in on the selected area of the plot. You may notice that there is a peak at the left end of the power spectrum that extends beyond the new upper y axis limit. Suppose that you wish to view the top of this peak. Right-click on the plot and select Up from the Scroll submenu. The plot should scroll upwards. Of course, it is most likely easier to use the shortcut key associated with the menu item; this is true for most of the zooming and scrolling functions. In this case, the shortcut key is Up Arrow, so the quickest way to scroll upwards would be to hold down the Up Arrow key. To return to maximum zoom at any time, right-click on the plot and select Zoom Maximum from the Zoom submenu (or type M, the shortcut key associated with Zoom Maximum).

Restore the size of the power spectrum plot by right-clicking the plot and unchecking Maximize.

Now look at the plots with y axes labelled `Column 2` and `Column 3`. These are plots of the pitch gyro and roll gyro, respectively, from the 1998 BOOMERANG flight. Since these two plots are related, it can be useful to zoom and scroll them simultaneously. Click on the squares located at the top right corners of the two plots. They should turn dark in colour to indicate that the two plots are now tied together:

Tied Zoom
Tied Zoom

Before we try zooming in, we should delete all plots other than the two we are working with. Select Layout Mode from the Plots menu or click the toolbar button. For each plot other than the two we want to keep, right-click on the plot and select Delete. Then, right-click anywhere inside the current window and select Cleanup Layout. Now the two plots should share maximal space inside the window. Return to XY Mouse Zoom mode when you are done.

Now try zooming in on any portion of the upper plot. You will find that the lower plot will become blank. This is because the lower plot axes have changed to match the upper plot axes, and there is no data in that particular region of the lower plot. Type M while the mouse cursor is over either plot to return to maximum zoom on both plots. Now hold down Ctrl (this is equivalent to selecting X Mouse Zoom Mode from the Plots menu or clicking the toolbar button). The mouse cursor will change shape as visual feedback. While keeping Ctrl held down, drag a rectangle in the upper plot. Note that the height of the dotted rectangle is restricted so that only the x axis will be zoomed. Now both plots will display data when zoomed in, as the y axis for either plot was not changed.

You can quickly tie or untie all the plots in the window by selecting Tied Zoom from the Plots menu or by clicking the toolbar button.

When you are finished experimenting with the zooming features, you can close &kst;. There is no need to save the plots this time (unless you wish to).

## A Brief Overview of Data Objects

There is more to &kst; than simple plotting and viewing of data. From the data wizard, you have already seen that &kst; has the ability to create power spectra of data. In fact, &kst; is also capable of creating other data objects such as histograms, equations, and plugins. A utility called the Data Manager can help you keep track of all the data objects you create.

Start &kst; with the file `demo.kst`, included in the demo package:

    kst demo.kst

Kst with demo.kst
Kst with demo.kst

This &kst; session contains vectors and other data objects created from data in `gyrodata.dat`. The top plot contains the azimuth data, the middle plot contains the pitch data in blue, and the bottom plot shows the power spectrum of the pitch data in blue. Let us first examine the plots more closely. Tie the top two plots together using the techniques you learned in the previous section. Then hold down Ctrl to enter X Mouse Zoom mode. Now zoom in on a small region of the top plot (say from 50000 to 53000), to cause both tied plots to zoom. You will notice that the the blue pitch curve is negatively correlated with the red azimuth curve. This is because the pitch gyro was slightly rotated relative to the azimuth axis (by -0.69 degrees). The true pitch `p'` is:

where `p` is the original pitch, is the rotation of the pitch gyro relative to the azimuth axis, and `a` is the azimuth gyro. `p'` is plotted as the black curve in the middle plot. The power spectrum of `p'` is the black curve in the bottom plot.

Now let us take a look at how the three plots were created. To display the Data Manager, select Data Manager... from the Data menu, or click the toolbar button:

The Data Manager
The Data Manager

The Data Manager contains the definitive list of data objects in the current &kst; session. It also allows you edit or create new data objects. As you can see, there are three curves (each created from a pair of vectors), one equation, two power spectra, and four data vectors listed. Right-click on C2-GY_PITCH and select W1-P1 from the Remove From Plot submenu. This removes the curve from plot P1 in window W1. Also remove PSD2-V3-GY_PITCH from plot P3 in window W1 using the same procedure. Now only the corrected curves should be displayed in the plots:

Corrected Curves Only
Corrected Curves Only

To see how the corrected pitch gyro was created, highlight C4-cleaned_pitch and click the Edit button. The Edit Equation dialog should be displayed:

Edit Equation
Edit Equation

Note that the equation used to calculate `p'` was entered in the Equation text box (an approximation of 1 was used for `cos(-0.69)`). Feel free to experiment with the settings in this dialog. Click OK (to save any changes made) or Cancel when you are done.

Note that all data objects have a number listed under the # Used column. This number indicates the number of times the data object is either used by other data objects or by plots. Since we removed a curve and a power spectrum, at least two data objects should have 0 listed under this column. Click Purge to permanently remove all unused data objects.

Click Close to close the Data Manager. You can exit &kst; now if you wish.

## A Look at Plugins and Events

We end our journey through &kst; by looking at two specific data types—plugins and event monitors.

A plugin is a flexible data object whose behaviour depends entirely on the specific plugin file selected. The plugin file can be one that is included with the standard &kst; distribution, or it can be a third-party plugin file. In fact, the Kst Handbook includes instructions on how to write and compile custom plugin files. Plugins allow &kst; to perform arbitrary operations on a set of data, as the only requirements for a plugin file are that they receive a set of input vectors and scalars, and output a set of vectors and scalars.

As an example, we will try fitting a simple line to a small set of data points. Start &kst; with a plot of the first field of the `maxima.dat` data file included in the demo package:

    kst -y 1 -d maxima.dat

The `d` option specifies that only points should be plotted, not lines. The plot of data points should now be displayed:

Plot of Data Points
Plot of Data Points

Now, open the Data Manager. Click Plugin... in the New section to create a new plugin object. Under Plugin Selection, select the Fit linear plugin. This particular plugin requires two input vectors—one containing the x values and one containing the y values of the data points to be fitted. Select V1-INDEX for Input Vector - X Array, and V2-1 for Input Vector - Y Array. Then, click OK. You will notice that the new plugin object has created slave vectors to store its outputs. Click on Curve... to create a new curve from the output vectors. Select V1-INDEX for X axis vector and P1-kstfit_linear_unweighted-Y Fitted for Y axis vector. We want to place the curve on top of the data points in the existing plot, so under Curve Placement, select Place in existing plot and deselect Place in new plot. Finally, click OK to create the curve. Close the data manager to view the fitted line:

Fitted Line
Fitted Line

A procedure similar to the one you have just followed will allow you to create and plot the outputs of any type of plugin object. However, there is a shortcut for creating fit plugins. Right-clicking on a plot will display the context menu, which contains a Fit... submenu. Selecting a curve from the submenu will bring up the Fit Function dialog with the x and y vectors preselected. After the fit plugin is selected, a click of the OK button will create the plugin object, create the curve from the plugin outputs, and place the curve on the existing plot.

Let us now take a look at events. Event objects usually monitor other vectors or scalars and perform specified actions when certain conditions involving those vectors or scalars are true. Click EventMonitor... in the New section of the Data Manager to create a new event:

Event Monitor
Event Monitor

Suppose that the pitch gyro data was being updated in real time, and that we wanted to be notified whenever the corrected pitch gyro falls outside the range `[-0.60, -0.40]`. To set up the event in this manner, enter the following in the Expression textbox:

`[C4-cleaned_pitch-sv]>(-0.40) | [C4-cleaned_pitch-sv]<(-0.60)`

Note that anything entered as an expression must be a boolean expression. This particular expression will evaluate to true whenever either of the inequalities is true. Select both Log as and Notify, and enter in your email address to the right of the Notify checkbox. Click OK, and the event will be created.

Now select Debug Kst... from the Help menu. Click the Log tab to view the debug log. If the event was set up correctly, you should see warnings indicating the x values for which the event was triggered. Check that the values roughly match those you would expect from looking at the plot:

Debug Log
Debug Log

If the pitch gyro data was being updated in real-time, the event monitor would be triggered for any new data when appropriate as well.

Once you are done, you can close &kst;.

## Conclusion

This concludes the &kst; tutorial. Hopefully you have gained enough knowledge to become comfortable with &kst;. Keep in mind that this tutorial does not cover all the functionality of &kst;—there is still much to explore and experiment with. The Kst Handbook, available through the Help menu of &kst;, can be your in-depth guide to concepts ranging from window layout fundamentals to creation of custom plugins and data source readers. You are encouraged to use &kst; in interesting and innovative ways—you will most likely find that it not only meets, but exceeds your needs and requirements.

## Credits and Licensing

This tutorial is based on the original &kst; Quick Tour written by Barth Netterfield.

&underFDL;