# Common Tasks

This chapter contains instructions for performing basic tasks with &kst;. It runs through the method for performing each task in the simplest way. Links to the sections of the handbook with more in-depth information are also given.

## Plotting Simple Graphs

The first thing you'll want to do with &kst; is probably to plot a simple graph. Here's the procedure:

1. Choose your data file. &kst; will read many types of data file, the simplest being a plain text (ASCII) file with the data in columns. For this tutorial, we'll create a simple data file. Copy and paste this simple 10-line set of data into a text file, and save it as `simple.dat`:

       x  y
       -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

   ASCII is only one of the many file types &kst; is capable of reading. For further details on file types, see the Datasources section.

2. Open &kst;. If you are presented with the QuickStart dialog, then click on the Data Wizard button. If the QuickStart dialog does not appear, then you can click the toolbar button to open the Data Wizard. In the wizard that appears, you can enter the pathname of the simple.dat file manually, or select it using the Open File icon openfile-icon which appears next to the path entry textbox. We have put x and y labels on the first line of our data file, so click the Configure... button and set up the data source as shown below.

   Plotting Simple Graphs - Configure ASCII

3. The Next page is where you select which data to use. If you've configured the ASCII datasource correctly, the field names will have been read from the first entry of the datafile and x and y will be entries in the Available list on the left-hand side of the page. Move the y field to theSelected list using the arrow buttons in the center of the window. The INDEX field is a special field created by &kst;; it can be used as X-axis data when the data source does not provide a data vector for the X-axis.

4. Clicking the Next button again allows you to select Data Presentation options. Under Plot Types, leave the default XY as it is, but change the X Axis Vector to Create From Field: x.

5. On the Next page, 'Plot Layout', we'll just change one thing: under Curve Style, select Points only to draw just the data points, and not the lines joining them.

6. Click on Finish and you're done! The new plot appears in the main &kst; window.

   Plotting Simple Graphs

It's also possible to quickly create plots from the command line using &kst;, similar to Gnuplot. In the case of the `simple.dat` file, we can produce a simple plot using the first column (or field) of the file as the x vector, with the second column as a y vector, by entering the following at the command line:

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

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.

## Customizing Plot Settings

For the previous curve plot, suppose you want to change the default x and y labels, and add a title for it.

To change the default setting for the plot, first, right click anywhere on the plot, a context menu will appear as below.

context_menu
context_menu

Choose Edit..., and the Edit Plot dialog will appear.

To add or change the Y/X label and title of the plot, click on the Appearence tab.

appearance
appearance

In the textbox beside Y axis/X axis: enter the Y axis/X axis label you want. In this case, Distance(m) and Time(s).

In the textbox beside Top label: enter the title for the plot. In this case: Distance vs Time. In addition, you can choose the justification of the title by selecting Left, Right or Center in the Justification textbox.

To change the settings of the X or Y axis, such as choosing the scale of the X/Y axis or adding gridlines, click on the X Axis or Y Axis tab.

x_y_axis
x_y_axis

Change the minor ticks of the X axis to be 1, and choose to show both the major and minor gridlines for the X axis.

For the Y axis, for which no screenshot is shown, select Reverse for the Scale, change the Minor ticks to be 1.

To change the range of X or Y axis, choose the Range tab.

range
range

Change the range of x axis to be From 0 To 8.

Finally, you can highlight some important part of the plot by using the Markers tab.

marker
marker

For example, if time = 4 s is important, enter 4 in the New textbox and click on the Add button. A marker line will appear at the position of time = 4. You can customize the marker line in Appearance. In this example, choose blue for the line color, broken line for the Type and 5 for the Weight.

The customized plot will look like this:

plot
plot

## Curve Fitting

&kst; also provides functions for many different types of curve fitting: linear, quadratic, sinusoidal, and more. As an example, we'll do a simple polynomial fit to the curve we plotted previously, in the Plotting Simple Graphs section.

1. Right click on the simple graphs plot which you've created and select y from the Fit submenu in the context menu which appears.

   Curve Fitting - Fit Context Menu

2. Now a New Plugin dialog will appear which allows you to configure the fit. Since the example data here are quadratic, we'll use the Fit polynomial plugin. Choose this from the Plugin Selection drop-list. As it happens, the Order of the polynomial is set to 2 by default, which is what we want. You can set the Order to any integer, one of the predefined scalar quantities, or some statistical value based on one of the available vectors (e.g. the Standard Deviation of x, [x/Sigma]).

   There are several Output fields where you can enter text to be used as the unique name for the vectors and scalars generated by this fit. For more information, you can read the section on the Fit Polynomial in the Plugins chapter.

3. Hit OK to perform the fit. A new curve showing the best fit polynomial will be automatically added to the plot containing the original curve. A new label object is also added to the plot containing the fitted coefficients for x^2, x^1 and x^0 (the constant).

   Curve Fitting - Plotted Curve

Not all of the fit results are shown in the new label. The covariances for the fit coefficients, as well as the Chi-Square value for the fit can be accessed from the View Fit Results dialog. Select Data View Fit Results from the main menu, and choose the fit which you are interested in from the drop down list. The results are shown in a table:

Curve Fitting - Fit Results

## Generating a Histogram

&kst; contains built in routines to generate histograms from data. For this tutorial, we'll look at the histogram of a vector containing normally distributed numbers.

We'll generate this vector using a perl script. Copy the following code into a file called generate_normal.pl:

    sub gaussian_rand { # from the Perl Cookbook. (O'Reilly, 1998)
        my ($u1, $u2);  # uniformly distributed random numbers
        my $w;          # variance, then a weight
        my ($g1, $g2);  # gaussian-distributed numbers

        do {
            $u1 = 2 * rand() - 1;
            $u2 = 2 * rand() - 1;
            $w = $u1*$u1 + $u2*$u2;
        } while ( $w >= 1 );

        $w = sqrt( (-2 * log($w))  / $w );
        $g2 = $u1 * $w;
        $g1 = $u2 * $w;
        # return both if wanted, else just one
        return wantarray ? ($g1, $g2) : $g1;
    }

    srand(time() ^($$ + ($$ <<15))) ; # initialize the RNG.
    for ($x=0;$x < 10000;$x++) {
            print gaussian_rand() . "\n";
    }

Now execute the script with the command:

``perl generate_normal.pl > normal.dat``

This will generate an ASCII file `normal.dat` containing random numbers with a gaussian distribution centered at 0 with a standard deviation of 1. Import this data into &kst;, and plot it as points with INDEX as the x-axis vector (if this gives you trouble, you may want to see the Getting Started section on Importing Data. You should see something which resembles the following:

Generating Histograms - Scatter Plot
Generating Histograms - Scatter Plot

Now we are ready to generate the histogram itself. Select Data New Histogram.... Select the Data Vector which has just been created from `normal.dat`. There are several options relating to bin choices. For quick generation of histograms, it is usually easiest to just press the Auto-Bin feature. This will select an optimal bin size and range for the given data.

Click the OK button to generate the histogram.

Generating Histograms - Histogram
Generating Histograms - Histogram

## Creating an Event Monitor

&kst; has many features which are oriented toward real-time data. One of the most useful of these features is the "Event Monitor" data object. Event monitors check conditions on data vectors. A common use for them is to provide warnings about unusual features in incoming data. They can provide feedback in a number of ways:

- Messages in the &kst; debug log.

- Automated Electronic Logbook (ELOG) entries.

- Email notification.

In this tutorial, we will create an event monitor to provide debug log notification about statistically unlikely spikes in a data stream. More information about Event Monitor data objects can be found here

First we'll need a script to generate some simulated realtime data. Copy the following into a file called `simrealtime.pl`

    #!/usr/bin/perl

    open(OUTPUT, ">$ARGV[0]") || die "Can't open $ARGV[0]: $!";

    srand(1); # (badly) initialize the RNG.

    for ($x=0;;$x++) {
            open(OUTPUT, ">>$ARGV[0]") || die "Can't open $ARGV[0]: $!";
            $rn = rand();
            if ($rn > .99) {
                    $rn = $rn + 5;
            } else {
                    $rn = $rn - .5;
            }
            print OUTPUT $rn . "\n";
            close(OUTPUT);
            print "Created " . $x . " entries. Press Enter to Continue ...";
            $dummy=<STDIN>
    }

This perl script will generate random data, uniformly distributed in the range [-0.5, 0.5], with occasional spikes. Make the script executable and run it using the commands...

``chmod a+x simrealtime.pl``

``./simrealtime.pl simulated.dat``

In order to simulate realtime data, the script will not generate all of its output at once, but will prompt the user before it outputs each entry. Press the enter key several times to get the data set started. Now, in a separate terminal, instruct &kst; to plot the data using the command...

``kst -y 1 simulated.dat``

Depending on the number of data points which you have generated so far, your plot should look something like the graph below, possibly without the large spike in the middle.

Creating Event Monitor - Initial Plot
Creating Event Monitor - Initial Plot

Now, return to the terminal where the `simrealtime.pl` script is running and press the enter key a few more times. You should see the plot you've made in &kst; update automatically as new data is added to the `simulated.dat` stream.

Suppose that we would like to receive notification every time a large spike occurs in our incoming data stream. This can be done using an event monitor. Select the menu-item Data New Event Monitor..., and configure the new event monitor's settings as shown below.

Creating Event Monitor - New Event Monitor
Creating Event Monitor - New Event Monitor

The settings in the Expression text box configure the event monitor to report entries in the vector 1 which are more than 5 standard deviations from its mean. This is a fairly simple event monitor. Much more powerful event monitors can be created using the large collection of scalars which &kst; maintains, and the many operators which can make comparisons between vectors.

We will have our events logged as Warnings in the &kst; Debug Log. As you can see, there are several other possible event reporting methods. These are explained in more detail in the documentation for Event Monitors.

Click the OK button to create the new event monitor. Now, access the &kst; Debug Log by selecting the Help Debug Kst... menu-item and clicking the Log tab. You may see that a spike has been detected. If not, return to the terminal where you are running the `simrealtime.pl` script and continue generating new data until a number of spikes are visible in your plot. About 1% of the data should be spikes. Spikes which occur near the beginning of the data stream may not have been detected, because &kst; didn't yet have enough data to establish a reliable estimate of the standard deviation of the vector 1. After generating a few hundred data points, your Log may look something like this:

Creating Event Monitor - Debug Log
Creating Event Monitor - Debug Log

Once you have an event monitor up and running, it's sometimes useful to have &kst; indicate on your plots where events have occurred. This is best done using objects called Plot Markers. To create plot markers for events, we need to have a Curve Data Object for the events in question. Create a curve data object now by selecting Data New Curve... and configure the new curve with the options shown below.

Creating Event Monitor - New Curve
Creating Event Monitor - New Curve

Now we are ready to create plot markers. Right click on the data plot, and on the context menu which appears select Edit.... Then select the Markers tab and configure it to use our event monitor curve as shown below:

Creating Event Monitor - Maker Settings
Creating Event Monitor - Maker Settings

Click the OK button to create the markers. Vertical lines will now appear on the data plot, indicating the position of the spikes. The usefulness of plot markers is that they will always stretch across the entire y-axis, regardless of the zoom level, as shown in the screenshot below.

marker
marker

## Creating a Power Spectrum

&kst; contains built-in routines to generate power spectrum from data. The following example shows how to create a power spectrum.

First, plot the normal distributed data vector generated by the `perl script`: generate_normal.pl in the histogram tutorial. The plot of the normal distributed data is shown below:

vector plot
vector plot

To create a power spectrum from this data vector, choose Data New Spectrum...

choose new spectrum
choose new spectrum

Then, the dialog for creating a new specturm appears:

creating power spectrum dialog
creating power spectrum dialog

In the text box beside Data vector: select the vector that you want to create a power spectrum from. The default is INDEX, but you can change it by selecting from the dropdown textbox. You can change the name of the specturm in the Unique name text box. FFT option will be explained in detail later in the spectrum section of the data chapter. For a quick look of the resulting spectrum, just use the default choices for the FFT option and click OK. The following spectrum is generated:

spectrum plot
spectrum plot