# The &kst; Tutorial

## 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;. It is based on the &kst; Quick Tour by Barth Netterfield. You are invited to further investigate any features at any time. All features are documented in the rest of this Handbook.

## 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 which are installed with &kst; in `$`KDEDIR`/share/apps/kst/tutorial`, where `$`KDEDIR`` is the location in which &kde; is installed on your system (you can find this using the command `kde-config --prefix`).

If you have a version of &kst; older than 1.1.0, you can find the tutorial data online at http://omega.astro.utoronto.ca/kst/tutorial/kst_tutorialdata.tgz. 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. Check the boxes for the 1, 2 and 3 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 supportingadditionalfileformatsdatasourceconceptsframes.

Start, Count from end, Range, 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 10,000 for Range to read only the last 10,000 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 value entered) 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. For more information on the options available for power spectra, see power-spectra.

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 [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 the high x end of this plot is almost completely flat, 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 around the interesting-looking area. 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).

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 labeled `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 color 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 six 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 C-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 behavior 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. You can find instructions on how to write and compile custom plugin files in creatingplugins.. 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 INDEX for Input Vector - X Array, and 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 Event Monitor... 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 rest of this Handbook is an 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.