<chapter id="intro">
<title>Introduction</title>

<sect1 id="intro-whatiskst">
<title>What is &kst;?</title>
<para>
&kst; is a data plotting and analysis program.  Some of its features include:
<itemizedlist>
<listitem><para>Robust plotting of live <quote>streaming</quote> data, including support for automated monitoring of events and notification.</para></listitem>
<listitem><para>Powerful plugin and extensions support.</para></listitem>
<listitem><para>A large selection of built-in plotting and analysis functions, including: histograms, equations, curve fitting, filtering, and power spectra.</para></listitem>
<listitem><para>Powerful graphical user interface, with unique view modes for easy plot manipulation.</para></listitem>
<listitem><para>Color mapping and contour mapping capabilities for three-dimensional data.</para></listitem>
<listitem><para>Support for several popular data formats including FITS, netCDF, and HEALPix, as well as ASCII. Additional formats can be accommodated with plugins.</para></listitem>
<listitem><para>KstScript, a JavaScript based scripting language which allows automation of complicated workflows.</para></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="intro-gettingstarted">
<title>Getting Started</title>
<para>
This is a brief introductory tutorial to the fundamental features of &kst;. We will cover...
<itemizedlist>
<listitem><para><link linkend="intro-gettingstarted-importingdata">Importing and plotting raw data</link></para></listitem>
<listitem><para><link linkend="intro-gettingstarted-plotmanipulation">Plot manipulation</link></para></listitem>
<listitem><para><link linkend="intro-gettingstarted-basicanalysis">Basic data analysis with &kst;</link></para></listitem>
</itemizedlist>
</para>

<sect2 id="intro-gettingstarted-importingdata">
<title>Importing Data</title>

<para>
Let's start by seeing how raw data can be imported into &kst; using the graphical interface (this can also be done using the command line, for details see the appendix on  <link linkend="command-lineoptions">Command Line Options</link>).
</para>

<para>
Begin by running &kst;. When you do this for the first time, a <quote>QuickStart</quote> Dialog should appear by default.
</para>

<screenshot>
<screeninfo>QuickStart Dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-quickstartdialog.png" format="PNG" />
</imageobject>
<textobject>
<phrase>QuickStart Dialog Screenshot</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>
This dialog has a list of your recently opened &kst; sessions, as well as a link to the <guilabel>Data Wizard</guilabel>. The <guilabel>Data Wizard</guilabel> allows data to be imported into &kst; using the graphical interface. We'll run through using it now.
</para>

<para>
Click the <guibutton>Data Wizard</guibutton> button. A data source dialog will appear which allows you to select a file or network resource (e.g. HTTP address) to use as a data source. &kst; determines the format of the source by its extension and contents.
</para>

<para>
We will import data from a file called <quote>gyrodata.dat</quote> which should be included in your &kst; installation. The location of this file is <filename class="directory">$<envar>KDEDIR</envar>/share/apps/kst/tutorial/gyrodata.dat</filename>,
where <filename class="directory">$<envar>KDEDIR</envar></filename> is
the location in which &kde; is installed on your system (you can find
this using the command <command>kde-config --prefix</command>).
</para>

<para>Select <filename>gyrodata.dat</filename> for opening. &kst; should report the data source as type ASCII, which means that the data is in delimited plain text format. More options can be seen by clicking the <guibutton>Configure</guibutton> button. The options for the gyrodata.dat file should be as shown below:
</para>

<screenshot>
<screeninfo>Datasources - Configure ASCII</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-gs-configureascii.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>

<para>Close the Configure Data Source Dialog and click the <guibutton>Next</guibutton> button. This will lead to a pane where you can select the fields from the data source which you'd like to work with. In the case of ASCII data, each field is a column in the text file. Select the data from the 1st, 2nd, and 3rd fields. The INDEX field is a supplementary field created by &kst;. It contains integers from 0 to N-1, where N is the number of <link linkend="data-sources-concepts-frames">frames</link> in the data file. Once you've selected the proper fields, the selection pane should look like this:
</para>

<screenshot>
<screeninfo>Data Wizard - Select Data Dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-gs-selectdata.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>

<para>
Click the <guibutton>Next</guibutton> button again, to get to the <guilabel>Data Presentation Pane</guilabel>. This allows you to select some basic and frequently modified options for the plots which are about to be created. 
</para>

<para>
The <guilabel>Data Range</guilabel> section is used to specify the
subset of data to read from the selected vectors in the input file. For more information about this pane see the <link linkend="data-tools-wizard">Data Wizard</link> documentation.
</para>

<para>
Configure the Data Presentation Pane to look like the following:
</para>

<screenshot>
<screeninfo>Data Wizard Data Presentation Pane</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-gs-presentation.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>

<para>
This tells &kst; that we would like to read all of the available data for our chosen fields, and that we would like to generate plots with the x-axis of the data as its INDEX. INDEX is an automatically generated vector which gives the position of the data elements within the file. 
</para>

<para>
Clicking the <guibutton>Next</guibutton> button again takes us to the final Data Wizard pane, where there are options to determine the appearance of the plotted data. We can select a curve style, decide whether labels and legends should be generated from the available field names, and decide which plots the curves should be placed into. Again, the default options should be fine for now.
</para>

<screenshot>
<screeninfo>Data Wizard - Configure Plot Layout Plane</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-gs-final.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>

<para>
Now, click the <guibutton>Finish</guibutton> button to generate the plots. Your &kst; session should now look something like this:
</para>

<screenshot>
<screeninfo>Getting Started - Initial Plots</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-gs-initialplots.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Getting Started - Initial Plots</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>
Congratulations! You've just done some basic plotting in &kst;. Generating these plots took a bit of effort, so we should save the current &kst; session (it will be used in the next section of this tutorial). Select <guimenuitem>Save As...</guimenuitem> from the <guimenu>File</guimenu> menu, and save the session as
<filename>mykstsession.kst</filename>:
</para>

<screenshot>
<screeninfo>Saving a KST session</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-gs-saveas.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Saving a KST session</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>
Saving the &kst; session allows you to restore your plots later.
</para>
</sect2>

<sect2 id="intro-gettingstarted-plotmanipulation">
<title>Plot Manipulation</title>
<para>
Now that you are comfortable with creating plots from imported data in &kst;, we can explore some of the plot manipulation features available through the graphical user interface.
Start &kst; from the command-line with the
<filename>mykstsession.kst</filename> file you saved earlier:
</para>
<screen><userinput><command>kst mykstsession.kst</command></userinput></screen>
<para>
All the plots you created in the <link linkend="intro-gettingstarted-importingdata">Importing Data</link> section should now be loaded in &kst;. Examine the plots with the y axis label of <literal>Column 2</literal>.  To take a closer look at the plot, right click on it and select the <guimenuitem>Maximize</guimenuitem> menu item, as shown below:
</para>
<screenshot>
<screeninfo>Maximizing a plot</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-gs-maximize.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Maximizing a plot</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>
The plot you selected will now be maximized within the current window. Note that the
data is still dense in this plot, so it would be useful to zoom in on an interesting area. To do so, make sure you are in <guimenuitem>XY Mouse Zoom</guimenuitem> mode (select <guimenuitem>XY Mouse Zoom</guimenuitem> from the <guimenu>Plots</guimenu> menu, or
click the <inlinemediaobject><imageobject><imagedata
fileref="Icon-kst-xymousezoom.png"
format="PNG"/></imageobject></inlinemediaobject> toolbar
button). Then, simply drag a rectangle around the area you're interested in.  Note that the coordinates of the mouse cursor are displayed in
the lower right corner of the &kst; window (if they are not, ensure
that <guimenuitem>Show Statusbar</guimenuitem> is checked in the
<guimenu>Settings</guimenu> menu).
</para>

<para>
The plot axes will change to <quote>zoom in</quote> on the selected area of the plot.  Suppose that you would like to view some data just outside the region you have zoomed into. This can be done with &kst;'s scrolling feature. Right-click on the plot and select <guimenuitem>Up</guimenuitem>, <guimenuitem>Down</guimenuitem>, <guimenuitem>Left</guimenuitem>, or <guimenuitem>Right</guimenuitem> from the <guimenu>Scroll</guimenu> submenu.  The plot will scroll accordingly. Of course, it is usually easier to use the shortcut key associated with the menu item; this is true for most of the zooming and scrolling functions.  The shortcut keys for scrolling are the <keysym>Arrow</keysym> keys, so the quickest way to scroll upwards would be to hold down the <keysym>Up Arrow</keysym> key.  To return to maximum zoom at any time, right-click on the plot and select <guimenuitem>Zoom Maximum</guimenuitem> from the <guisubmenu>Zoom</guisubmenu> submenu (or type <keycap>M</keycap>, the shortcut key associated with <guimenuitem>Zoom Maximum</guimenuitem>).
</para>

<para>
Restore the size of the plot by right-clicking it and unchecking the <guimenuitem>Maximize</guimenuitem> option.
</para>

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

<screenshot>
<screeninfo>Tied Zoom</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-gs-tiedzoom.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Tied Zoom</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>
Before we try zooming in, we should delete the <quote>Column 1</quote> plot, which we won't be working with any more. Right-click on this plot and select <guimenuitem>Delete</guimenuitem>.  A hole will be left in the plotting window. We can remedy this by right-clicking anywhere inside the window and selecting <menuchoice><guimenu>Cleanup Layout</guimenu><guimenuitem>Default Tile</guimenuitem></menuchoice>.  Now the two remaining plots should share maximal space inside the window.  Return to XY Mouse Zoom mode when you are done.
</para>

<para>
Now try zooming in on any portion of the upper plot.  You will find that the lower plot becomes blank.  This is because the lower plot axes have changed to match the upper plot axes, and there is no data in that particular region of the lower plot. Type <keycap>M</keycap> while the mouse cursor is over either plot to return to maximum zoom on both plots.  Now hold down <keycap>Ctrl</keycap> (this is
equivalent to selecting <guimenu>X Mouse Zoom Mode</guimenu> from the
<guimenu>Plots</guimenu> menu or clicking the
<inlinemediaobject><imageobject><imagedata fileref="Icon-kst-xmousezoom.png" format="PNG"/></imageobject></inlinemediaobject> toolbar button). The mouse cursor will change shape as visual feedback.  While keeping <keycap>Ctrl</keycap> held down, drag a rectangle in the upper plot. Note that the height of the dotted rectangle is restricted so that only the x axis will be zoomed.  Now both plots will display data when zoomed in, as the y axis for either plot was not changed.
</para>
<tip>
<para>
You can quickly tie or untie all the plots in the window by selecting
<guimenuitem>Tied Zoom</guimenuitem> from the <guimenu>Plots</guimenu>
menu or by clicking the <inlinemediaobject><imageobject><imagedata
fileref="Icon-kst-tiedzoom.png"
format="PNG"/></imageobject></inlinemediaobject> toolbar button.
</para>
</tip>
<para>
When you are finished experimenting with the zooming features, you can
save the <filename>mykstsession.kst</filename> file again, with the changes which have been made.
</para>
</sect2>

<sect2 id="intro-gettingstarted-basicanalysis">
<title>Basic Analysis and the Data Manager</title>

<para>
There is more to &kst; than simple plotting and viewing of data.  From the data wizard, you have already seen that &kst; has the ability to create power spectra of data. In fact, &kst; is also capable of creating other data objects such as histograms, equations, and plugins. A utility called the <link linkend="data-overview-datamanager">Data Manager</link> can help you to do this.
</para>

<para>
Open the data manager now by clicking the <inlinemediaobject><imageobject><imagedata fileref="Icon-kst-datamanager.png"
format="PNG"/></imageobject></inlinemediaobject> toolbar button, or by selecting <guimenuitem>Data Manager</guimenuitem> from the <guimenu>Data</guimenu> menu.
</para>

<screenshot>
<screeninfo>The Data Manager</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-gs-datamanager.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The Data Manager</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>
The Data Manager contains the definitive list of data objects in the
current &kst; session.  It also allows you to edit or create new data
objects.  As you can see, there are currently 3 curves (each created from a
pair of vectors) and four data vectors listed. A summary is given for each object; see the <link linkend="data-overview-datamanager">Data Manager</link> section for more information.
</para>

<para>
We saw earlier that when we attempted tied-zoom in XY-Zoom-Mode that the Column 2 and Column 3 data have different y-offsets. Suppose that we would like to compare them on the same graph. To do this, we will have to shift the mean of one of the plots. We can do this easily using an Equation Object.
</para>

<para>
Begin the process of creating an Equation by clicking the corresponding button under the <guibutton>Create Data Object</guibutton> tab on the left side of the Data Manager. A dialog will appear to create the new object. Configure this dialog as shown below:
</para>

<screenshot>
<screeninfo>New Equation</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-gs-equationnew.png" format="PNG" />
</imageobject>
<textobject>
<phrase>New Equation</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>
This equation takes values from the data vector [2], subtracts the scalar [2/mean], then adds the scalar [3/mean] to make a new vector which is [2] shifted vertically to have the same mean as the data vector [3]. Note from the Scalars drop-down menu that &kst; maintains a collection of simple statistics on all of its vectors (as well as many other objects). These can frequently prove useful.
</para>

<para>
Click the <guibutton>OK</guibutton> button of the New Equation dialog. Now a new curve has been added to the plot with y-axis label <quote>Column 3</quote>. If we return to the &kst; plot window, we can zoom in on the <quote>Column 3</quote> plot. Comparing the data, we can see what we suspected, that data vector [2] is essentially the same as [3], but exactly out of phase:
</para>

<screenshot>
<screeninfo>Getting Started Final Plots</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-intro-gs-finalplots.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>

<para>
This concludes our basic introduction to &kst;. We encourage you to experiment with the program now; there is clearly a lot of functionality in &kst; which hasn't been covered in this tutorial. Most of it can be found intuitively. You may want to look at some of the entries in the <link linkend="commontasks">Common Tasks</link> chapter. Good luck!
</para>

</sect2>
</sect1>
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:true
sgml-parent-document:("index.docbook" "book" "chapter")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->