Keywords: KDE, kdeextragear, kdeextragear-2, Kst, plotting, plot

# The Kst Handbook

### Rick Chern `<kst@kde.org>`

Revision 1.0.0

Copyright © 2004 The University of British Columbia

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Kst is a data plotting and manipulation program with powerful plugin support.

## Chapter 1. Introduction

## What is Kst?

Kst is a data plotting and viewing program. Some of the features include:

- Robust plotting of live "streaming" data.

- Powerful keyboard and mouse plot manipulation.

- Powerful plugins and extensions support.

- Large selection of built-in plotting and data manipulation functions, such as histograms, equations, and power spectra.

- Color mapping and contour mapping capabilities for three-dimensional data.

- Monitoring of events and notifications support.

- Built-in filtering and curve fitting capabilities.

- Convenient command-line interface.

- Powerful graphical user interface.

## Getting Started

There are two main methods of quickly obtaining plots in Kst. The Kst command-line interface provides quick access to the main Kst features, while the graphical data wizard enables intuitive fine tuning of plot and data settings.

We first need a data file. Copy and paste this simple 40-line set of data into a text file, and save it as `simpledata.dat`:

    -20 100
    -19 90.25
    -18 81
    -17 72.25
    -16 64
    -15 56.25
    -14 49
    -13 42.25
    -12 36
    -11 30.25
    -10 25
    -9 20.25
    -8 16
    -7 12.25
    -6 9
    -5 6.25
    -4 4
    -3 2.25
    -2 1
    -1 0.25
    0 0
    1 0.25
    2 1
    3 2.25
    4 4
    5 6.25
    6 9
    7 12.25
    8 16
    9 20.25
    10 25
    11 30.25
    12 36
    13 42.25
    14 49
    15 56.25
    16 64
    17 72.25
    18 81
    19 90.25
    20 100

`simpledata.dat` is an example of an ASCII data file, one of the many file types Kst is capable of reading. For further details on file types, see Supported File Formats. To produce a simple plot using the first column (or “field”) of this file an x vector, and the second column as a y vector, enter the following:

`kst -x 1 -y 2 simpledata.dat`

Kst should start with the plot displayed:

Numerous other command-line options are available—using the command-line only, plots of data can be printed directly to files, and simple data manipulation such as creation of power spectra can be performed as well. For a complete list of command-line options, see Command Line Usage and Examples.

If Kst is started without any command-line options, a QuickStart dialog is shown by default:

The QuickStart dialog provides both a convenient facility for opening previously saved Kst sessions and a shortcut to the data wizard. To open an existing Kst session, either select a file from the Recent files list, or enter a path in the textbox underneath, and click Open File. Clicking the button to the right of the textbox displays a file browser dialog that can be used to graphically browse to a Kst file. If this is your first time using Kst, you most likely will not have any saved sessions. In this case, the data wizard can be used to quickly import data and produce plots. To start the data wizard, click the Data Wizard... button. The data wizard walks through specification of a data file, selection of fields, and selection of plot options. For detailed descriptions of the data wizard options and settings, refer to the Data Wizard section.

### Tip

If you do not want the QuickStart dialog to be displayed at startup, simply uncheck Show this dialog at startup at the bottom of the QuickStart dialog. The QuickStart dialog can also be toggled by selecting Configure Kst... from the Settings menu and clicking on Show QuickStart dialog on startup.

Any plot displayed in Kst can be manipulated. For example, dragging a rectangle anywhere within a plot will zoom in to that section of the plot. Holding Ctrl or Shift while dragging will zoom in on the x or y axis only, respectively, and tapping the arrow keys scrolls a plot. See Working with Plots and Window for more details on manipulating plots and plot layout, as well as the different mouse modes.

## Chapter 2. Working With Data

## Supported File Formats

Currently, Kst supports ASCII text files, BOOMERANG frame files, and BLAST dirfile files as data sources, as well as PIOLib and FITS files with the appropriate libraries. This section describes basic data source concepts common to all file types, and specifically details the ASCII and BLAST dirfile file types.

### Data Source Concepts

A data source in Kst is simply a supported data file. The following concepts are important in understanding how Kst works with different data sources. Some terminology is also introduced in this section.

#### Samples

A sample is considered to be the fundamental unit with respect to data files. Each sample consists of one data value in the file. Note, however, that one sample may not correspond to one value in a data vector in Kst, due to the concept of frames.

#### Fields

A field usually corresponds to one vector in Kst. For example, a column in an ASCII data file is considered to be one field. Each field can have an explicit or implicit name. Datasource readers provide functions for reading and obtaining fields and field names.

#### Frames

A frame corresponds to a set number of samples, and each field in a data file can have its own ratio of samples per frame. The size of a data file is measured by the number of frames it contains. For ASCII data files, the number of samples per frame is 1, but for some data files, there may be multiple samples per frame. In the below illustration, the first 3 frames of an imaginary data file are shown. In this particular data file, Field 1 has a ratio of 5 samples per frame, Field 2 has a ratio of 2 samples per frame, Field 3 has a ratio of 3 samples per frame, and Field 4 has a ratio of 1 sample per frame.

Depending on the specific data vector settings in Kst, data from files may be read as frames instead of samples, with either the first sample in a frame or the mean of all the samples in a frame representing the value of the frame.

#### INDEX Field

Some data files may not have a field that represents the x axis of a plot. However, Kst implicitly creates an INDEX field for all data sources. The INDEX field simply contains integers from 0 to N-1, where N is the number of frames in the data file.

### ASCII Input Files

The simplest input file format is the ASCII text file. These files are usually human-readable and can be easily created by hand or simple scripts if desired. The following is an example of an ASCII input file.

    112.5 3776 428
    187.5 5380 429
    262.5 5245 345
    337.5 2942 184
    412.5 1861 119
    487.5 2424 138
    567.5 2520 162
    637.5 1868 144
    712.5 1736 211
    787.5 1736 211
    862.5 2172 292
    937.5 1174 377
    1000.5 499 623

Each column of this file represents a field, while each row represents one frame. Columns are separated by tabs or spaces, and rows are separated by carriage returns. Note that due to their structure, ASCII files cannot have multiple samples per frame. Also, since the columns do not have labels, field names are assigned by Kst based on the order of the columns (the leftmost column has a field name of `1`).

Commented lines in ASCII files start with one of the characters in the set `{#, !, /, ;, c}`. All commented lines and empty lines are ignored by Kst. Valid numbers include those with decimals, negative signs, or `e`, to indicate scientific notation. Invalid numbers (such as english words) are replaced with 0 by Kst.

### BLAST Dirfiles

BLAST dirfile data sources are actually directories of files. Each directory represents one data source, and each file in the directory, with the exception of a file called `format`, represents a single field. The file named `format` lists each field and its properties. Below is example of such a file:

    scount RAW f 1
    fcount RAW f 20
    sine RAW f 20
    ssine RAW f 1
    cos RAW f 20

In this example, `scount`, `fcount`, `sine`, `ssine`, and `cos` are field names. `RAW` indicates the file is written in raw format, and the last number in each row is the number of samples per frame.

When selecting a BLAST dirfile for use in Kst, the directory containing the field files should be selected. Kst will when automatically look for a `format` file, if it exists, to determine the fields and their properties.

## The Data Wizard

The Data Wizard provides a quick and easy way of creating vectors, curves, power spectra, and plots in Kst from data files. To launch the wizard, select Data Wizard... from the Data menu. You will be prompted to select a data source. Browse to a valid data file (or enter in the path to a data file) and click Next. The following window will be displayed.

Select the fields you wish to import into Kst. You may filter the list of fields by entering a string to match (wildcards such as `*` are supported) into the text box above the list.

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”. For a detailed description of this concept, see File Formats.

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. For example, to read from frame 10 to frame 900, enter `10` for Starting frame and `890` for Number of frames. To read from frame 500 to the end of the file, enter `500` for Starting frame and select the Read to end option. To read only the last 450 frames from the file, select the Count from end option and enter `450` for Number of frames. The combinations used in the previous two examples are often useful for reading data from a file that is being updated in real time. Subsequent additions to the file are read, causing associated vectors to be updated as well.

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 The value of the 1 sample that is used to represent a frame depends on whether or not Boxcar filter first is selected. If Boxcar filter first is not selected, the value is the same as the value of the 1st sample in the frame. If Boxcar filter first is selected, the value is the mean (average) of all the samples in that particular frame.

Power Spectrum and X axis settings can be specified within the Plot Types section. These settings are described below.

XY, Power Spectrum, and XY and Power Spectrum

  Select whether to plot the power spectrum only, data (XY) only, or both. If the power spectrum is selected for plotting, additional settings in this section become available.

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. The INDEX vector is simply a vector containing elements from 0 to N-1, where N is the number of frames in the data file.

The FFT Options subsection in the Plot Types section is available only if a power spectrum is to be plotted. The below definitions assume basic knowledge of power spectra—for further details, refer to Numerical Recipes in C: The Art of Scientific Computing, published by Cambridge University Press.

Interleaved average and FFT Length

  The power spectrum is defined as “the square root of the absolute value of the mean of the interleaved Fast Fourier Transforms of length `2^x`”, where x is the value entered in the FFT Length selection box. Selecting Interleaved average allows the length of the interleaved Fast Fourier Transforms to be specified. If Interleaved average is unchecked, Kst will determine the length based on the length of the vector.

Data units and Rate units

  The units specified in these textboxes are used for the purpose of auto-generating axes labels for the plots.

Sample rate

  The sample rate is used to generate the X axis of power spectrum plots.

Appodize

  If this option is selected, the data is appodized using a Hanning window, to reduce bin-to-bin leakage.

Remove Mean

  Select this option to remove the mean from the selected data (i.e. translate the data so that the mean is zero).

Once you are satisfied with all the settings, click Next to advance to the next window. Select any filters you wish to apply to the data, and click Next to advance to the final window.

From here, you can change general plotting settings. Most of the settings are self-explanatory. A brief overview of each section is provided below.

Curve Style

  Select whether to plot data points only, lines connecting the data points only, or both. By default, lines are continuous with weight 0, and data points are marked using crosses. Line and data point colours are chosen so that curves with identical colours are minimized. Note that the curve style settings apply to both Power Spectra and XY plots.

Curve Placement

  Select the plots to place the new curves on. Cycle through distributes the curves on the plots by cycling through the plots. Note that the curve placement settings apply to both Power Spectra and XY plots.

Label Generation

  Select the desired labels and legends to be placed on the plots.

Plot Placement

  Select the desired window(s) to place the new plots on. New windows can be created for the plots by selecting In new window.

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

## The Data Manager

The Data Manager provides a central location for adding, deleting, and modifying all the data objects used in Kst. It can be accessed by selecting Data Manager from the Data menu.

### Creating New Data Objects

To create a new data object from the Data Manager, click on one of the buttons listed under New:. A new window will be displayed, allowing options and settings for the data object to be set.

### Tip

You can also create new curves by right-clicking on a vector and choosing Make Curve...

Since you are creating a new data object, you may enter a unique name to identify the object. The default name can be used as well (if it is unique).

The settings for all plottable data objects except images have two common sections—Appearance and Placement (images only have the Placement section). These sections are described below. For data-specific settings, see Data Types.

#### Appearance

The Appearance section allows you to change the appearance of the data object when it is plotted.

  Clicking this button displays a colour chooser dialog box, which can be used to change the colour of both the lines and points.

Show points

  Selecting this checkbox shows the data points used to plot the data object. The drop-down list to the right allows the shape of the points to be changed.

Show lines

  Selecting this checkbox shows the lines joining the data points for the data object. The thickness of the line as well as the line style can be changed.

#### Placement

The Placement section specifies the plotting location of new plottable data objects.

Plot window

  Specify the window in which to plot the data object. You may create a new window by clicking the New... button.

Place in existing plot, Place in new plot and Do not place in any plot

  You can choose whether or not to immediately plot the data object on a new or existing plot. If Place in new plot is selected, you can also choose to re-arrange the layout of the plots by selecting re-grid and entering the number of columns to use for the new layout grid.

Once all the desired settings for the new data object have been set, click the OK button to create the new data object.

### Editing and Deleting Existing Data Objects

To edit an existing data object, simply highlight it in the Data Manager window and click the Edit button. The settings window for the selected object will be displayed. This window is identical to the one displayed when creating new data objects (with the exception that the Placement section may be absent), so refer to Creating New Data Objects for more information on the settings and options.

To delete a data object, highlight it in the Data Manager window and click the Delete button. Note that the entry in the # Used column for an object must be 0 before the object can be deleted. The # Used column indicates the number of times that a particular data object and its children (if any) are used by either other data object or by plots. Listed below are some consequences of this restriction to keep in mind when attempting to delete data objects.

- All plottable objects (curves, equations, histograms, power spectra, and images) must be removed from plots before they can be deleted. An object can be removed from a plot by right-clicking on it in the Data Manager window and selecting the desired plot from the Remove From Plot submenu.

- All data objects that use a particular data vector must be deleted before the data vector can be deleted.

- All children of a parent data object must be unused before the parent data object can be deleted.

After a sequence of deletions and removals of plottable data objects from plots, you may find that there are numerous unused data objects displayed in the Data Manager. To quickly remove these objects, you can click the Purge button.

## Data Types

There are nine main types of data objects in Kst. Data objects can contain other data objects, as represented by the tree structure view in the Data Manager. The following diagram illustrates the relationships between the different data types.

As can be seen from the above diagram, the curve, equation, histogram, power spectrum and image data objects are the only data objects that are plottable. All data objects (other than vectors) have the capability of using vectors, while equations, power spectra, events, and plugins all contain slave vectors.

Descriptions of each data type are provided below, along with overviews of the settings and options available when creating or editing each type of data object. Settings common to almost all data types have been omitted—see Creating New Data Objects for more information.

### Vectors

Vectors are one of the most often-used data objects in Kst. As their name implies, vectors are simply ordered lists of numbers. Most often they contain the x or y coordinates of a set of data points.

As vectors can be potentially quite large, it is a good idea to be aware of the amount of memory Kst has allocated for use. The current available memory is displayed in the lower right corner of the status bar of the main Kst window.

### Tip

If the status bar is not available, ensure that Show Statusbar is checked in the Settings menu.

The following is a screenshot of the window displayed when creating or editing vectors. Explanations of the settings are listed below.

#### Data Vector Parameters

The source file and field to read can be set using the following options.

File name

  The path to the desired data file. Clicking the button to the right displays a file browser window that can be used to graphically browse to the file.

Field or column

  The field or column to create a vector from.

#### Data Range

This section specifies the range of data to use from the selected field for the data vector.

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. For example, to read from frame 10 to frame 900, enter `10` for Starting frame and `890` for Number of frames. To read from frame 500 to the end of the file, enter `500` for Starting frame and select the Read to end option. To read only the last 450 frames from the file, select the Count from end option and enter `450` for Number of frames. The combinations used in the previous two examples are often useful for reading data from a file that is being updated in real time. Subsequent additions to the file are read, causing associated vectors to be updated as well.

Read 1 sample per 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 is not selected, all samples in the selected range will be read. If Read 1 sample per is selected, only 1 sample per `N` frames will be read, where `N` is the number entered in selection box to the right. The value of the 1 sample that is used to represent a frame depends on whether or not Boxcar filter first is selected. If Boxcar filter first is not selected, the value is the same as the value of the 1st sample in the frame. If Boxcar filter first is selected, the value is the mean (average) of all the samples in that particular frame.

### Curves

Curves are primarily used to create plottable objects from vectors. Curves are created from two vectors - an “X axis vector” and a “Y axis vector”, that presumably provide a set of data points. Thus, a curve can be thought of as a set of data points and the lines that connect them (even though the points or lines may not be visible on plots).

The following is a screenshot of the window displayed when creating or editing curves. Explanations of the settings are listed below.

#### Curve Contents

The contents of the curve can be set from this section.

X axis vector

  The vector to use for the independent (horizontal) axis.

Y axis vector

  The vector to use for the dependent (vertical) axis.

X error bar and Y error bar

  The vectors containing error values corresponding to the X axis vector and Y axis vector, respectively. The vectors should contain the sizes of the error bars in the same order as the data points.

### Equations

An equation data object consists of a mathematical expression and an independent variable. The expression is built using a combination of scalars, vectors, and operators, and usually represents the values of the dependent variable. The independent variable can be an existing vector or it can be generated when the equation object is created or edited. Since an equation ultimately consists of a set of data points, an equation object is plottable.

The following is a screenshot of the window displayed when creating or editing equations. Explanations of the settings are listed below.

#### Equation

The mathematical expression representing the dependent variable can be modified from this section.

Operators

  A list of available operators. Choosing an operator from the list inserts the operator at the current insertion point in the Equation text box.

Vectors

  A list of the current vector objects in Kst. Choosing a vector from the list inserts the vector at the current insertion point in the Equation text box.

Scalars

  A list of the available scalar values. This list is composed of both the scalar values in the current Kst session as well as some built-in constants. Choosing a scalar from the list inserts the scalar at the current insertion point in the Equation text box.

Equation

  The mathematical expression representing the independent variable. You may manually type in this text box or you may select items to insert using the above drop-down lists.

#### Independent Variable

This section is used to specify the source of the values for the independent variable.

Use

  Select this option to use an existing vector as the independent variable. Select a vector from the drop-down list, or quickly create a new one by clicking the button to the right.

Interpolate to highest resolution vector

  Selecting this option interpolates the selected vector to the greatest number of samples possible.

Generate

  Select this to generate a set of values to use as the independent variable. Specify the lowest value to generate in the From field, and the highest value to generate in the to field. Set the value for Number of samples to be the number of equally spaced values to generate between the lowest value and the highest value (inclusive).

### Histograms

A histogram data object simply represents a histogram of a particular vector. Histogram objects are plottable.

The following is a screenshot of the window displayed when creating or editing histograms. Explanations of the settings are listed below.

#### Histogram Properties

The source vector, as well as basic histogram properties, can be modified from this section. You can either manually specify settings or use the Auto Bin button.

Data vector

  The data vector to create the histogram from. Although a vector is needed to create a histogram, the vector is treated as an unordered set for the purposes of creating a histogram.

From and to

  The From field contains the left bound for the leftmost bin in the histogram. The to field contains the right bound for the rightmost bin in the histogram.

Num bins

  Enter the total number of bins to use in the Num bins field.

Auto Bin

  Instead of specifying values for From, to, and Num bins, you can click Auto Bin to automatically generate values for all three fields based based on the lowest and highest values, as well as the number of elements found in the source vector.

#### Y Axis Normalization

This section is used to specify the type of normalization used for the y axis of the histogram.

Number in bin

  Selecting this option causes the y axis to represent the number of elements in each bin.

Fraction in bin

  Selecting this option causes the y axis to represent the fraction of elements in each bin out of the total number of elements.

Percent in bin

  Selecting this option causes the y axis to represent the percentage of elements (out of the total number of elements) in each bin.

Peak bin = 1.0

  Selecting this option causes the y axis to represent the number of elements in each bin divided by the number of elements in the largest bin (the bin with the greatest number of elements). In other words, the y axis is normalized to 1.0.

### Power Spectra

A power spectrum data object represents the power spectrum of a vector, defined as “the square root of the absolute value of the mean of the interleaved Fast Fourier Transforms of length `2^x` of the vector”, where x is the value entered in the FFT Length selection box. The below definitions assume basic knowledge of power spectra—for further details, refer to Numerical Recipes in C: The Art of Scientific Computing, published by Cambridge University Press.

#### Curve Contents

The source vector, as well as basic power spectrum properties, can be modified from this section.

Data vector

  The data vector to create a power spectrum from.

Interleaved average and FFT Length

  Selecting Interleaved average allows the length of the interleaved Fast Fourier Transforms to be specified. The length is specified as a power of 2. If Interleaved average is unchecked, Kst will determine the length based on the length of the vector.

Data units and Rate units

  The units specified in these textboxes are used for the purpose of auto-generating axes labels for the plots.

Sample rate

  The sample rate is used to generate the X axis of power spectrum plots.

Appodize

  If this option is selected, the data is appodized using a Hanning window, to reduce bin-to-bin leakage.

Remove Mean

  Select this option to remove the mean from the selected data (i.e. translate the data so that the mean is zero).

### Plugins

A plugin data object represents a Kst plugin. All plugins have a common format, and show up as type “Plugin” in the Data Manager. For more information about plugins, please see Plugins and Filters

### Event Monitors

An event monitor data object represents an instance of an event monitor. For more information on monitoring of events, see Event Monitoring.

### Matrices

A matrix represents a set of three-dimensional data points (x, y, z) arranged in a two-dimensional grid. The z values of the matrix are obtained from a vector, and the grid structure is manually specified using the Edit or New Matrix dialog. The descriptions below refer to the following diagram depicting Kst's matrix structure.

A screenshot and explanation of the matrix dialog follow.

#### Vector Selection

Z Vector

  The data vector to obtain the z values from.

#### Grid Parameters

X Minimum and Y Minimum

  The origin of the matrix is specified by the coordinates (X Minimum, Y Minimum). The location of the origin is represented by a red circle in the above diagram.

X Step Size and Y Step Size

  These two values specify the dimensions of each rectangular cell in the matrix grid. All cells in the matrix have identical dimensions.

Dimensions and Use maximum x length

  Enter the number of steps for the x dimension of the matrix, followed by the number of steps for the y dimension of the matrix. If Use maximum x length is checked, the x dimension of the matrix will be determined based on the length of the vector and the entered y dimension. If this option is checked and the length of the vector subsequently changes, the x dimension of the matrix will be updated accordingly.

  Note that the minimum allowed y dimension is 1, while the minimum allowed x dimension is 0.

### Images

Images are graphical representations of Matrices. Images can be plotted as color maps, contour maps, or both.

#### Matrix Selection

Matrix

  Select the matrix to use for this image. New matrices can be created by clicking on the button to the right.

#### Image Type

Color Map, Contour Map, and Color Map and Contour Map

  Select the type of image to be plotted. Changing this selection enables or disables sections of the image dialog as appropriate.

#### Color Map Parameters

A color map represents the z value of each cell in the matrix using a color. This section is only available if Color Map or Color Map and Contour Map is selected under Image Type.

Color palette

  Select the color palette to use for the color map. By default, two palettes suitable for color maps are installed by Kst—Kst Grayscale 256 (a 256 color grayscale palette) and Kst Spectrum 1021 (a 1021 color rainbow spectrum that ranges from blue to red). Additional palettes can be installed by simply copying GIMP compatible palette files to the `colors` subdirectory of the user configuration directory (for example, `/usr/share/config/colors/`). Note that saved images using a non-default palette may not be viewable by other users of Kst if they do not have the required palette. In such cases, a default grayscale palette is used instead.

Lower Z threshold, Upper Z threshold and Auto Threshold

  Enter the lower and upper thresholds to use for the mapping of colors. Palette colors are evenly distributed between Lower Z threshold and Upper Z threshold. Any cells in the selected matrix with z values less than Lower Z threshold are mapped to the first color in the palette. Any cells in the selected matrix with z values greater than Upper Z threshold are mapped to the last color in the palette. Clicking Auto Threshold will fill in the lower and upper threshold values using the least and greatest z values found in the selected matrix.

#### Contour Map Parameters

A contour map draws a set of lines, with each line representing a certain z value. This section is only available if Contour Map or Color Map and Contour Map is selected under Image Type.

Number of contour levels

  Select the number of contour levels to use. The contour levels will be distributed evenly between the lowest and highest z values found in the matrix.

Color

  Select the color to use for the contour lines. Clicking this button displays a standard KDE color chooser dialog.

Weight and Use variable line weight

  Select the weight, or “thickness” of the contour lines. If Use variable line weight is selected, contour lines representing higher elevations are drawn thicker than those representing lower elevations. Use discretion when selecting this option, as images with high contour line densities may become unreadable.

## The Data Menu

The Data menu provides quick access to many features related to data objects in Kst. Most of the menu functions duplicate functions found elsewhere, so only brief descriptions are provided below.

Reload

  Reloads all data vectors from their source files.

Data Wizard...

  Displays the Data Wizard.

Data Manager

  Displays the Data Manager.

New [data object]

  Displays the corresponding dialog for creating the data object. Refer to Data Types for descriptions of each dialog.

View Scalars

  Displays a dialog from which the values of all the scalars in the current Kst session can be viewed. The dialog is updated dynamically if the values change.

View Vectors

  Displays a dialog from which the values in all the current vectors can be viewed. Select a vector to view using the drop-down list. The dialog is updated dynamically if the values change.

View Fit Results

  Displays a dialog which shows all the resulting values from performed fits. Select a fit result to view using the drop-down list. The dialog is updated dynamically if the values change.

Change Data File

  Displays a dialog for quickly changing data files that vectors are associated with. Select the vectors to change, and then browse to a different data file. Click Apply to save the changes.

## Chapter 3. Working with Plots and Windows

This chapter details the concepts behind plots and windows, and provides information on viewing and manipulating the layout of plots and windows in Kst. The following diagram illustrates the relationships between windows, plots, and plottable data objects.

As can be seen from the above diagram, each window in Kst can contain zero or more plots, and each plot can contain zero or more plottable data objects.

## The Plot Dialog

The plot dialog provides a central location for managing plots. To access it, select Edit Plots from the Plots menu. At the top of the dialog box you should see two drop-down lists:

To modify a plot, select the window that contains the plot from the left drop-down list, and select the plot itself from the right drop-down list. New windows can be created by clicking the button in the middle.

At the bottom of the plot dialog are four buttons. Delete deletes the currently selected plot, Apply as New applies the current plot settings to a new plot, Apply Edits applies the plot settings to the currently selected plot, and Close closes the plot dialog without applying or saving any settings.

The plot settings available on each tab of the plot dialog are described below.

### Content

Below is a screenshot of the Content tab.

As the name implies, the settings on this tab specify the content of the plot. The following are brief explanations of the settings.

Unique plot name

  The unique plot name is the identifier for the plot. There cannot be duplicate plot names.

Displayed objects and Available objects

  Displayed objects lists the plottable data objects that should be plotted in the plot. Available objects lists all the current plottable data objects in Kst that are not in the Displayed objects list. To move an item from one list to the other, first highlight the desired item, and click the appropriate arrow button in between the two lists (the left arrow to move a item from Available objects to Displayed objects, and the right arrow to move a item from Displayed objects to Available objects). Alternatively, dragging and dropping the items works as well.

Foreground and background colors

  Select the foreground and background colors to use for this plot using the standard KDE color chooser. The upper left box indicates the foreground colour, while the lower right box indicates the background colour. To edit a colour, double-click on the desired box, and a standard colour chooser dialog will appear. Click to swap the foreground and background colours. If you wish to quickly switch to a white background and black foreground, click Note that the foreground color only affects the axes lines and axes labels, and is independent of any colors used to plot data objects.

Re-grid and Columns

  Check the Re-grid option to rearrange all plots in the selected window in a grid pattern with the specified number of columns.

### Axes

Below is a screenshot of the Axes tab.

The settings for the plot axes are specified on this tab. The axis settings are split into two identical sections—an x axis section and a y axis section.

Auto scale

  Select this option to let Kst automatically choose a scale for this axis based on the highest and lowest values for this axis found in the plotted objects.

Auto up

  This option behaves similarly to Auto Scale, but the upper axis limit will only increase, and the lower axis limit will only decrease.

Spike Insensitive Auto scale

  Select this option to let Kst automatically choose a scale for this axis that is based on the values found in the plotted objects. In general, “spikes”, or sudden short increases or decreases in the value, will be ignored when determining the scale.

Mean-centered

  Select this option to center the axis around the mean of the values found in the plot (x values are used to calculate the mean for the x axis, and y values are used to calculate the mean for the y axis). Specify the length of the axis in the Range text box.

Fixed

  Manually specify lower and upper limits for the axis. Enter the limits in the textboxes to the right of Range.

Logarithmic

  Enable this checkbox if you wish to use a logarithmic scale for the axis.

Major tick density, Minor ticks, and Auto minor

  Change the density value for the major ticks on this axis by using the Major tick density field. The number of major ticks on the axis will be approximately equal to the density value, with slight variations depending on the plot size and zoom level. Select the number of minor ticks to show in between major ticks using the Minor ticks field. If Auto minor is checked, the number of minor ticks is automatically determined based on zoom level.

In addition to axis ticks, grid lines can be shown on plots as well. Grid lines are drawn as thin dotted lines using the specified colors.

Show major

  Select X major to show vertical grid lines corresponding to the x axis major tick marks. Select Y major to show horizontal grid lines corresponding to the y axis major tick marks. The color of both types of major lines can be specified by clicking the button next to Color.

Show minor

  Select X minor to show vertical grid lines corresponding to the x axis minor tick marks. Select Y minor to show horizontal grid lines corresponding to the y axis minor tick marks. The color of both types of minor lines can be specified by clicking the button next to Color.

### Labels

Below is a screenshot of the Labels tab.

Settings for the plot labels can be specified on this tab. Brief descriptions of the settings are provided below.

Current scalar list

  A list of the current scalars defined in Kst. This list is primarily used to quickly insert values in the label texts. Choosing an item from this list will insert the item at the current text cursor position.

Top label

  The label located at the top of the plot. Select a font size and enter the text for the label using the controls in this row.

Y axis

  The label located vertically next to the y axis of the plot. Select a font size and enter the text for the label using the controls in this row.

X axis

  The label located vertically next to the x axis of the plot. Select a font size and enter the text for the label using the controls in this row.

Numbers, X angle and Y angle

  The numbers used to label both the x axis and the y axis of the plot. The size and angles of the numbers can be specified. Positive angles rotate the text clockwise, while negative angles rotate the text counter-clockwise.

Font family

  The font used for all labels of the plot. Select an available font using the drop-down list.

Also Apply Font and Angle Settings To

  Select the plots to which the specified label settings (except Label Text) should be applied.

  ### Note

  If All other plots or All other plots in this window is selected, previous label settings for the affected plots will be lost.

Auto Label

  Click this button to automatically generate label texts for all labels on the plot. The text for Top label will be a list of paths to the data files used in the plot. The text for Y axis will be a list of the dependent variable descriptions (e.g. “Number in Bin” for a histogram). The text for X axis will be the name of the vector used as the independent variable.

Labels (preview)

  The preview image at the bottom of the Labels tab provides previews of all four labels at 100% zoom.

### Legend

Below is a screenshot of the Legend tab.

Legend settings for the plot can be specified on this tab; most of these settings concern the appearance of the legend. The legend itself is optional.

Show legend

  This option enables or disables the legend for the plot. If you wish to use a legend, you must select this checkbox.

Display in legend box

  Select this option to display a border around the legend. Selecting this option also allows the background of the legend to be set using the color chooser located on this tab.

Alignment

  The horizontal (left and right) alignment of the items in the legend. The available settings in the drop-down list are Right, Center, and Left.

Font family

  The font to use for the legend text. Select a font from the drop-down list.

Font size

  The size of the legend text. Note that the size is not specified in points, but is relative to a default size of 0.

Colors

  This widget can be used to specify the colour of the legend text. The upper left box indicates the foreground colour, while the lower right box indicates the background colour (applicable only if Display in legend box is checked). To edit a colour, double-click on the desired box, and a standard colour chooser dialog will appear. Click to swap the foreground and background colours. If you wish to quickly return to the default colours, click

Also Apply Settings To

  Select the plots to which the specified legend settings should be applied.

  ### Note

  If All other plots or All other plots in this window is selected, previous legend settings for the affected plots will be lost.

Legend (preview)

  The image at the bottom of this tab provides a preview of the legend text at 100% zoom. Among other things, the preview can be useful in determining appropriate font sizes.

### Markers

Below is a screenshot of the Markers tab.

Plot markers provide an easy means of flagging areas of interest on a plot. The Markers tab provides full access to plot marker settings and options. Navigation functions for plot markers are described in the Scroll Menu section.

### Tip

To quickly create plot markers on a plot, place the mouse cursor over the plot and press the Insert key. A vertical dashed line should appear indicating the position of the plot marker.

New and Add

  Use the New text field to manually enter a plot marker value. Values can be entered in floating point or scientific notation. Values in scientific notation must be entered in the form `mEx` or `mex`, where `m` is the mantissa and `x` is the exponent. For example, one way to enter the value 15000 in scientific notation is by typing `1.5e4`.

  Click the Add button to create a new plot marker with the specified value. You will be warned if duplicate plot markers already exist, or if the entered value is not valid. Note that plot marker additions or removals made from the Markers tab are not applied unless the plot dialog settings are applied.

Defined plot markers, Remove, and Remove All

  The list of existing plot markers for this plot are listed under Defined plot markers. To remove plot markers, highlight the desired markers in the list and click the Remove button. Multiple markers can be selected for removal by clicking and dragging within the list, or by holding down the Shift or Ctrl key and clicking on items in the list. To remove all plot markers for this plot, click the Remove All button. Note that plot marker additions or removals made from the Markers tab are not applied unless the plot dialog settings are applied.

Automatic Marker Generation

  In addition to individually defining plot markers, curves, equations, power spectra, and histograms can be used to automatically generate plot markers as well. To use one of these data objects for plot marker generation, check the Use data object as marker source checkbox and select an item from the drop down list. Then select the criteria to use for creating plot markers. Selecting Rising edge causes plot markers to be created when the y value of the selected data object changes from zero to non-zero. Selecting Falling edge causes plot markers to be created when the y value of the selected data object changes from non-zero to zero. Selecting Both causes plot markers to be created on both rising edges and falling edges of the data object. In all cases, the x value of the point in the data object with the non-zero y value is used to create the new plot marker.

  If the selected data object is subsequently updated, additional plot markers will be created if necessary. However, plot markers will never be removed as a consequence of data object changes, so manually created plot markers will never be affected.

## The Plot Context Menu

When working with plots, right-clicking on any plot will bring up a context menu that provides commonly used functions. The following list provides a brief overview of the menu items, often referring to other sections of this document that describe the functions in more detail.

Delete

  Deletes the plot.

Edit...

  Brings up the Plot Dialog, with this plot selected. See the Plot Dialog section for information on the settings.

Maximize

  Expands the plot so that it takes up the entire area of the window. Uncheck this option to return the plot to its previous size.

Pause

  Pauses automatic update of live data. This menu item duplicates the functionality of Pause from the Range menu. See Working with Live Data for more information.

Zoom (submenu)

  The Zoom submenu is described in the section entitled The Zoom Menu.

Scroll (submenu)

  This menu is described in the section entitled The Scroll Menu.

Edit (submenu)

  This submenu displays a list of objects available for editing. Clicking on an object name from the submenu displays the Edit dialog for the object. Details on this dialog are available in the Curves.

Fit (submenu)

  This submenu displays a list of curves, histograms, power spectra, and equations that can be fit. Selecting a name from the submenu displays the Fit Function dialog. This dialog is similar to the plugins dialog, but displays only those plugins that perform fits. The input vectors are selected based on the data object. In addition, curve appearance properties can be changed, as the Fit function creates vectors, and curves based on the vectors.

Filter (submenu)

  This submenu displays a list of data objects that can be filtered. Selecting a name from the submenu displays the Filter Function dialog. This dialog is similar to the plugins dialog, but displays only those plugins that perform filtering. The input vector to be filtered is selected based on the curve. In addition, curve appearance properties can be changed, as the Filter function creates vectors, and curves based on the vectors.

Remove (submenu)

  This submenu displays a list of curves currently in the plot. Clicking on a curve name from the submenu removes the curve from the plot (the curve itself, however, is not removed as a data object).

## The Label Editor

The label editor allows custom labels to be placed in arbitrary locations in Kst plot windows, in addition to the fixed labels created as part of plots. To use the label editor, select Label Editor from the Plots menu. The mouse mode will change to label editor mode. To exit label editor mode, select another mouse mode (such as XY Mouse Zoom). The following sections describe the functions available when in label editor mode.

### Creating New Labels

To create a new label using the label editor, click anywhere within the x and y axes of a plot where there is not already an existing label. The label editor dialog should appear:

The following are explanations of the dialog box elements.

Scalars

  A list of scalars currently defined in Kst. Selecting an item from the dropdown list inserts the value of the item at the current cursor position in Label text.

Label text

  The text displayed by the label. You may enter text manually in this dialog and in combination with scalars selected from the Scalars dropdown list if you wish.

Font

  The font to use for the label text. Select a font from the dropdown list.

Size

  The size of the label text. 0 is the default value.

Rotation

  The number of degrees to rotate the label. Positive values rotate the label clockwise, while negative values rotate the label counter-clockwise.

Alignment

  The horizontal alignment of the label. Select one of Left, Center, or Right.

Color

  Select the color to use for the label text. Clicking the button displays the standard KDE color chooser. Selecting Use plot color uses the foreground color specified for the plot.

Once you are satisfied with the label settings, click Apply to apply the label settings without closing the label editor dialog. Click OK to apply the label settings and close the dialog. Alternatively, you can click Close to close the label editor dialog without applying any label settings.

### Editing and Deleting Existing Labels

To edit an existing label, click on the label in the plot. The label editor dialog should be displayed. You can delete the label from the label editor dialog by clicking the Delete button.

### Moving Labels

To move an existing label in label editor mode, simply drag the label to the desired location, anywhere within the plot.

## Data Mode

Data mode allows precise viewing of the data points use in a plotted data object. To toggle data mode, select Data Mode from the Plots menu. Now, when the cursor is moved over a plot, a coloured dot will indicate the closest data point to the cursor, as shown in the screenshot below. The status bar will display the coordinates of the data point (in terms of the x and y vectors used to plot the data object) in status bar at the lower right corner of the Kst window. The status bar will also display the x, y, and z coordinates of any visible image. If images overlap, only the coordinates of the topmost image will be displayed. Note that all zooming functions are still available while in data mode.

### Tip

If the status bar is not visible, make sure Show Statusbar is checked in the Status menu.

## Zooming and Scrolling

Zooming and scrolling in plots is easy and intuitive with Kst. The following sections explain the different zooming and scrolling modes.

### Mouse Zoom Modes

To access the different zoom modes, choose one of XY Mouse Zoom, X Mouse Zoom, or Y Mouse Zoom from the Plots menu. The different modes are described below.

#### XY Mouse Zoom

In XY Mouse Zoom mode, you can zoom into a specific rectangular area of the plot by simply clicking and dragging to draw a rectangle where desired. The x and y axes of the plot will change to reflect the new scale. This mode is often useful for quickly looking at an interesting area of the plot without having to specify exact axis scales.

#### X Mouse Zoom

In X Mouse Zoom mode, the y axis is fixed. Zooming in is performed by clicking and dragging a rectangular area; however, the upper and lower limits of the rectangle will always be equal to the current upper and lower limits of the y axis. This mode is often useful for looking at a certain time range, if the x axis happens to represent a time vector.

### Tip

You can quickly switch to X Mouse Zoom mode by holding down Ctrl. The mouse cursor will change to indicate the new mode. Releasing Ctrl will return you to the previous mouse zoom mode.

#### Y Mouse Zoom

In Y Mouse Zoom mode, the x axis is fixed. Zooming in is performed by clicking and dragging a rectangular area; however, the left and right limits of the rectangle will always be equal to the current left and right limits of the x axis. This mode is often useful for zooming in on data that is concentrated around a horizontal line.

### Tip

You can quickly switch to Y Mouse Zoom mode by holding down Shift. The mouse cursor will change to indicate the new mode. Releasing Shift will return you to the previous mouse zoom mode.

### The Zoom Menu

The Zoom menu can be accessed by right-clicking on a plot and selecting the Zoom submenu from the context menu. A list of zoom actions and their corresponding keyboard shortcuts will be displayed. These actions are described below.

Zoom Action | Keyboard Shortcut | Description
--- | --- | ---
Zoom Maximum | M | Sets both the x axis and the y axis scales so that all data points are displayed. This is equivalent to the AutoScale setting of the Plot Dialog.
Zoom Max Spike Insensitive | S | Sets both the x axis and the y axis scales so that most data points are displayed. Spikes, or sudden increases or decreases in x or y values, are excluded from the plot display.
Zoom Previous | R | Returns to the most recent zoom setting used.
Y-Zoom Mean-centered | A | Sets the Y axis so that the mean of the y values in the plot is centered vertically. The actual zoom level is not changed.
X-Zoom Maximum | Ctrl+M | Sets the x axis scale such that the x values for all data points are between the minimum and maximum of the x axis. The y axis scale is unaltered.
X-Zoom Out | Shift+Right | For a non-logarithmic x axis, increases the length of the x axis by a factor of approximately 0.5, without changing the midpoint of the x axis. The y axis scale is unaltered.
X-Zoom In | Shift+Left | For a non-logarithmic x axis, decreases the length of the x axis by a factor of approximately 0.5, without changing the midpoint of the x axis. The y axis scale is unaltered.
Toggle Log X Axis | G | Enables or disables using a logarithmic scale for the x axis.
Y-Zoom Maximum | Shift+M | Sets the y axis scale such that the y values for all data points are between the minimum and maximum of the y axis. The x axis scale is unaltered.
Y-Zoom Out | Shift+Up | For a non-logarithmic y axis, increases the length of the y axis by a factor of approximately 0.5, without changing the midpoint of the y axis. The x axis scale is unaltered.
Y-Zoom In | Shift+Down | For a non-logarithmic y axis, decreases the length of the y axis by a factor of approximately 0.5, without changing the midpoint of the y axis. The x axis scale is unaltered.
Toggle Log Y Axis | L | Enables or disables using a logarithmic scale for the y axis.

Many of the zoom actions are best used in conjunction with the various mouse zoom modes.

### Match Axis

To quickly change the axes of a plot to match those of another plot, right-click on the plot and select a different plot name from the Match Axis... menu. Both the x and y axes scales of the current plot will change to match those of the selected plot. Note that this does not permanently tie the axes scales together; changing the zoom on either plot will unmatch the axes scales again. To tie the axes scales of two or more plots together, use the Tied Zoom feature.

### The Scroll Menu

Functions for scrolling a plot are available by right-clicking a plot and selecting the Scroll submenu from the context menu. Most scrolling functions and their keyboard shortcuts should be self-explanatory. To quickly jump to a plot marker, select Next Plot Marker (to jump right) or Previous Plot Marker (to jump left). For more information on plot markers, see the Markers section.

Assuming non-logarithmic axis scales are used, each function scrolls the plot in the indicated direction by 0.1 of the current length of the x axis (when scrolling left or right), or 0.25 of the current length of the y axis (when scrolling up or down).

### Tip

You can also scroll left or right in a plot by using the mouse wheel (if available).

### Tip

To quickly go forwards or backwards along the x axis, select Back 1 Screen or Advance 1 Screen from the Range menu. The keyboard shortcuts, Ctrl+Left and Ctrl+Right respectively, can be used as well.

### Tied Zoom

When looking at two or more related plots (for example, two curves on separate plots both dependent on the same time vector), it can sometimes be useful to zoom or scroll the plots simultaneously. This is possible using Kst's tied zoom feature. To activate tied zoom, click the small square at the top-right corner of the plots you wish to tie together. The squares will change colour to indicate the plots are tied, as shown below.

Zooming and scrolling actions performed on one plot in a group of tied plots will be performed on on all the plots in the group. To remove a plot from the tied group, simply click on the small square at the top-right corner of the plot again. The square will become transparent to indicate that the plot is not tied.

### Tip

To quickly tie or untie all plots (including plots in other windows), select Tied Zoom from the Plots menu, or the corresponding icon on the Kst toolbar.

### Working with Live Data

Kst features special zooming and scrolling functions designed to make it easy to work with “live” data, or data that is being updated while Kst is running. These features are designed to be used in conjunction with the regular zooming and scrolling functions.

#### Updating Plots Automatically

To have a plot automatically update as data is being added to a data file, choose Read From End from the Range menu. The plot will automatically scroll to the right periodically, to display new data points. The update interval can be changed by selecting Configure Kst... from the Settings menu. Specify the update interval in the Plot Update Timer field.

#### Pausing Plot Updates

To pause automatic updating of plots, select Pause from the Range menu. You can still perform zooming and scrolling functions while the updating is paused. Selecting Read From End from the Range menu will resume automatic updating.

#### Changing Data Sample Ranges

To quickly change sample range settings associated with vectors, select Change Data Sample Ranges from the Range menu. Select one or more vectors, change the desired settings for the vectors, and click Apply to save the settings. These settings are a subset of those found in the Edit Vectors dialog.

## Manipulating Plot Layout

Plots in a Kst window are arranged in layers. Each plot is positioned on one layer, and each layer contains one plot. Thus, plots can overlap, with plots in higher layers taking precedence in visibility over those in lower ones. To change the layout of plots in Kst, layout mode must be activated. Layout mode can be toggled by selecting Layout Mode from the Plots menu.

### Layout Mode Context Menu

While layout mode is activated, right-clicking on any plot displays a modified context menu. The selections available in this menu are listed below.

Delete

  Deletes the plot.

Raise

  Raises the plot one layer up.

Lower

  Lowers the plot one layer down.

Raise to Top

  Raises the plot to the top-most layer, guaranteeing it will be visible.

Lower to Bottom

  Lowers the plot to the bottom-most layer.

Rename...

  Selecting this item displays a dialog box that allows the unique name of the plot to be changed.

Move To

  Selecting a window name from this submenu moves the plot to the window with the corresponding name.

Cleanup Layout

  Arranges the plots in the current window in a tile type pattern, with no overlap between plots. This action applies to all plots in the current window.

### Moving and Resizing Plots

Moving and resizing plots in layout mode is analogous to moving and resizing regular windows. To move a plot, simply click anywhere on the desired plot and drag the plot. An outline of the plot will appear, indicating where the plot will be placed. You can drag plots anywhere within the current window. To resize a plot, move the mouse cursor to any edge or corner of the plot. The cursor will change to indicate that the plot can be resized. Click and drag the outline of the plot until the plot is the desired shape and size.

### Selecting Multiple Plots and Grouping Plots

Two or more plots can be selected together in layout mode. To select the plots, hold down the Shift key and either sequentially click on each plot you wish to select, or drag to draw a dotted rectangle around a group of plots. The selected plots will be indicated by a gray border around each plot:

Multiple selected plots can be moved simultaneously by dragging any single plot that is part of the selection (note that resizing any plot in the selection removes the selection). In addition, the layout mode context menu contains three additional items when multiple plots are selected. These items are described below.

Make Same

  Resizes all the selected plots in the chosen dimension(s) to match the dimension(s) of the plot from which the context menu was invoked. For example, right-clicking on a plot in the group and selecting Width from the Make Same submenu will match the width of all the plots in the group to the width of the first plot. If Size is chosen, both the width and height of each plot in the selection will change.

Align

  Aligns all plots in the selection to the plot directly underneath the context menu. Select from Left, Right, Top, or Bottom.

Pack (submenu)

  The Pack submenu contains two functions. Pack Horizontally divides the entire width of the plot group evenly between the individual plot widths, while Pack Vertically divides the entire height of the plot group evenly between the individual plot heights. Packing plots usually results in a staggered or “checkered” pattern. To align the plots in a grid, use the Cleanup Layout function of the layout mode context menu.

Group Objects

  Groups all the selected plots together. A group of plots is indicated by a blue outline around the entire group. The layout of the plots within a group cannot be altered, but a group of plots can be resized or moved as a whole in the same way the layout of a single plot can be changed. Grouped plots remain grouped even when layout mode is exited, so the Maximize or Delete functions of the plot context menu can be used on an entire group.

  To ungroup a group of plots, simply right-click on the group and select Ungroup.

## Working with Windows

Kst has a flexible window layout that makes use of Kmdi. Organizing plots on different windows allows for efficient viewing and manipulating of plots.

### MDI Modes

There is a choice of four different MDI (Multi-Document Interface) modes available. To select a mode, choose one of the menu items from the MDI Mode... submenu of the Window menu. The selected MDI mode will take effect immediately. The sections below provide more information on each mode.

#### Top Level Mode

Top level mode is the mode traditionally used by other KDE applications. In this mode, the parent window (the window containing all the main menus, toolbars, and status bars) is a separate window from the plot windows. The plot windows, while still functionally tied to the main window, appear as separate windows on the desktop.

To quickly switch between plot windows in top level mode, you can click the buttons on the parent window, as shown below.

#### Childframe Mode

In childframe mode, all the plot windows appear inside the main Kst window and can be individually resized. Each plot window contains buttons for minimizing, maximizing, closing, and docking themselves. The main Kst window also contains functions for arranging the plot windows. The following lists the functionality of the buttons located in the top right corner of each plot window:

  Undocks the plot window. An undocked window is not contained within the main Kst window, but is located directly on the desktop.

  ### Tip

  You can also undock or dock a window by selecting its name from the Dock/Undock submenu of the Window menu. This is also the only way to dock an undocked window.

  Minimizes the plot window. Since the plot window is contained within the main Kst window, clicking this button will minimize the window to a titlebar within the Kst window.

  Maximizes the plot window. The plot window will take up the entirety of the main Kst window.

  Closes the plot window.

To quickly switch between plot windows in childframe mode, you can click the buttons on the parent window, as shown below.

To easily organize the plot windows within the main Kst window, you can choose one of the tiling functions from the Tile... submenu of the Window menu. These functions are described below.

Cascade Windows

  Cascades the windows starting from the top left corner, maintaining the original window sizes.

Cascade Windows

  Cascades the windows starting from the top left corner, but resizes each window so that the bottom right corner of each window reaches the bottom right of the main Kst window.

Expand Vertically

  Resizes each window to its maximum height. The widths of the windows are not changed.

Expand Horizontally

  Resizes each window to its maximum width. The heights of the windows are not changed.

Tile Non-overlapped

  Arranges the windows in a tile pattern, with no windows overlapping and each window being as close to a square as possible.

Tile Overlapped

  Arranges the windows in three or four stacks, depending on the number of windows and the main Kst window size.

Tile Vertically

  Arranges the windows in a tile pattern, with each window having maximum height and no windows overlapping.

#### Tab Page Mode

Tab page mode arranges each plot window on a separate tab within the main Kst window. In this mode, the plot windows are not independently resizeable or moveable—they conform to the size and shape of the main Kst window.

To switch between plot windows in tab page mode, you can click on the tabs corresponding to each window, as shown below.

#### IDEAl Mode

IDEAl mode seems to be identical to tab page mode.

### Creating and Deleting Windows

New windows in Kst can be created in a number of ways. To create a new, empty, window, select New Window from the File menu. You will be prompted for a unique name for the new window. You can also create a new window while creating a new plottable data object. See Placement for the specific details.

To delete an existing window, simply select Close from the Window menu. To delete all current windows in Kst, select Close All from the Window menu. By default, Kst prompts for confirmation before closing any window. This behaviour can be changed by selecting Configure Kst... from the Settings menu and clicking on Prompt before closing windows.

### Important

When a window is deleted, all plots within that window are deleted as well. However, data objects, such as curves, are not deleted.

### Moving Plots Between Windows

To move a plot from one window to another, you can use the Move To function of the layout mode context menu.

## Chapter 4. Saving and Printing

Kst provides various methods of saving and exporting data and plots. These methods are described below.

## Saving Plot Definitions

A plot definition is essentially a capture of a Kst session. It contains all the plots, data objects, and plot layouts that are present at the time of saving.

To save a plot definition, simply select Save or Save As... (depending on whether or not you wish to save to a new file) from the File menu. Browse to the location you wish to save the plot definition, enter a filename, and click Save. The plot definition will be saved as a `*.kst` file.

## Exporting Vectors and Plots

Vectors and plots in Kst can be exported to files. This can be useful, for example, in capturing plots of live data or using generated vectors in a different application.

### Exporting Vectors

To export or save a vector to a file, select Save Vectors to Disk... from the File menu. The vector will be saved as an ASCII data file. The single column of the file will contain the elements of the selected vector. See below for an example of an exported vector.

    3776
    5380
    5245
    2942
    1861
    2424
    2520
    1868
    1736
    1736
    1174
    499

### Exporting Plots

To export a Kst plot to a graphics file, select Export to Graphics File... from the File menu. The following dialog box will appear.

The following settings and options are available when saving:

Save location

  The path to the graphics file. Enter a location manually, or click the button to right of the text box to browse to a location.

File Format

  The format to use for the saved graphics file. PNG is suggested if you are not sure which format to use.

Size

  Select the dimensions, in pixels, of the graphic. Check the Square option if you wish for the length and width of the graphic to be equal.

Windows

  Select whether to export only the plots in the current window, or all plots. If All is selected, one graphics file will be created for each window, each with filename `file_n.fmt`, where `file` is the filename specified in Save location, `n` is an index number assigned to each window, and fmt is an extension representing the selected file format.

Autosave

  Check this option if you want Kst to automatically save the plot to the specified file on a specified time interval.

Save interval

  The time interval used to perform autosave, in seconds.

Click Save Once to immediately perform a save with the specified options and settings. Click Close to close the dialog box (autosave will still be performed at the specified intervals, if selected).

## Printing

To print all the plots in the current window, select Print... from the File menu. A standard KDE print dialog will be displayed. There are currently no options to select for printing. The printed page will be in landscape orientation and contain the arrangement of plots in the current window. A footer containing the page number, window name, and current date is included as well.

## Chapter 5. Event Monitoring

An event monitor data object essentially keeps track of one or more vectors or scalars, and performs a specified action when a specified condition involving the vectors or scalars is true. Event monitors are usually used in conjunction with “live”, or streaming data. For example, an event monitor could be created to monitor whether or not elements of a data vector representing temperature exceed a predefined value.

## Event Monitor Dialog

The following is a screenshot of the window displayed when creating or editing events. Explanations of the settings are listed below.

### Expression

The condition to monitor for, along with other event properties, can be modified in this section.

Operators

  A list of available operators. Choosing an operator from the list inserts the operator at the current insertion point in the Expression text box.

Vectors

  A list of the current vector objects in Kst. Choosing a vector from the list inserts the vector at the current insertion point in the Expression text box.

Scalars

  A list of the available scalar values. This list is composed of both the scalar values in the current Kst session as well as some built-in constants. Choosing a scalar from the list inserts the scalar at the current insertion point in the Expression text box.

Expression

  The expression to monitor. You may type directly in this textbox, or select items to insert using the above drop-down lists. Ensure that the expression entered in this textbox is a boolean expression (i.e. it evaluates to either true or false). This usually entails using an equality or inequality in the expression. Note that vectors entered in the textbox will be monitored according to their individual elements.

  Whenever this expression is true, the event will be triggered. The action taken upon an event trigger depends on the settings specified in the next two sections.

Description

  This textbox is used to store a short description of the event. The description is primarily available as a method for keeping track of multiple events. You can enter any text you wish in this textbox.

### Kst Debug Log

This section specifies settings for entries added to the Kst debug log when events are triggered.

Log as:

  Enable this checkbox to have entries added to the Kst debug log when this event is triggered. There are three types of entries in the debug log—notices, warnings, and errors. Select the desired type of entry using the corresponding radio button.

### E-Mail Notification

In this section, settings for sending e-mail notifications of event triggers can be specified.

Notify

  Enable this checkbox to have Kst send e-mail notifications to the specified address when this event is triggered. Also enter in the email address you would like to appear in the “From” field of the email in the Sender textbox.

### ELOG

Kst supports adding entries to an ELOG logbook upon event triggers. This can be useful for remotely monitoring live data, or for obtaining summaries of event activity.

Notify

  Selecting this checkbox enables ELOG logging functionality for this event monitor. Click Configure... to specify server and logging settings.

## The ELOG Extension

The ELOG extension allows event monitors to create logbook entries on a server running the Electronic Logbook (ELOG) application. The created logbook entries can be used, for example, to remotely monitor Kst events or to produce periodical reports on data. For information on configuring and maintaining an ELOG server, please see the official ELOG Homepage. To enable the ELOG extension in Kst, select Extensions... from the Settings menu and ensure that “ELOG Extension” is checked.

### Server and Logging Settings

Server and logging settings should be configured if ELOG functionality is enabled for an event monitor object. To configure logging settings, click the Configure... button in the ELOG section of the Event Monitor dialog. The ELOG Event Entry dialog should be displayed:

Use the three checkboxes at the bottom to select the type of information to be logged. Include Kst capture specifies that a screen capture of the currently active window should be included in the entry. Include Kst configuration file specifies that `*.kst` save file should be attached to the entry. Finally, if Include Kst debugging information is checked, a copy of the debug log will be attached to the entry as well.

Additional fields will appear in this dialog once ELOG server settings are configured. To customize ELOG server settings, click the Configuration... button. The following dialog should be displayed:

Descriptions of the settings in this dialog follow.

Configuration, Save, and Load

  The Configuration drop down list contains a list of saved ELOG server configurations. To load a set of configuration settings, select an item from the list and click the Load button. To save the current configuration settings in this dialog into a slot, select the desired slot and click the Save button.

  ### Caution

  Saving settings into a slot overwrites any existing settings in that slot.

IP address and Port number

  Enter the IP address of the machine running the ELOG server application. The port number that the ELOG server listens on is configurable through the server, but by default it is 8080, so if you are unsure, enter 8080 as the port number.

Logbook

  Each ELOG server can contain one or more logbooks, so the name of the logbook to write entries to must be specified. Ensure that the spelling of the logbook is correct.

User name, User password, and Write password

  Depending on the how the ELOG server application is configured, these settings may or may not be necessary. If they are, enter the correct login credentials in the appropriate textboxes.

Capture size

  Use this list box to select the size, in pixels, of the Kst screen capture to attach (if specified).

Submit as HTML text

  If this checkbox is selected, HTML tags may be used in the logbook entry.

Suppress e-mail notification

  If the logbook is configured to send e-mail notifications of new entries, selecting this checkbox will disable the notifications. Note that this option is not related to Kst's own e-mail notification setting for event monitors.

Click the Apply button to apply the entered settings. Click Update to update the ELOG Event Entry dialog (the previous dialog). Additional fields should appear in the ELOG Event Entry dialog. These fields are unique to the selected logbook. Once you are satisfied with the settings, the Test button can be used to send a test logbook entry. Click Close to exit the dialog.

## Chapter 6. Plugins, Fits, and Filters

Plugins provide added functionality to Kst. By default, Kst comes packaged with an extensive selection of built-in plugins. In addition, a simple and consistent interface allows for easy creation of 3rd-party plugins. Fits and Filters are simply subsets of the set of plugins, and thus behave identically to plugins, with the exception of additional convenience dialog functionality accessible from the plot context menu.

## Adding and Removing Plugins

By default, the built-in plugins are stored in `/usr/lib/kde3/kstplugins/` (this directory may vary, depending on where you installed Kst). The Plugin Manager can be used to add and remove plugins. It can be acccessed by selecting Plugins... from the Settings menu. A list of the currently installed plugins is displayed in the Plugin Manager.

To add a plugin, click the Install... button. Browse to the directory containing both the plugin specification file (`*.xml`) and the object file (`*.o`). Click OK, and the plugin should be installed.

To remove a plugin, simply highlight the plugin in the Plugin Manager and click Remove. You will be prompted for confirmation.

To quickly refresh the list of plugins displayed in the Plugin Manager, click Rescan. Doing so will remove any plugins no longer present in their specified paths, and add any new plugins in the default plugins directory.

## Built-in Plugins

To date, there are more than 25 built-in plugins available in Kst that perform functions from taking cross correlations of two vectors to producing periodograms of a data set. The settings window for every plugin consists of two main sections—an input section and an output section. Each section is composed of a set of scalars and/or vectors. The following screenshot shows the settings window for a typical plugin. The only difference between the different plugins is the set of inputs and outputs, and the mechanism for deriving the outputs from the inputs.

The following sections describe the purpose, key algorithms or formulas used to perform calculations, and inputs and outputs for each plugin. Note that fitting and filtering plugins are included in the following sections.

### Autocorrelation

The autocorrelation plugin calculates correlation values between a series (vector) and a lagged version of itself, using lag values from `floor(-(N-1)/2)` to `floor((N-1)/2)`, where `N` is the number of points in the data set. The time vector is not an input as it is assumed that the data is sampled at equal time intervals. The correlation value `r` at lag `k` is:

#### Inputs

X Array (vector)

  The array `x` of values to calculate correlation values for.

#### Outputs

Step Number (vector)

  The array of step, or lag values.

Correlation Value (vector)

  The array of correlation values calculated using the corresponding step number in the Step Number vector.

### Bin

The bin plugin bins elements of a single data vector into bins of a specified size. The value of each bin is the mean of the elements belonging to the bin. For example, if the bin size is `3`, and the input vector is `[9,2,7,3,4,74,5,322,444,2,1]`, then the outputted bins would be `[6,27,257]`. Note that any elements remaining at the end of the input vector that do not form a complete bin (in this case, elements `2` and `1`), are simply discarded.

#### Inputs

Input Vector (vector)

  The vector to bin.

Bin Size (scalar)

  The size to use for each bin.

#### Outputs

Bins (vector)

  The array of means for each bin.

### Butterworth band-pass

The Butterworth band-pass plugin filters a set of data by calculating the Fourier transform of the data and recalculating the the frequency responses using the following formula

where `f` is the frequency, `fc` is the low frequency cutoff, `b` is the bandwidth of the band to pass, and `n` is the order of the Butterworth filter. The inverse Fourier transform is then calculated using the new filtered frequency responses.

#### Inputs

X Array (vector)

  The array of values to filter.

Order (scalar)

  The order of the Butterworth filter to use.

Low cutoff frequency (scalar)

  The low cutoff frequency of the Butterworth band pass filter.

Band width (scalar)

  The width of the band to pass. This should be the difference between the desired high cutoff frequency and the low cutoff frequency.

#### Outputs

X Filtered (vector)

  The array of filtered data values.

### Butterworth band-stop

The Butterworth band-stop plugin filters a set of data by calculating the Fourier transform of the data and recalculating the the frequency responses using the following formula

where `f` is the frequency, `fc` is the low frequency cutoff, `b` is the bandwidth of the band to stop, and `n` is the order of the Butterworth filter. The inverse Fourier transform is then calculated using the new filtered frequency responses.

#### Inputs

X Array (vector)

  The array of values to filter.

Order (scalar)

  The order of the Butterworth filter to use.

Low cutoff frequency (scalar)

  The low cutoff frequency of the Butterworth band stop filter.

Band width (scalar)

  The width of the band to stop. This should be the difference between the desired high cutoff frequency and the low cutoff frequency.

#### Outputs

X Filtered (vector)

  The array of filtered data values.

### Butterworth high-pass

The Butterworth high-pass plugin filters a set of data by calculating the Fourier transform of the data and recalculating the the frequency responses using the following formula

where `f` is the frequency, `fc` is the high frequency cutoff, and `n` is the order of the Butterworth filter. The inverse Fourier transform is then calculated using the new filtered frequency responses.

#### Inputs

X Array (vector)

  The array of values to filter.

Order (scalar)

  The order of the Butterworth filter to use.

Cutoff frequency (scalar)

  The cutoff frequency of the Butterworth high pass filter.

#### Outputs

X Filtered (vector)

  The array of filtered data values.

### Butterworth low-pass

The Butterworth low-pass plugin filters a set of data by calculating the Fourier transform of the data and recalculating the the frequency responses using the following formula

where `f` is the frequency, `fc` is the low frequency cutoff, and `n` is the order of the Butterworth filter. The inverse Fourier transform is then calculated using the new filtered frequency responses.

#### Inputs

X Array (vector)

  The array of values to filter.

Order (scalar)

  The order of the Butterworth filter to use.

Cutoff frequency (scalar)

  The cutoff frequency of the Butterworth low pass filter.

#### Outputs

X Filtered (vector)

  The array of filtered data values.

### Chop

The chop plugin takes an input vector and divides it into two vectors. Every second element in the input vector is placed in one output vector, while all other elements from the input vector are placed in another output vector.

#### Inputs

Array (vector)

  The array of values to perform the chop on.

#### Outputs

Odd Array (vector)

  The array containing the odd part of the input array (i.e. it contains the first element of the input array).

Even Array (vector)

  The array containing the even part of the input array (i.e. it does not contain the first element of the input array).

Difference Array (vector)

  The array containing the elements of the odd array minus the respective elements of the even array.

Index Array (vector)

  An index array the same length as the other three output arrays.

### Convolution

The convolution plugin generates the convolution of one vector with another. The convolution of two functions `f` and `g` is given by:

The order of the vectors does not matter, since `f*g=g*f`. In addition, the vectors do not need to be of the same size, as the plugin will automatically extrapolate the smaller vector.

#### Inputs

Array One (vector)

  One of the pair of arrays to take the convolution of.

Array Two (vector)

  One of the pair of arrays to take the convolution of.

#### Outputs

Convolved (vector)

  The convolution of the two input vectors.

### Crosscorrelation

The crosscorrelation plugin calculates correlation values between two series (vectors) `x` and `y`, using lag values from `floor(-(N-1)/2)` to `floor((N-1)/2)`, where `N` is the number of elements in the longer vector. The shorter vector is padded to the length of the longer vector using `0`s. The time vector is not an input as it is assumed that the data is sampled at equal time intervals. The correlation value `r` at lag `k` is:

#### Inputs

X Array (vector)

  The array `x` used in the cross-correlation formula.

Y Array (vector)

  The array `y` used in the cross-correlation formula.

#### Outputs

Step Number (vector)

  The array of step, or lag values.

Correlation Value (vector)

  The array of correlation values calculated using the corresponding step number in the Step Number vector.

### Deconvolution

The deconvolution plugin generates the deconvolution of one vector with another. Deconvolution is the inverse of convolution. Given the convolved vector `h` and another vector `g`, the deconvolution `f` is given by:

The vectors do not need to be of the same size, as the plugin will automatically extrapolate the shorter vector. The shorter vector is assumed to be the response function `g`.

#### Inputs

Array One (vector)

  One of the pair of arrays to take the deconvolution of.

Array Two (vector)

  One of the pair of arrays to take the deconvolution of.

#### Outputs

Deconvolved (vector)

  The deconvolution of the two input vectors.

### Fit exponential weighted

The Fit exponential weighted plugin performs a weighted non-linear least-squares fit to an exponential model:

An initial estimate of `a=1.0`, `=0`, and `b=0` is used. The plugin subsequently iterates to the solution until a precision of `1.0e-4` is reached or 500 iterations have been performed.

#### Inputs

X Array (vector)

  The array of x values for the data points to be fitted.

Y Array (vector)

  The array of y values for the data points to be fitted.

Weights (vector)

  The array of weights to use for the fit.

#### Outputs

Y Fitted (vector)

  The array of fitted y values.

Residuals (vector)

  The array of residuals.

Parameters (vector)

  The best fit parameters `a`, , and `b`.

Covariance (vector)

  The covariance matrix of the model parameters, returned row after row in the vector.

chi^2/nu (scalar)

  The weighted sum of squares of the residuals, divided by the degrees of freedom.

### Fit exponential

The Fit exponential plugin is identical in function to the Fit exponential weighted plugin with the exception that the weight value `wi` is equal to `1` for all index values `i`. As a result, the Weights (vector) input does not exist.

### Fit gaussian weighted

The Fit gaussian weighted plugin performs a weighted non-linear least-squares fit to a Gaussian model:

An initial estimate of `a=`(maximum of the y values), `=`(mean of the x values), and `=`(the midpoint of the x values) is used. The plugin subsequently iterates to the solution until a precision of `1.0e-4` is reached or 500 iterations have been performed.

#### Inputs

X Array (vector)

  The array of x values for the data points to be fitted.

Y Array (vector)

  The array of y values for the data points to be fitted.

Weights (vector)

  The array of weights to use for the fit.

#### Outputs

Y Fitted (vector)

  The array of fitted y values.

Residuals (vector)

  The array of residuals.

Parameters (vector)

  The best fit parameters , , and `a`.

Covariance (vector)

  The covariance matrix of the model parameters, returned row after row in the vector.

chi^2/nu (scalar)

  The weighted sum of squares of the residuals, divided by the degrees of freedom.

### Fit gaussian

The Fit gaussian plugin is identical in function to the Fit gaussian weighted plugin with the exception that the weight value `wi` is equal to `1` for all index values `i`. As a result, the Weights (vector) input does not exist.

### Fit gradient weighted

The gradient weighted plugin performs a weighted least-squares fit to a straight line model without a constant term:

The best-fit is found by minimizing the weighted sum of squared residuals:

for `b`, where `wi` is the weight at index `i`.

#### Inputs

X Array (vector)

  The array of x values for the data points to be fitted.

Y Array (vector)

  The array of y values for the data points to be fitted.

Weights (vector)

  The array containing weights to be used for the fit.

#### Outputs

Y Fitted (vector)

  The array of y values for the points representing the best-fit line.

Residuals (vector)

  The array of residuals, or differences between the y values of the best-fit line and the y values of the data points.

Parameters (vector)

  The parameter `b` of the best-fit.

Covariance (vector)

  The estimated covariance matrix, returned row after row, starting with row 0.

Y Lo (vector)

  The corresponding value in Y Fitted minus the standard deviation of the best-fit function at the corresponding x value.

Y Hi (vector)

  The corresponding value in Y Fitted plus the standard deviation of the best-fit function at the corresponding x value.

chi^2/nu (scalar)

  The value of the sum of squares of the residuals, divided by the degrees of freedom.

### Fit gradient

The Fit linear plugin is identical in function to the Fit gradient weighted plugin with the exception that the weight value `wi` is equal to `1` for all index values `i`. As a result, the Weights (vector) input does not exist.

### Fit linear weighted

The Fit linear weighted plugin performs a weighted least-squares fit to a straight line model:

The best-fit is found by minimizing the weighted sum of squared residuals:

for `a` and `b`, where `wi` is the weight at index `i`.

#### Inputs

X Array (vector)

  The array of x values for the data points to be fitted.

Y Array (vector)

  The array of y values for the data points to be fitted.

Weights (vector)

  The array containing weights to be used for the fit.

#### Outputs

Y Fitted (vector)

  The array of y values for the points representing the best-fit line.

Residuals (vector)

  The array of residuals, or differences between the y values of the best-fit line and the y values of the data points.

Parameters (vector)

  The parameters `a` and `b` of the best-fit.

Covariance (vector)

  The estimated covariance matrix, returned row after row, starting with row 0.

Y Lo (vector)

  The corresponding value in Y Fitted minus the standard deviation of the best-fit function at the corresponding x value.

Y Hi (vector)

  The corresponding value in Y Fitted plus the standard deviation of the best-fit function at the corresponding x value.

chi^2/nu (scalar)

  The value of the sum of squares of the residuals, divided by the degrees of freedom.

### Fit linear

The Fit linear plugin is identical in function to the Fit linear weighted plugin with the exception that the weight value `wi` is equal to `1` for all index values `i`. As a result, the Weights (vector) input does not exist.

### Fit lorentzian weighted

The Fit lorentzian weighted plugin performs a weighted non-linear least-squares fit to a Lorentzian model:

An initial estimate of `a=`(maximum of the y values), `x0=`(mean of the x values), and `=`(the midpoint of the x values) is used. The plugin subsequently iterates to the solution until a precision of `1.0e-4` is reached or 500 iterations have been performed.

#### Inputs

X Array (vector)

  The array of x values for the data points to be fitted.

Y Array (vector)

  The array of y values for the data points to be fitted.

Weights (vector)

  The array of weights to use for the fit.

#### Outputs

Y Fitted (vector)

  The array of fitted y values.

Residuals (vector)

  The array of residuals.

Parameters (vector)

  The best fit parameters `x0`, , and `a`.

Covariance (vector)

  The covariance matrix of the model parameters, returned row after row in the vector.

chi^2/nu (scalar)

  The weighted sum of squares of the residuals, divided by the degrees of freedom.

### Fit lorentzian

The Fit lorentzian plugin is identical in function to the Fit lorentzian weighted plugin with the exception that the weight value `wi` is equal to `1` for all index values `i`. As a result, the Weights (vector) input does not exist.

### Fit polynomial weighted

The Fit polynomial weighted plugin performs a weighted least-squares fit to a polynomial model:

where `n` is the degree of the polynomial model.

#### Inputs

X Array (vector)

  The array of x values for the data points to be fitted.

Y Array (vector)

  The array of y values for the data points to be fitted.

Weights (vector)

  The array of weights to use for the fit.

Order (scalar)

  The order, or degree, of the polynomial model to use.

#### Outputs

Y Fitted (vector)

  The array of fitted y values.

Residuals (vector)

  The array of residuals.

Parameters (vector)

  The best fit parameters `c0`, `c1`,..., `cn`.

Covariance (vector)

  The covariance matrix of the model parameters, returned row after row in the vector.

chi^2/nu (scalar)

  The weighted sum of squares of the residuals, divided by the degrees of freedom.

### Fit polynomial

The Fit polynomial plugin is identical in function to the Fit polynomial weighted plugin with the exception that the weight value `wi` is equal to `1` for all index values `i`. As a result, the Weights (vector) input does not exist.

### Fit sinusoid weighted

The Fit sinusoid weighted plugin performs a least-squares fit to a sinusoid model:

where `T` is the specified period, and `n=2+2H`, where `H` is the specified number of harmonics.

#### Inputs

X Array (vector)

  The array of x values for the data points to be fitted.

Y Array (vector)

  The array of y values for the data points to be fitted.

Weights (vector)

  The array of weights to use for the fit.

Harmonics (scalar)

  The number of harmonics of the sinusoid to fit.

Period (scalar)

  The period of the sinusoid to fit.

#### Outputs

Y Fitted (vector)

  The array of fitted y values.

Residuals (vector)

  The array of residuals.

Parameters (vector)

  The best fit parameters `c0`, `c1`,..., `cn`.

Covariance (vector)

  The covariance matrix of the model parameters, returned row after row in the vector.

chi^2/nu (scalar)

  The weighted sum of squares of the residuals, divided by the degrees of freedom.

### Fit sinusoid

The Fit sinusoid plugin is identical in function to the Fit sinusoid weighted plugin with the exception that the weight value `wi` is equal to `1` for all index values `i`. As a result, the Weights (vector) input does not exist.

### Interpolation Akima spline

The Interpolation Akima spline plugin generates a non-rounded Akima spline interpolation for the supplied data set, using natural boundary conditions.

#### Inputs

X Array (vector)

  The array of x values of the data points to generate the interpolation for.

Y Array (vector)

  The array of y values of the data points to generate the interpolation for.

X' Array (vector)

  The array of x values for which interpolated y values are desired.

#### Outputs

Y Interpolated (vector)

  The interpolated y values.

### Interpolation Akima spline periodic

The kstinterp akima periodic plugin generates a non-rounded Akima spline interpolation for the supplied data set, using periodic boundary conditions.

#### Inputs

X Array (vector)

  The array of x values of the data points to generate the interpolation for.

Y Array (vector)

  The array of y values of the data points to generate the interpolation for.

X' Array (vector)

  The array of x values for which interpolated y values are desired.

#### Outputs

Y Interpolated (vector)

  The interpolated y values.

### Interpolation cubic spline

The Interpolation cubic spline plugin generates a cubic spline interpolation for the supplied data set, using natural boundary conditions.

#### Inputs

X Array (vector)

  The array of x values of the data points to generate the interpolation for.

Y Array (vector)

  The array of y values of the data points to generate the interpolation for.

X' Array (vector)

  The array of x values for which interpolated y values are desired.

#### Outputs

Y Interpolated (vector)

  The interpolated y values.

### Interpolation cubic spline periodic

The Interpolation cubic spline periodic plugin generates a cubic spline interpolation for the supplied data set, using periodic boundary conditions.

#### Inputs

X Array (vector)

  The array of x values of the data points to generate the interpolation for.

Y Array (vector)

  The array of y values of the data points to generate the interpolation for.

X' Array (vector)

  The array of x values for which interpolated y values are desired.

#### Outputs

Y Interpolated (vector)

  The interpolated y values.

### Interpolation linear

The Interpolation linear plugin generates a linear interpolation for the supplied data set.

#### Inputs

X Array (vector)

  The array of x values of the data points to generate the interpolation for.

Y Array (vector)

  The array of y values of the data points to generate the interpolation for.

X' Array (vector)

  The array of x values for which interpolated y values are desired.

#### Outputs

Y Interpolated (vector)

  The interpolated y values.

### Interpolation polynomial

The Interpolation polynomial plugin generates a polynomial interpolation for the supplied data set. The number of terms in the polynomial used is equal to the number of points in the supplied data set.

#### Inputs

X Array (vector)

  The array of x values of the data points to generate the interpolation for.

Y Array (vector)

  The array of y values of the data points to generate the interpolation for.

X' Array (vector)

  The array of x values for which interpolated y values are desired.

#### Outputs

Y Interpolated (vector)

  The interpolated y values.

### Noise Addition

The Noise addition plugin adds a Gaussian random variable to each element of the input vector. The Gaussian distribution used has a mean of `0` and the specified standard deviation. The probability density function of a Gaussian random variable is:

#### Inputs

Array (vector)

  The array of elements to which random noise is to be added.

Sigma (scalar)

  The standard deviation to use for the Gaussian distribution.

#### Outputs

Output Array (vector)

  The array of elements with Gaussian noise added.

### Periodogram

The periodogram plugin produces the periodogram of a given data set. One of two algorithms is used depending on the size of the data set—a fast algorithm is used if there are greater than 100 data points, while a slower algorithm is used if there are less than or equal to 100 data points.

#### Inputs

Time Array (vector)

  The array of time values of the data points to generate the interpolation for.

Data Array (vector)

  The array of data values, dependent on the time values, of the data points to generate the interpolation for.

Oversampling factor (scalar)

  The factor to oversample by.

Average Nyquist frequency factor (scalar)

  The average Nyquist frequency factor.

#### Outputs

Frequency (vector)

  The frequency vector.

Periodogram (vector)

  The frequency response vector for the periodogram.

### Statistics

The statistics plugin calculates statistics for a given data set. Most of the output scalars are named such that the values they represent should be apparent. Standard formulas are used to calculate the statistical values.

#### Inputs

Data Array (vector)

  The array of data values to calculate statistics for.

#### Outputs

Mean (scalar)

  The mean of the data values.

Minimum (scalar)

  The minimum value found in the data array.

Maximum (scalar)

  The maximum value found in the data array.

Variance (scalar)

  The variance of the data set.

Standard deviation (scalar)

  The standard deviation of the data set.

Median (scalar)

  The median of the data set.

Absolute deviation (scalar)

  The absolute deviation of the data set.

Skewness (scalar)

  The skewness of the data set.

Kurtosis (scalar)

  The kurtosis of the data set.

## Chapter 7. The Toolbar and Keyboard Shortcuts

This chapter describes miscellaneous time-saving and convenience features available in Kst.

## The Toolbar

The toolbar provides one-click access to commonly used menu functions in Kst. To toggle the toolbar, select Show Toolbar from the Settings menu.

### The Toolbar Menu

The toolbar menu, accessible by right-clicking anywhere on the toolbar, contains functions for modifying the layout, appearance, and behaviour of the toolbar. The three submenus available are described below.

#### Orientation

The Orientation submenu contains layout options for the toolbar.

Top, Left, Right, and Bottom

  Docks the toolbar at the corresponding edge of the Kst window.

Flat

  Hides the toolbar and turns it into a slim bar at the top of Kst window. To unhide the toolbar, click on the “gripper” that is still visible.

You can also move the toolbar by dragging the gripper on the edge of the toolbar. Dragging the toolbar close to an edge of the Kst window docks it. Dragging the toolbar anywhere else turns it into a floating toolbar.

#### Text Position

The Text Position submenu specifies if and how text and icons should be displayed on the toolbar.

Icons Only

  Does not display any text labels and only displays icons. However, the text for each icon is still available as a tooltip associated with the icon (viewable by momentarily holding the cursor of the icon).

Text Only

  Does not display any icons on the toolbar, but displays all text labels.

Text Alongside Icons

  Displays all icons. Text labels are displayed to the right of the icons.

Text Under Icons

  Displays all icons. Text labels are displayed underneath the icons.

#### Icon Size

The Icon Size submenu specifies the size of the icons on the toolbar. Select a size from the submenu, or select Default to use the default size (usually the same as Medium). The options in this menu do not have any effect if Text Only is selected for Text Position.

## Custom Shortcut Keys

You can create custom shortcut keys to make working in Kst more efficient. To modify the shortcut keys, select Configure Shortcuts... from the Settings menu. The following dialog will be displayed.

A list of available actions and their associated shortcuts are shown in the dialog. Each action is allowed two shortcuts—a primary shortcut and an alternate shortcut. Either shortcut can be used at any time. To define or change a shortcut for an action, simply highlight the appropriate row in the shortcut list. Under Shortcut for Selected Action, there are three choices:

None

  Select this option to disable any shortcut keys for the selected action.

Default

  Select this option to use the default shortcut key(s) for the selected action. Note that not all actions have default shortcuts defined.

Custom

  Select this option to define a custom shortcut for the selected action.

If you select the Custom option, the Define Shortcut dialog will appear (alternatively, you can also click on the key-shaped button to open the dialog).

By default, the Auto-close option is checked, so once a key combination is entered, the key combination will be automatically saved and the dialog closed. You can uncheck this option if you wish to experiment with the dialog.

To define a key combination, select Primary or Alternate. If you wish to define a key sequence, check the Multi-key option. Now enter the key combination or sequence to be used for this action. Click OK when you are done.

### Tip

When using shortcuts defined with the multi-key option, a small menu is displayed after the first key of the shortcut is pressed, showing the possible shortcut key completions. Pressing additional keys of the shortcut further filters the list. This list can be a useful reminder of the defined shortcuts.

### Note

The action associated with a multi-key shortcut is performed as soon as only one action matches the keys pressed so far. For example, if a multi-key shortcut of A B C is defined, and no other multi-key shortcuts are defined, the action associated with the shortcut will be performed as soon as A is pressed.

## Chapter 8. Licensing

This documentation is licensed under the terms of the GNU Free Documentation License.

## Appendix A. Command Line Usage and Examples

### Barth Netterfield `<kst@omega.astro.utoronto.ca>`

A typical use of kst is from the command line to make X-Y plots of data files. kst can read ascii data, or readdata compatible binary files.

## Command Line Synopsis

The options are:

kst [Qt-options] [KDE-options] [options] [`file`...]

`[file...]`

  A .kst file, or one or more data files. Supported formats are ASCII columns, BOOMERANG frame files, or BLAST dirfile files. A .kst files stores all options that can be set by other flags. The following flags can be used to override the options set in the .kst file: `-F datafile`, `-n NS`, `-s NS`, `-f F0`, `-a`. The rest can not be overridden. If an override flag is given, it is applied to all vectors in the plot.

  ASCII data from stdin can be plotted by including "stdin" in the list `[file...]`.

`-y Y`

  The source for the Y axis data. For ASCII files, this is the column. For binary files, this is the field name. To plot multiple curves, this may be specified multiple times. The same source file, sample ranges, and X axis data are assumed.

`-e E`

  Error bars for Y axis data. For ASCII file, refer to the column holding the data. For binary files use the field name. If multiple `-y Y` options are given, this may also be used multiple times. Individual Y entries are associated in order with multiple E entries.

`-x X`

  The source for the X axis data. For ASCII files, this is the column. For readata files, this is the field name. If this option is not specified, the row number in the file is used. This option can only be given once.

`-p P`

  The source for power spectra. For ASCII files, this is the column. For binary files, this is the field name. To plot power spectra of multiple curves, this may be specified multiple times. The same source file, sample ranges and fft lengths are used for all Power Spectra requested from the command line.

`-l P`

  The length of the FFT used in power specra estimation is 2^P.

`-h H`

  The source for histograms. For ASCII files, this is the column. For binary files, this is the field name. Multiple histograms can be defined from the command line.

`-m NC`

  Used when multiple curves have been defined. Rather than plotting all curves in the same plot, plot each in its own plot,

`-f F0`

  The starting frame number (for readdata files) or row (for ASCII files) to read.

`-n`

  The number of frames (for readdata files) or rows (for ASCII files) to read.

`-s NS`

  The number of frames or rows to skip each read. This is useful when working with very large data files, to speed up response and conserve memory, in the case that the data are slowly varying.

`-a`

  Used in with the `-s NS`: rather than skipping each NS frames, average them. This provides a combination of very basic high pass filtering, and memory conservation.

`-F Datafile`

  Override the file to read the data from for all vectors listed in the .kst file. Can only be used in conjunction with a kst file.

`--print psfile`

  Rather than displaying the plot, export the image to a postscript file and exit. *BUG note: even though no windows are opened on screen, access to the X server is still required.*

`--png pngfile`

  Rather than displaying the plot, export the image to a png file of dimensions 640x480 and exit. *BUG note: even though no windows are opened on screen, access to the X server is still required.*

## Command Line Examples

Several examples of typical use follow.

To plot column 1 a file (tmp.dat) of ASCII data:

    kst -y 1 tmp.dat

To plot column 2, 3, and 4 vs. column 1 of an ASCII file, in 1 plot:

    kst -x 1 -y 2 -y 3 -y 4 tmp.dat

To plot column 2, 3, and 4 vs. column 1 of an ASCII file, in 3 plots, arranged in 1 column:

    kst -x 1 -y 2 -y 3 -y 4 -m 1 tmp.dat

To plot 500 rows of column 2 of an ASCII file, starting at line 100:

    kst -y 2 -f 100 -n 500 tmp.dat

To plot the first 100,000 rows of column 2 of an ASCII file, averaging every 100 rows:

    kst -y 2 -f 0 -n 100000 -s 100 -a tmp.dat

## Appendix B. Creating Additional Plugins

Kst has a simple and standardized interface that facilitates easy creation of additional plugins. In addition to detailing basic requirements for plugins, the following sections describe how to make use of pre-written header files to create certain types of plugins.

## Creating a Basic Plugin

A Kst plugin consists of two files—an XML file and a shared object file.

### The XML File

The XML file provide information about the plugin and describes its inputs and outputs. The following is an example of an XML file for a Kst plugin:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE Module SYSTEM "file:/Repository/Level2/Soft/ProC/moduledef.dtd">

    <module>

    <intro>
    <modulename name="testplugin"/>    <!-- The name of the module -->
    <author name="Rick Chern"/> <!-- The name of the author -->
    <description text="A test plugin for me"/> <!-- A description of the module -->
    <version minor="1" major="0"/>  <!-- The version number of the module -->
    <state devstate="release"/>     <!-- The development state of the module (optional)-->
    </intro>

    <interface>

    <!--inputs here-->
    <input>
    <table type="float" name="Input Vector 1" descr="The first input vector" />
    </input>

    <input>
    <float name="Input Scalar 1" descr="The first input scalar" />
    </input>

    <!--outputs here-->
    <output>
    <table type="float" name="Output Vector 1" descr="The first output vector" />
    </output>

    <output>
    <float name="Output Scalar 1" descr="The first output scalar" />
    </output>

    </interface>

    </module>

Generally, you can use the example above as a template and modify sections to fit your needs. As can be seen from the example, the XML file consists of one `module` node. The `module` node has an `intro` node and an `interface` node. You should modify the `intro` node appropriately using the comments in the above XML file as guides. It is important that `modulename` has the `name` attribute set to the same name that your shared object file will use.

The `interface` node describes the actual inputs and outputs of the plugin. Each input is described by an `input` node, and each output is described by an `output` node. Each input or output should have either a `table` or a `float` node as a child. The `type` attribute of a `table` must be set to `"float"`. Note that the order of the inputs and outputs matters—the order is used to determine the index values for each input and output array of the object file, and is the same order used to display the input and output fields in the Kst plugin interface.

Once you have completed the XML file, save it as `[modulename].xml`, where `[modulename]` is the value of the `name` attribute of the `modulename` node.

### The Shared Object File

The shared object file contains the actual functionality of the plugin. In other words, it determines how to derive the outputs from the given inputs. The following are the requirements for the shared object file:

- The object must export the following C linkage symbol:

  `int symbol(const double *const `inArrays[]`,
  const int `inArrayLens[]`,
  const double `inScalars[]`,
  double *`outArrays[]`,
  int `outArrayLens[]`,
  double `outScalars[]`)`

  where `symbol` must be the value of the `name` attribute of the `modulename` node in the XML file. This is the only function that will be called by Kst (although you may have other functions). The following describes each argument of this function:

  `const double *const inArrays[]`

    The array of input arrays. Each input array corresponds to an input vector. The arrays are in the same order as the vectors are listed in the XML file, so `inArrays[0]` is the array representing the first input vector, `inArrays[1]` is the array representing the second input vector, and so on.

  `const int inArraysLens[]`

    The array containing array lengths for each input array. The lengths are stored in the same order as the arrays in `inArrays[]` (e.g. `inArrayLens[0]` is the length of `inArrays[0]`).

  `const double inScalars[]`

    The array of input scalars. The scalars are stored in the same order as they are listed in the XML file.

  `double *outArrays[]`

    The array of output arrays. Each output array corresponds to an output vector, and the arrays should be in the same order as the output vectors are listed in the XML file.

  `int outArrayLens[]`

    The array that should contain lengths of the output arrays. The lengths should be stored in the same order as the arrays in `outArrays[]`.

  `double outScalars[]`

    The array of output scalars. The scalars should be in the same order they are listed in the XML file.

- The function must return `0` if it executed succesfully, and `-1` otherwise.

- The code for the object file must handle unexpected inputs, such as empty input arrays (in most cases a return value of `-1` would be sufficient when such situations are encountered).

- The number and type of outputs must be exactly as specified by the XML file.

- You will probably need to resize the arrays in `outArrays[]`. To do so, use the `realloc()` function. E.g.,

      outArrays[0]=(double*)realloc(outArrays[0], 5*sizeof(double));

  will allocate space for 5 doubles for `outArrays[0]`. Do not use any memory allocator other than `realloc()`.

- The input arguments must remain constant. Do not cast them to non-constant types.

The following is an example of the shared object file source code for a simple plugin:

    #include <stdlib.h>

    extern "C" int testplugin(const double *const inArrays[], const int inArrayLens[],
                    const double is[],
                    double *outArrays[], int outArrayLens[],
                    double outScalars[]);

    int testplugin(const double *const inArrays[], const int inArrayLens[],
                    const double is[],
                    double *outArrays[], int outArrayLens[],
                    double outScalars[])

    //Accept 1 vector and 1 scalar. Multiply all elements of the vector by the
    //scalar, and output the resulting vector. Also output the original scalar.
    {
    	//Set the outputs
    	outArrayLens[0]=inArrayLens[0];

    	//resize the output arrays
    	outArrays[0]=(double*)realloc(outArrays[0], inArrayLens[0]*sizeof(double));

    	//multiply each element of the input vector
    	//by the scalar
    	for (int i=0; i<inArrayLens[0]; i++)
    	{
    		outArrays[0][i]=inArrays[0][i] * is[0];
    	}

    	//now set the output scalar
    	outScalars[0]=is[0];

    	return 0;
    }

### Compiling the Plugin

If you are using gcc to compile your plugin, simply compile the object file:

    cc -Wall -c -o myplugin.o myplugin.c -fPIC -DPIC

and then create the shared library:

    ld -o myplugin.so -shared myplugin.o

The resulting `*.so` file and `*.xml` file must be put in the same directory. When you use Kst's Plugin Manager to load the XML file, it will automatically look for the shared object file in the same directory.

## Creating Linear Fit Plugins

To create a linear fit plugin, you could implement your own fitting algorithms and output the appropriate vectors. However, Kst already comes with header files that make it easy for you to implement linear least-squares fit plugins by just providing a few functions. This section will describe how to take advantage of these files.

### Header Files

Two header files are provided for performing linear fits, `linear.h` (for unweighted linear fits) and `linear_weighted.h` (for weighted linear fits). They are both located under `kst/plugins/fits/` in the Kst source tarball. To use these files, include only one of them in the source code for your plugin:

    #include <../linear.h>

or

    #include <../linear_weighted.h>

(by convention, we will place the source code for the plugin one directory below where the header files are).

### Implementing Required Functions

Given a general linear model:

where `y` is a vector of `n` observations, `X` is an `n` by `p` matrix of predictor variables, and `c` is the vector of `p` best-fit parameters that are to be estimated, the header files provide functions for estimating `c` for a given `y` and `X`. To provide `X`, the following function needs to be implemented in the source code for the plugin:

`double calculate_matrix_entry( double `dX`, int `iPos` )`

This function should return the value of the entry in column `iPos` of the matrix of predictor variables, using `x` value `dX`. This function will be called by linear.h or linear_weighted.h. The implementation of this function depends on the model you wish to use for the fit, and is unique to each linear fit plugin. For example, to fit to a polynomial model, `calculate_matrix_entry` could be implemented as follows:

    double calculate_matrix_entry( double dX, int iPos ) {
      double dY;
      dY = pow( dX, (double)iPos );
      return dY;
    }

### Calling the Fitting Functions

Once the appropriate header file has been included and `calculate_matrix_entry` has been implemented, call the appropriate fitting function included from the header file:

    kstfit_linear_unweighted( inArrays, inArrayLens,
                              outArrays, outArrayLens,
                              outScalars, iNumParams );

or

    kstfit_linear_weighted( inArrays, inArrayLens,
                            outArrays, outArrayLens,
                            outScalars, iNumParams );

Each function will return `0` on success, or `-1` on error, so it is a good idea to set the return value of the exported C function to be equal to the return value of the fitting function. To maintain simplicity, the code for the plugin can simply pass the arguments given to the exported C function to the fitting function. Note, however, that inArrays must be structured as follows:

- `inArrays[0]` must contain the array of x coordinates of the data points

- `inArrays[1]` must contain the array of y coordinates of the data points

- `inArrays[2]` only exists if `kstfit_linear_weighted` is being called, and must contain the array of weights to use for the fit.

The easiest way to ensure that inArrays is structured correctly is to specify the correct order of input vectors in the XML file for the plugin.

`iNumParams` is the number of parameters in the fitting model used, which should be equal to the number of columns in the matrix `X` of predictor variables. `iNumParams` must be set correctly before the fitting function is called.

After `kstfit_linear_unweighted` or `kstfit_linear_weighted` is called, `outArrays` and `outScalars` will be set as follows:

- `outArrays[0]` will contain the array of fitted y values.

- `outArrays[1]` will contain the array of residuals.

- `outArrays[2]` will contain the array of best-fit parameters that were estimated.

- `outArrays[3]` will contain the covariance matrix, returned row after row in an array.

- `outScalars[0]` will contain chi^2/nu, where chi^2 is the weighted sum of squares of the residuals, and nu is the degrees of freedom.

`outArrayLens` will be correctly set to indicate the length of each output array.

Ensure that the specified outputs in the XML file match those that the exported C function returns (which in most cases will simply be the outputs returned by the fitting function).

### Example

The following is an example of the source code for a linear fit plugin.

    /*
     *  Polynomial fitting plugin for KST.
     *  Copyright 2004, The University of British Columbia
     *  Released under the terms of the GPL.
     */

    #include "../linear.h"

    double calculate_matrix_entry( double dX, int iPos ) {
      double dY;

      dY = pow( dX, (double)iPos );

      return dY;
    }

    extern "C" int kstfit_polynomial_unweighted(
      const double *const inArrays[],
      const int inArrayLens[],
      const double inScalars[],
      double *outArrays[], int outArrayLens[],
      double outScalars[]);

    int kstfit_polynomial_unweighted(
      const double *const inArrays[],
      const int inArrayLens[],
    	const double inScalars[],
    	double *outArrays[], int outArrayLens[],
    	double outScalars[])
    {
      int iRetVal = -1;
      int iNumParams;

      iNumParams = 1 + (int)floor( inScalars[0] );
      if( iNumParams > 0 ) {
        iRetVal = kstfit_linear_unweighted( inArrays, inArrayLens,
                                            outArrays, outArrayLens,
                                            outScalars, iNumParams );
      }

      return iRetVal;
    }

## Creating Non-linear Fit Plugins

Kst provides header files designed to simplify the creation of non-linear least-squares fit plugins. The following sections detail the use of the header files.

### Header Files and Definitions

The non-linear fit header files are located in `kst/plugins/fits_nonlinear` of the Kst source tarball. The files are named `non_linear.h` and `non_linear_weighted.h` for unweighted and weighted fits, respectively. To use these files, include only one of them in the source code for your plugin:

    #include <../non_linear.h>

or

    #include <../non_linear_weighted.h>

(by convention, we will place the source code for the plugin one directory below where the header files are).

As non-linear fitting is an iterative process, you must also define the maximum number of iterations that should be performed. The non-linear fitting algorithm will stop when at least one of the following conditions is true:

- The maximum number of iterations has been reached.

- A precision of 10-4 has been reached.

In addition, you need to define the number of parameters in the model, as it is not passed to the fitting function explicitly. To define these two values, include the following at the top of your source code:

    #define NUM_PARAMS [num1]
    #define MAX_NUM_ITERATIONS [num2]

replacing `[num1]` with the number of parameters in the model, and `[num2]` with the maximum number of iterations to perform.

### Implementing Required Functions

To use the header files for non-linear fits, you must provide the function to use as the model, the partial derivatives of the function with respect to each parameter, and initial estimates of the best-fit parameters. To do this, three functions must be implemented. These functions are described below.

`double function_calculate( double `dX`, double* `pdParameters` )`

  This function calculates the y value of the fitting model for a given x value `dX`, using the supplied array of parameters `pdParameters`. The order of parameters in `pdParameters` is arbitrary, but should be consistent with the other two implemented functions. For example, for an exponential model, `function_calculate` could be implemented as follows:

      double function_calculate( double dX, double* pdParameters ) {
        double dScale	 = pdParameters[0];
        double dLambda = pdParameters[1];
        double dOffset = pdParameters[2];
        double dY;

        dY  = ( dScale * exp( -dLambda * dX ) ) + dOffset;

        return dY;
      }

`void function_derivative( double `dX`, double* `pdParameters`, double* `pdDerivatives` )`

  This function calculates the partial derivatives of the model function for a give value of x `dX`. The partial derivatives should be returned in `pdDerivatives`. The order of the partial derivatives in the array `pdDerivatives` should correspond to the order of the parameters in `pdParameters` (i.e. if `pdParameters[0]` contains the parameter lambda for an exponential model, `pdDerivatives[0]` should contain the derivative of the model with respect to lambda).

`void function_initial_estimate( const double* `pdX`, const double* `pdY`, int `iLength`, double* `pdParameterEstimates` )`

  This function provides an initial estimate of the best-fit parameters to the fitting function. The array of x values and y values of the data points are provided in `pdX` and `pdY` respectively, and the number of data points is provided by `iLength`. You can use any or none of these parameters at your discretion to calculate the initial estimate. The function should put the calculated initial estimates in `pdParameterEstimates`, with the order of the estimates corresponding to the order of the parameters in `pdParameters` of `function_calculate` and `function_derivative`. Keep in mind that the initial estimate is important in determining whether or not the fitting function converges to a solution.

### Calling the Fitting Functions

Once all the required functions have been implemented, the fitting function from the included header file can be called:

    kstfit_nonlinear( inArrays, inArrayLens,
    		  inScalars, outArrays,
    		  outArrayLens, outScalars );

or

    kstfit_nonlinear_weighted( inArrays, inArrayLens,
                               inScalars, outArrays,
                               outArrayLens, outScalars );

depending on whether you are implementing a non-weighted fit or a weighted fit.

The function will return `0` on success, or `-1` on error, so it is simplest to set the return value of the exported C function to be equal to the return value of the fitting function. To maintain simplicity, the code for the plugin can simply pass the arguments given to the exported C function to the fitting function. Note, however, that inArrays must be structured as follows:

- `inArrays[0]` must contain the array of x coordinates of the data points

- `inArrays[1]` must contain the array of y coordinates of the data points

- `inArrays[2]` only exists if `kstfit_linear_weighted` is being called, and must contain the array of weights to use for the fit.

The easiest way to ensure that inArrays is structured correctly is to specify the correct order of input vectors in the XML file for the plugin.

After `kstfit_linear_unweighted` or `kstfit_linear_weighted` is called, `outArrays` and `outScalars` will be set as follows:

- `outArrays[0]` will contain the array of fitted y values.

- `outArrays[1]` will contain the array of residuals.

- `outArrays[2]` will contain the array of best-fit parameters that were estimated.

- `outArrays[3]` will contain the covariance matrix, returned row after row in an array.

- `outScalars[0]` will contain chi^2/nu, where chi^2 is the weighted sum of squares of the residuals, and nu is the degrees of freedom.

`outArrayLens` will be correctly set to indicate the length of each output array.

Ensure that the specified outputs in the XML file match those that the exported C function returns (which in most cases will simply be the outputs returned by the fitting function).

### Example

The following is an example of a non-linear fit plugin that performs a fit to an exponential model.

    /*
     *  Exponential fit plugin for KST.
     *  Copyright 2004, The University of British Columbia
     *  Released under the terms of the GPL.
     */

    #define NUM_PARAMS 3
    #define MAX_NUM_ITERATIONS 500

    #include "../non_linear.h"

    void function_initial_estimate( const double* pdX, const double* pdY,
                                    int iLength, double* pdParameterEstimates ) {
      KST_UNUSED( pdX )
      KST_UNUSED( pdY )
      KST_UNUSED( iLength )

      pdParameterEstimates[0] =  1.0;
      pdParameterEstimates[1] =  0.0;
      pdParameterEstimates[2] =  0.0;
    }

    double function_calculate( double dX, double* pdParameters ) {
      double dScale	 = pdParameters[0];
      double dLambda = pdParameters[1];
      double dOffset = pdParameters[2];
      double dY;

      dY  = ( dScale * exp( -dLambda * dX ) ) + dOffset;

      return dY;
    }

    void function_derivative( double dX, double* pdParameters, double* pdDerivatives ) {
      double dScale	 = pdParameters[0];
      double dLambda = pdParameters[1];
      double dExp;
      double ddScale;
      double ddLambda;
      double ddOffset;

      dExp     = exp( -dLambda * dX );
      ddScale  = dExp;
      ddLambda = -dX * dScale * dExp;
      ddOffset = 1.0;

      pdDerivatives[0] = ddScale;
      pdDerivatives[1] = ddLambda;
      pdDerivatives[2] = ddOffset;
    }

    extern "C" int kstfit_exponential(const double *const inArrays[], const int inArrayLens[],
    		const double inScalars[],
    		double *outArrays[], int outArrayLens[],
    		double outScalars[]);

    int kstfit_exponential(const double *const inArrays[], const int inArrayLens[],
    		const double inScalars[],
    		double *outArrays[], int outArrayLens[],
    		double outScalars[])
    {
      return kstfit_nonlinear( inArrays, inArrayLens,
                               inScalars, outArrays,
    			   outArrayLens, outScalars );
    }

## Creating Pass Filter Plugins

Kst provides header files to simplify the implementation of pass filter plugins. The use of these header files is described below.

### Header Files

The pass filter header file is located in `kst/plugins/pass_filters` of the Kst source tarball. The file is named `filters.h` To use this file, include it in the source code for your plugin:

    #include <../filters.h>

(by convention, we will place the source code for the plugin one directory below where the header files are).

### Required Functions

The `filters.h` header file contains a single function that calculates the Fourier transform of a supplied function, applies the supplied filter to the Fourier transform, and then calculates the inverse Fourier transform of the filtered Fourier transform. To supply the filter, the following function needs to be implemented in the source code for your plugin:

`double filter_calculate( double `dFreqValue`, const double `inScalars[]` )`

This function should calculate the filtered amplitude for the frequency `dFreqValue`. `inScalars[]` will contain the unaltered input scalars for the plugin, specified in the XML file. Most likely `inScalars[]` will contain cutoff frequencies or other properties of the filter. For example, to implement a Butterworth high-pass filter, `filter_calculate` could be implemented as follows:

    double filter_calculate( double dFreqValue, const double inScalars[] ) {
      double dValue;
      if( dFreqValue > 0.0 ) {
        dValue = 1.0 / ( 1.0 +
        		pow( inScalars[1] / dFreqValue, 2.0 * (double)inScalars[0] ) );
      } else {
        dValue = 0.0;
      }
      return dValue;
    }

### Calling the Filter Function

Once the required `filter_calculate` has been implemented, the filter function from the header file can be called:

`kst_pass_filter( `inArrays`,
`inArrayLens`,
`inScalars`,
`outArrays`,
`outArrayLens`,
`outScalars` );`

The arguments supplied to the exported C function can usually be passed to `kst_pass_filter` without modification. However, there are a few restrictions on the arguments:

- `inArrays[0]` must contain the array of data to filter.

- `inScalars` should contain the filter-specific parameters to be used by the `filter_calculate` function.

After the function call, `outArrays[0]` will contain the filtered array of data, and `outArrayLens` will be set appropriately. The `kst_pass_filter` function does not use `outScalars`.

### Example

The following is an example of a pass filter plugin that implements the Butterworth high-pass filter.

    /*
     *  Butterworth low pass filter plugin for KST.
     *  Copyright 2004, The University of British Columbia
     *  Released under the terms of the GPL.
     */

    #include <stdlib.h>
    #include <math.h>
    #include "../filters.h"

    extern "C" int butterworth_highpass(const double *const inArrays[], const int inArrayLens[],
    		const double inScalars[],
    		double *outArrays[], int outArrayLens[],
    		double outScalars[]);

    int butterworth_highpass(const double *const inArrays[], const int inArrayLens[],
    		const double inScalars[],
    		double *outArrays[], int outArrayLens[],
    		double outScalars[])
    {
      int iReturn;

      iReturn = kst_pass_filter( inArrays,
                                 inArrayLens,
                                 inScalars,
                                 outArrays,
                                 outArrayLens,
                                 outScalars );

      return iReturn;
    }

    double filter_calculate( double dFreqValue, const double inScalars[] ) {
      double dValue;

      if( dFreqValue > 0.0 ) {
        dValue = 1.0 / ( 1.0 + pow( inScalars[1] / dFreqValue, 2.0 * (double)inScalars[0] ) );
      } else {
        dValue = 0.0;
      }

      return dValue;
    }

## Appendix C. Supporting Additional File Formats

This section describes how to create additional readers for unsupported file formats. If you are not already familiar with data source concepts, please read Data Source Concepts

## Creating Datasource Readers

If you wish to use a file format other than those currently supported, you might choose to write custom datasource readers.

All Kst datasource readers are regular KDE plugins. Like all KDE plugins, each datasource reader must have a shared object file and a `*.desktop` file. Before writing the reader, the library name of the plugin must be decided. This name must be a valid variable name in C, as it will be used in the function names of the shared object. For example, the library name of the reader for ASCII files is “ascii”.

### Note

KDE plugins are not the same as the Kst plugins used to manipulate data. All references to plugins in this section are to KDE plugins.

### The Shared Object

A datasource reader should be a subclass of the abstract `KstDataSource` class. Ensure that you include the header file for `KstDataSource` in the source code for your datasource reader:

    #include <kstdatasource.h>

There are certain requirements that a datasource reader must meet. One requirement concerns the presence of exported C functions. Other requirements are consequences of the fact that datasource readers inherit from `KstDataSource`. Both sets of requirements, along with suggestions and general explanations, are provided in the following sections.

#### Exported C Functions

The exported C functions are listed below. In the following examples, all instances of `<libname>` should be replaced with the actual library name of the plugin.

`KstDataSource *create_<libname>(const QString& `filename`, const QString& `type`)`

  This function should create a new datasource reader of type `<libname>`, where `<libname>` is the library name of the plugin. A pointer of type `KstDataSource` to the new reader should be returned.

`bool understands_<libname>(const QString& `filename`)`

  This function should return true if the file specified by `filename` is of a valid type supported by this reader, and false otherwise. The function should check the contents of the file for validity, and not rely on any filename extensions.

`QStringList provides_<libname>()`

  This function should return a `QStringList` of the file types supported by this reader. The strings returned are arbitrary, but should be descriptive of and appropriate for the actual file types.

#### Protected Member Variables

`KstDataSource` contains various protected member variables that the custom datasource reader can use. These variables are described below.

`bool _valid`

  This variable should be `true` if the custom datasource reader is valid. Most likely the reader will be valid, unless there is an error condition (such as the data file being unreadable by the reader). This variable is used by the `isValid()` function of `KstDataSource`, which is usually not reimplemented in subclasses.

`QStringList _fieldList`

  This variable should hold a list of the field names in the data source.

`QString _filename`

  This variable should hold the name of the data file this datasource reader is associated with.

`QString _source`

  This variable should hold the type name of the source.

#### Virtual Functions

The `KstDataSource` class contains many virtual functions that should be redefined in the custom datasource reader. These functions are in the template files `template.h` and `template.cpp`, listed in the Example Templates section. Descriptions of the functions follow.

`TemplateSource(const QString&amp; `filename`, const QString&amp; `type`)`

  The constructor for the datasource reader. `filename` is the name of the file to read data from, and `type` is the type of data the file contains. This constructor should most likely invoke the `KstDataSource` constructor in the constructor initializer list, and probably call the `update` function listed below to initialize member variables. In particular, the `bool _valid` variable should be set appropriately.

`virtual ~TemplateSource()`

  The destructor for the datasource reader. Any dynamically allocated memory should be freed.

`virtual KstObject::UpdateType update(`int = -1`)`

  This function should read any new data entered in the data file since the last time `update` was called, and update the member variables appropriately. The function should return `KstObject::UPDATE` if the file contained changes, or `KstObject::NO_CHANGE` otherwise.

`virtual int readField(double *`v`, const QString &`field`, int `s`, int `n`)`

  This function should read `n` frames of data, starting at frame `s` from the field specified by the field name `field`, and return the contents in the array `v`. If `n` is less than 0, the function should instead read 1 sample starting at frame `s`. The number of frames that were read should be returned.

`virtual bool isValidField(const QString &`field`) const`

  This function should return true of the field specified by the field name `field` is a valid field in the current data source, or false if the field is not a valid field.

`virtual int samplesPerFrame(const QString& `field`)`

  This function should return the ratio of samples per frame for the field specified by the field name `field`. For data sources that do not make use of this concept, the number of samples per frame can be set to `1`.

`virtual int frameCount() const`

  This function should return the total number of frames in the data source, as of the last time `update` was called.

`virtual QString fileType() const ```

  This function should return the file type of the data file currently being used, usually the same as the `type` parameter that was passed to the constructor. Alternatively, it can contain an error message (to indicate, for example, that the file is not valid).

`virtual void save(QTextStream &`ts`)`

  This function should save the file description information to `ts`. In most cases the implementation provided by `KstDataSource` should be sufficient.

#### Example Templates

In general, the following two template files can be used to create new shared object files. Simply modify the function bodies as appropriate for your particular data source.

    /***************************************************************************
                      template.h  -  data source plugin template
                                 -------------------
        begin                : Fri Oct 17 2003
        copyright            : (C) 2003 The University of Toronto
        email                :
     ***************************************************************************/

    /***************************************************************************
     *                                                                         *
     *   This program is free software; you can redistribute it and/or modify  *
     *   it under the terms of the GNU General Public License as published by  *
     *   the Free Software Foundation; either version 2 of the License, or     *
     *   (at your option) any later version.                                   *
     *                                                                         *
     ***************************************************************************/

    #ifndef TEMPLATE_H
    #define TEMPLATE_H

    #include &lt;kstdatasource.h&gt;

    class TemplateSource : public KstDataSource {
    public:
      TemplateSource(const QString& filename, const QString& type);

      virtual ~TemplateSource();

      virtual KstObject::UpdateType update(int = -1);

      virtual int readField(double *v, const QString &field, int s, int n);

      virtual bool isValidField(const QString &field) const;

      virtual int samplesPerFrame(const QString &field);

      virtual int frameCount() const;

      virtual QString fileType() const;

      virtual void save(QTextStream &ts);
    };

    #endif

    /***************************************************************************
                        template.cpp  -  data source template
                                 -------------------
        begin                : Fri Oct 17 2003
        copyright            : (C) 2003 The University of Toronto
        email                :
     ***************************************************************************/

    /***************************************************************************
     *                                                                         *
     *   This program is free software; you can redistribute it and/or modify  *
     *   it under the terms of the GNU General Public License as published by  *
     *   the Free Software Foundation; either version 2 of the License, or     *
     *   (at your option) any later version.                                   *
     *                                                                         *
     ***************************************************************************/

    #include "template.h"

    TemplateSource::TemplateSource(const QString& filename, const QString& type)
    : KstDataSource(filename, type) {
    }

    TemplateSource::~TemplateSource() {
    }

    KstObject::UpdateType TemplateSource::update(int u) {
      Q_UNUSED(u)
      return KstObject::NO_CHANGE;
    }

    int TemplateSource::readField(double *v, const QString& field, int s, int n) {
      Q_UNUSED(v)
      Q_UNUSED(field)
      Q_UNUSED(s)
      Q_UNUSED(n)
      return -1;
    }

    bool TemplateSource::isValidField(const QString& field) const {
      Q_UNUSED(field)
      return false;
    }

    int TemplateSource::samplesPerFrame(const QString &field) {
      Q_UNUSED(field)
      return 0;
    }

    int TemplateSource::frameCount() const {
      return 0;
    }

    QString TemplateSource::fileType() const {
      return QString::null;
    }

    void TemplateSource::save(QTextStream &ts) {
      KstDataSource::save(ts);
    }

    extern "C" {
    KstDataSource *create_template(const QString& filename, const QString& type) {
      return new TemplateSource(filename, type);
    }

    QStringList provides_template() {
      QStringList rc;
      // create the stringlist
      return rc;
    }

    bool understands_template(const QString& filename) {
      // determine if it is an X file
      Q_UNUSED(filename)
      return false;
    }

    }

### The `.desktop` File

The following is an example of a `.desktop` file for the template plugin:

    [Desktop Entry]
    Encoding=UTF-8
    Type=Service
    ServiceTypes=Kst Data Source
    X-KDE-ModuleType=Plugin
    X-Kst-Plugin-Library=template
    X-Kst-Plugin-Author=The University of Toronto
    Name=File Reader Template
    Comment=Long description of the file reader template.

You should add translations in additional languages for the Name and Comment fields by adding additional Name and Comment fields with `[xx]` appended to the end of the field names, where `xx` is the two-letter language code. For example, to add Spanish translations, the following lines would need to be added:

    Name[es]=Plantilla de lectura de ficheros
    Comment[es]=Plantilla de código para hacer un complemento de lectura de ficheros.

The field `X-Kst-Plugin-Library` should be exactly the same as the decided library name for the plugin.

### Compiling and Copying

To compile and install the new custom datasource reader, create a new directory under `kst/datasources` of the source package. Place the source files for the object, along with the `.desktop` file in the new directory. Then, edit `kst/datasources/Makefile.am` so that `SUBDIRS` contains the name of the new subdirectory. For example, if the new subdirectory is called `template`, `SUBDIRS` might be changed to the following:

    SUBDIRS=ascii dirfile frame indirect template $(PIOLIB_SUBDIR) $(FITSIO_SUBDIR)

After the required files are in the newly created subdirectory, a `Makefile.am` needs to be created in there as well. Use the following sample as a template, replacing all instances of “template” with your custom library name in `kde_module_LTLIBRARIES`, `kstdata_template_la_SOURCES` and `services_DATA`.

    INCLUDES=-I$(srcdir)/../.. $(all_includes)

    kde_module_LTLIBRARIES=kstdata_template.la

    kstdata_template_la_LDFLAGS=$(all_libraries) -module -avoid-version
    kstdata_template_la_SOURCES=template.cpp

    METASOURCES=AUTO

    services_DATA=kstdata_template.desktop
    servicesdir=$(kde_servicesdir)/kst

Once this is done, you can compile and re-install Kst from the modified source package, or alternatively, only install the new libraries, like follows (using the “template” subdirectory as an example). First change to the root directory of the Kst source package. Then,

    ./configure --prefix=`kde-config --prefix`
    cd ./kst/datasources/template
    make
    make install

Restart Kst and the new datasource reader should be loaded.

## Appendix D. The Kst DCOP Interface

Kst provides an interface that acts as a client using the the KDE Desktop COmmunications Protocol (DCOP). The set of functions provided in the `KstIface` interface allows for easy control of Kst by other applications or scripts. For more information on DCOP, refer to this webpage.

## Appendix E. The Debug Dialog

The Kst debug dialog can sometimes provide useful information about certain problems encountered, and contains all notices, warnings, and errors logged by Kst. To access the debug dialog, select Debug Kst... from the Help menu.

## The Debug Log

The debug log is located on the Log tab of the debug dialog. The following lists the different messages that can appear in the log, with brief explanations and suggested actions (where appropriate).

Type | Message | Explanation/Suggested Action |
Unknown | Kst Extension %1 loaded | None. |
Unknown | Error trying to load Kst extension %1. Code=%2, \"%3\" | Make sure extension exists, meets the requirements for a Kst extension, and is in the correct location. |
Unknown | Unable to find required vector [%1] for data object %2. | Ensure the indicated vector exists in the Data Manager. If so, try recreating the data object. |
Unknown | Unable to find required scalar [%1] for data object %2. | Ensure that the indicated scalar exists (try searching in View Scalars of the Data menu. |
Unknown | Error loading data-source plugin [%1]: %2 | A datasource reader (KDE plugin) could not be loaded. Make sure the data-source reader meets requirements described in Creating Datasource Readers and is compiled correctly. If it is a built-in datasource reader, try recompiling and installing it again from the source package. |
Unknown | Scanning for data-source plugins. | Kst is scanning for datasource readers. No action required. |
Unknown | No data in file %1 | Make sure file is supported by one of the datasource readers, and that the data is formatted correctly and is not corrupt. |
Unknown | Unsupported element '%1' in file %2 | Ensure that the file is not corrupt, and meets the specifications for the file format. |
Unknown | Unable to find X vector for %2: [%1] | ??? |
Unknown | Unable to find Y vector for %2: [%1] | ??? |
Unknown | Undefined justification %1 in label \"%2\" | This should not happen. Most likely it is the result of a bug. |
Unknown | Internal error: No X scale type checked in %1. | None. |
Unknown | Internal error: No Y scale type checked in %1. | None. |
Unknown | Unable to load plugin %1 for \"%2\" | Make sure that the plugin meets the requirements described in Creating Additional Plugins. In particular, make sure the shared object and `*.xml` file are in the same directory. If the plugin is a built-in plugin, try re-installing the plugin from the source package. |
Unknown | Input vector [%1] for plugin %2 not found. Unable to continue. | Ensure that the `*.xml` file for the plugin specifies all the inputs correctly and in the correct order. Check the source code for the shared object to ensure that it is using the correct arrays from the input array. Also ensure that the specified input vector still exists (check in the Data Manager). |
Unknown | Output vector [%1] for plugin %2 not found. Unable to continue. | Ensure that the `*.xml` file for the plugin specifies all the outputs correctly and in the correct order. Check the source code for the shared object to ensure that it is outputting the correct arrays in the output array. |
Unknown | Data file for vector %1 was not opened. | ??? |
Unknown | Error parsing XML file '%1'; skipping. | Check the XML file to make sure it has correct syntax and form for the intended use. If is an XML file for a plugin, check Creating Additional Plugins for more information. |
Unknown | Detected disappearance of '%1'. | None. |
Unknown | Could not parse xml file '%1'. | Check the XML file to make sure it has correct syntax and form for the intended use. If is an XML file for a plugin, check Creating Additional Plugins for more information. |
Unknown | Could not find library '%1' while loading plugin. | Make sure the library exists and is in the correct location. If this is a built-in plugin, try recompiling and installing the plugin again. |
Unknown | Could not find symbol '%1' in plugin %2. | A required C symbol could not be found in the plugin. Make sure the plugin meets the requirements described in Creating Additional Plugins. If this is a built-in plugin, try recompiling and re-installing the plugin. |
Unknown | The %1 font was not found and was replaced by the %2 font; as a result, some labels may not display correctly." | If this causes problems, install the missing font. |

## Appendix F. Installation

The following sections contain detailed instructions for obtaining, compiling, and installing Kst along with any optional libraries or packages. If you use a package management system, you may use it to install Kst instead.

## Obtaining Kst

Kst is part of the kdeextragear-2 module of KDE. You can also download the latest version separately from the Kst website . If you wish to download Kst from CVS, it is available via anonymous CVS for KDE or via the KDE WebCVS repository.

## Installing Kst from Source

The following sections detail how to compile and install Kst from source code.

### Requirements

Kst v1.0.0 requires the KDE 3.1 libraries and Qt™ 3.1. Almost all major Linux® distributions have packages for KDE and Qt™. Since Qt™ is a dependency of KDE, having the required version of KDE should be sufficient. It is recommended that you refer to your particular distribution's documentation for KDE library installation. Note that the entire KDE desktop environment is not required—in most cases, look for packages called `kdebase-*` and `kdelibs-*`. Alternatively, more information is available on the KDE website.

### Optional Libraries and Packages

The following libraries and packages are optional, but provide full plugin and data source functionality in Kst if installed. The installation instructions assume you have root access on your system.

### Note

You may already have some or all of these libraries and packages installed, in which case there is no need to reinstall them. Also, check first to see if pre-compiled binaries for the libraries and packages exist in your distribution's package management system, as it may be easier to install the binary packages.

#### GNU Scientific Library (GSL)

The GNU Scientific Library provides a variety of mathematical operations for the built-in Kst plugins. Having GSL installed enables a variety of plugins such as linear and non-linear fitting, correlation, and interpolation 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

#### CFITSIO

The CFITSIO library 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/. You only need to install the library if you anticipate reading or writing to the FITS file format.

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 change the directory specified for the `--prefix` option, but the most common directory is `/usr`

### Compiling and Installing

Once all of the prerequisites have been met on your system you can compile and install Kst. It is assumed that you have already downloaded the Kst source package. If not, please see Obtaining Kst.

The simplest way to install Kst is:

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

replacing [ver] with the version of Kst you have.

### Important

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.