[kst-plot] docbook/kst/tutorial: build system needs a tutorial directory.
Barth Netterfield
null at kde.org
Wed Mar 21 21:41:47 UTC 2018
Git commit 93f55dfc21d6dcd8bb898b91c261e583b660b178 by Barth Netterfield.
Committed on 21/03/2018 at 21:41.
Pushed by netterfield into branch 'master'.
build system needs a tutorial directory.
A +862 -0 docbook/kst/tutorial/tutorial.docbook
https://commits.kde.org/kst-plot/93f55dfc21d6dcd8bb898b91c261e583b660b178
diff --git a/docbook/kst/tutorial/tutorial.docbook b/docbook/kst/tutorial/tutorial.docbook
new file mode 100644
index 00000000..885ab343
--- /dev/null
+++ b/docbook/kst/tutorial/tutorial.docbook
@@ -0,0 +1,862 @@
+<chapter id="tutorial">
+
+<title>The &kst; Tutorial</title>
+
+
+<sect1 id="Welcome">
+<title>Welcome</title>
+<para>
+Welcome to &kst;! In a few minutes, you will be on your way to
+exploring the rich features of this plotting and data manipulation
+package. Here are just some of the tasks you can accomplish using
+&kst;:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>
+Quickly plot multiple graphs using only the command-line.
+</para>
+</listitem>
+<listitem>
+<para>
+Analyze data using an extensive set of tools including histograms,
+power spectra, and custom equations.
+</para>
+</listitem>
+<listitem>
+<para>
+Effortlessly zoom in and out of interesting areas of plots using
+either the mouse or keyboard
+</para>
+</listitem>
+<listitem>
+<para>
+Monitor live streaming data using &kst;'s real-time plotting capabilities.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+This tutorial covers the basics of installing, running, and working
+with &kst;. You are invited to further investigate any features at
+any time. All features are documented in the rest of this
+Handbook.</para>
+
+</sect1>
+
+<sect1 id="commandline">
+<title>Creating plots from the Command-line</title>
+<para>
+A common use of &kst; is to quickly produce plots of data from the
+command-line. This method of producing plots requires almost no
+knowledge of &kst;'s graphical user interface, yet produces immediate,
+useful results.
+</para>
+
+<para>
+The following instructions assume you are working in a broadly bash-compatible shell, such as you would in linux or osX.
+</para>
+
+<para>
+To obtain an overview of all available &kst; command-line options, type:
+<screen><userinput><command>kst2 --help</command></userinput></screen>
+</para>
+<para>
+A syntax description and list of commands similar to the following will be displayed:
+<screen>
+KST Command Line Usage
+************************
+*** Load a kst file: ***
+kst [OPTIONS] kstfile
+
+[OPTIONS] will override the datasource parameters for all data sources in the kst file:
+ -F <datasource>
+ -f <startframe>
+ -n <numframes>
+ -s <frames per sample>
+ -a (apply averaging filter: requires -s)
+
+************************
+*** Read a data file ***
+kst datasource OPTIONS [datasource OPTIONS []]
+
+OPTIONS are read and interpreted in order. Except for data object options, all are applied to all future data objects, unless later overridden.
+Output Options:
+ --print <filename> Print to file and exit.
+ --landscape Print in landscape mode.
+ --portrait Print in portrait mode.
+ --Letter Print to Letter sized paper.
+ --A4 Print to A4 sized paper.
+ --png <filename> Render to a png image, and exit.
+ --pngHeight <height> Height of png image (pixels)
+ --pngWidth <width> Width of png image (pixels)
+File Options:
+ -f <startframe> default: 'end' counts from end.
+ -n <numframes> default: 'end' reads to end of file
+ -s <frames per sample> default: 0 (read every sample)
+ -a apply averaging filter: requires -s
+
+Ascii File Options - for ascii files only: these are all sticky
+ --asciiDataStart <Line> Data starts here. Files start at line 1.
+ --asciiFieldNames <Line> Field names are in this row.
+ --asciiNoFieldNames Fields are named for their data column
+ --asciiReadUnits <Line> Read units from line <Line>
+ --asciiNoUnits Do not read units
+ --asciiSpaceDelim Columns are Space/tab delimited
+ --asciiDelim <char> Columns are dlimited with <char>
+ --asciiFixedWidth <w> Columns have width <w>
+ --asciiNoFixedWidth Columns are delimited, not fixed width
+ --asciiDecimalDot Use a . as a decimal separator (ie, 10.1)
+ --asciiDecimalComma Use a , as a decimal separator (ie, 10,1)
+Position:
+ -P <plot name>: Place curves in one plot.
+ -A Place future curves in individual plots.
+ -m <columns> Layout plots in columns
+ -T <tab name> Place future curves a new tab.
+Appearance
+ -d: use points for the next curve
+ -l: use lines for the next curve
+ -b: use bargraph for the next curve
+ --xlabel <X Label> Set X label of all future plots.
+ --ylabel <Y Label> Set Y label of all future plots.
+ --xlabelauto AutoSet X label of all future plots.
+ --ylabelauto AutoSet Y label of all future plots.
+Data Object Modifiers
+ -x <field>: Create vector and use as X vector for curves.
+ -e <field>: Create vector and use as Y-error vector for next -y.
+ -r <rate>: sample rate (spectra and spectograms).
+Data Objects:
+ -y <field> plot an XY curve of field.
+ -p <field> plot the spectrum of field.
+ -h <field> plot a histogram of field.
+ -z <field> plot an image of matrix field.
+
+****************
+*** Examples ***
+
+Data sources and fields:
+Plot all data in column 2 from data.dat.
+ kst data.dat -y 2
+
+Same as above, except only read 20 lines, starting at line 10.
+ kst data.dat -f 10 -n 20 -y 2
+
+... also read col 1. One plot per curve.
+ kst data.dat -f 10 -n 20 -y 1 -y 2
+
+Read col 1 from data2.dat and col 1 from data.dat
+ kst data.dat -f 10 -n 20 -y 2 data2.dat -y 1
+
+Same as above, except read 40 lines starting at 30 in data2.dat
+ kst data.dat -f 10 -n 20 -y 2 data2.dat -f 30 -n 40 -y 1
+
+Specify the X vector and error bars:
+Plot x = col 1 and Y = col 2 and error flags = col 3 from data.dat
+ kst data.dat -x 1 -e 3 -y 2
+
+Get the X vector from data1.dat, and the Y vector from data2.dat.
+ kst data1.dat -x 1 data2.dat -y 1
+
+Placement:
+Plot column 2 and column 3 in plot P1 and column 4 in plot P2
+ kst data.dat -P P1 -y 2 -y 3 -P P2 -y 4
+
+
+</screen>
+</para>
+
+<para>
+
+This tutorial uses a demo ascii data file which is available at <ulink
+url="gyrodata.dat.gz">gyrodata.dat.gz</ulink>.
+Download the file with your browser, and gunzip it.
+
+<screen><userinput><command>gunzip gyrodata.dat.gz</command></userinput></screen>
+</para>
+
+<para>
+We will first take a look at reading the ASCII file
+<filename>gyrodata.dat</filename> that we just downloaded.
+ASCII files are one of the many file types &kst; is capable of
+reading. In ASCII files, data is arranged in columns, with each
+column corresponding to a field, and the column numbers (beginning
+with 1 from left to right) corresponding to field names. This
+particular ASCII file contains 3 columns, and thus has field names 1,
+2, and 3. To produce a plot of the first column, simply type:
+
+<screen><userinput><command>kst2 gyrodata.dat -y 1</command></userinput></screen>
+
+</para>
+<para>
+All the data in the first column will be plotted:
+</para>
+<screenshot>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-tutorial-gyro1.png" format="PNG"/>
+</imageobject>
+</mediaobject>
+</screenshot>
+<para>
+Note that no field was specified for the X axis of the plot, so &kst;
+used the default INDEX vector. The INDEX vector is a
+special vector in &kst; that contains integers from 0 to N-1, where N
+is the number of frames read in the corresponding Y axis vector.
+Close &kst; by selecting <guimenuitem>Quit</guimenuitem> from the
+<guimenu>File</guimenu> menu, or by typing <keycombo
+action="simul">&Ctrl;<keycap>Q</keycap></keycombo>.
+</para>
+
+<para>
+<filename>gyrodata.dat</filename> contains 20000 frames, so you may
+wish to only look at a portion of the data. To only plot 10000 frames
+starting from frame 7000, type:
+
+<screen><userinput><command>kst2 gyrodata.dat -f 7000 -n 10000 -y 1</command></userinput></screen>
+
+</para>
+
+<para>
+One of &kst;'s strengths is its ability to plot real-time data.
+Imagine that new data was being continually added to the end of
+<filename>gyrodata.dat</filename>. In such a scenario, it would be
+useful to only plot the most recent portion of the data. To plot only
+the last 1000 frames of <filename>gyrodata.dat</filename>, enter the
+following:
+
+<screen><userinput><command>kst2 gyrodata.dat -n 1000 -y 1</command></userinput></screen>
+</para>
+<para>
+If <filename>gyrodata.dat</filename> was being updated, the plot would
+continuously scroll to display only the last 1000 frames.
+</para>
+
+<para>
+Note that the description of the <option>y</option> option states that
+Multiple instances of the <option>y</option> option are allowed. This allows quick
+plotting of more than one curve. To plot
+all three fields in <filename>gyrodata.dat</filename> in separate
+plots, arranged in one column, enter the following:
+
+<screen><userinput><command>kst2 gyrodata.dat -m 1 -y 1 -y 2 -y 3 </command></userinput></screen>
+
+</para>
+<para>
+The <option>m</option> option specifies that the plots should be in a single column.
+</para>
+
+<screenshot>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-tutorial-gyro-multiple.png" format="PNG"/>
+</imageobject>
+</mediaobject>
+</screenshot>
+
+<para>
+To plot column 1 in one plot, and columns 2 and three in a second plot, displayed side by side enter:
+
+<screen><userinput><command>kst2 gyrodata.dat -m 2 -P 1 -y 1 -P 2 -y 2 -y 3 </command></userinput></screen>
+
+</para>
+
+<screenshot>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-tutorial-gyro-multiple2.png" format="PNG"/>
+</imageobject>
+</mediaobject>
+</screenshot>
+
+</sect1>
+
+<sect1 id="datawizard-tour">
+<title>Creating plots with the Data Wizard</title>
+<para>
+&kst; can also be completely controlled through the graphical user interface,
+without ever using the command line. In this section, we will look at
+the Data Wizard, which a quick and easy way of creating vectors,
+curves, and plots in &kst; from data files. To launch the wizard,
+select <guimenuitem>Data Wizard...</guimenuitem> from the
+<guimenu>Data</guimenu> menu or click the
+
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="Icon-kst-datawizard.png" format="PNG"/>
+</imageobject>
+</inlinemediaobject>
+
+button on the toolbar. You will be prompted to select a data source by the
+following dialog:
+
+<screenshot>
+<screeninfo>Data Wizard Screen 1</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-datawizard1.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Data Wizard Screen 2</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+Select the <filename>gyrodata.dat</filename> file used in the
+command-line examples. If you have completed the command-line exercises
+in the previous sections, then the file should be listed in the recent
+files list, as shown. Simply click on it to select it. Otherwise,
+enter the full path in the top text entry box (or click on the
+
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="Icon-kst-fileselect.png" format="PNG"/>
+</imageobject>
+</inlinemediaobject>
+
+icon and browse to the file). Once you have selected the file, the <guibutton>Next</guibutton>
+button will be enabled. Click on it to proceed to the next page.
+
+The following window will be displayed:
+</para>
+
+<screenshot>
+<screeninfo>Data Wizard Screen 2</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-datawizard2.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Data Wizard Screen 2</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+Fields in <filename>gyrodata.dat</filename> available to be plotted are
+listed in the <guilabel>Available data</guilabel> box on the left. Fields
+that have been selected for plotting are listed in the <guilabel>Selected data</guilabel>
+box on the right. In the image shown, <guilabel>Column 1</guilabel> has been
+selected for plotting.
+</para>
+
+<para>
+Select <guilabel>Column 1</guilabel>, <guilabel>Column 2</guilabel>, and
+<guilabel>Column 3</guilabel> for plotting by moving them to the
+<guilabel>Selected data</guilabel> box.
+</para>
+
+<para>
+To move a field from <guilabel>Available data</guilabel> to
+<guilabel>Selected data</guilabel>, double click on it, or
+highlight it (with mouse or keyboard) and click on the
+
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="Icon-kst-right-arrow.png" format="PNG"/>
+</imageobject>
+</inlinemediaobject>
+
+icon. As well as using the mouse or keyboard, you may highlight fields by
+entering a string to match into the text box above the list. Wildcards such as <literal>*</literal>,
+<literal>?</literal> and <literal>[ ]</literal> are
+supported.
+</para>
+
+<para>
+Click <guibutton>Next</guibutton> once you have selected the three columns of data.
+</para>
+
+
+<screenshot>
+<screeninfo>Data Wizard Screen 3</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-datawizard3.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Data Wizard Screen 2</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+The next tab is used to select the data range to be plotted, and whether to
+create XY plots, spectrum plots, or both.
+</para>
+
+
+<para>
+The <guilabel>Data Range</guilabel> 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 <quote>frames</quote>. For ASCII
+files such as <filename>gyrodata.dat</filename>, a frame is simply a row of
+data, though for other formats this can be more complicated. For a detailed description of this
+concept, see <xref linkend="Frames"/>.
+</para>
+
+<variablelist>
+<varlistentry>
+<term>
+<guilabel>Start</guilabel>, <guilabel>End</guilabel>, <guilabel>Count from end</guilabel>,
+<guilabel>Range</guilabel>, and <guilabel>Read to end</guilabel>
+</term>
+<listitem>
+<para>
+Using these five settings, the lower and upper boundaries of the data
+range can be set. The settings in the above image are set to read the
+entire data file (starting at frame 0, and reading to the end).
+</para>
+
+<para>
+If new data were being appended to the end of the file in real time, then the range
+would be continuously increasing and &kst; would update to reflect this. If instead
+one wanted to only display the last 1000 frames of the file, one would instead select
+<guilabel>Count from end</guilabel> and enter 1000 in <guilabel>Range</guilabel>.
+&kst; would scroll the data along as new data were appended to the data file.
+</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<guilabel>Read 1 sample per N frames</guilabel> and <guilabel>Boxcar
+filter first</guilabel>
+</term>
+<listitem>
+<para>
+The number of data points plotted can be reduced using this option.
+If <guilabel>Read 1 sample
+per N frames</guilabel> is not selected, all samples in the selected
+range will be read. Alternatively, frames in the data file can be
+skipped by selecting <guilabel>Read 1 sample per N frames</guilabel>.
+For now, read all of the data by deselecting <guilabel>Read 1 sample
+per N frames</guilabel>, as shown.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+
+
+<para>
+In this tutorial, we are only going to plot the gyroscope time series, and not spectra.
+To do this, select <guilabel>Create XY plots</guilabel> and deselect
+<guilabel>Create Spectra Plots</guilabel> as shown.
+</para>
+
+<para>
+Set the X axis vectors for the curves to be The vector to be <guilabel>INDEX</guilabel>
+by selecting <guilabel>Create from field</guilabel> and selecting INDEX in
+vector selector, as shown.
+</para>
+
+<para>
+The <guilabel>FFT Options</guilabel> subsection in the <guilabel>Plot
+Types</guilabel> section is available only if a power spectrum is to
+be plotted. This tutorial will not deal with the details of power
+spectra.
+</para>
+
+<para>
+Once you are satisfied with all the settings, click
+<guibutton>Next</guibutton> to advance to the next window.
+</para>
+
+<screenshot>
+<screeninfo>Data Wizard Screen 4</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-datawizard4.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Data Wizard Screen 3</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+From here, you can change general plotting settings. Most of the
+settings are self-explanatory. Select <guilabel>1 new plot per
+curve</guilabel> for <guilabel>Curve Placement</guilabel>.
+</para>
+
+
+<para>
+Once you are satisfied with all the settings, click <guibutton>Finish</guibutton> and the plots will be generated:
+</para>
+<screenshot>
+<screeninfo>The Generated Plots</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-tutorial-datawizard-done.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The Generated Plots</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+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>
+
+<para>
+Saving a &kst; session saves all the plots, data objects (you will learn about these later), and layouts that exist
+at the time of saving.
+</para>
+<para>
+Once the file has been saved, you can exit &kst;.
+</para>
+</sect1>
+
+<sect1 id="mousezooming">
+<title>The Basics of Plot Manipulation</title>
+<para>
+Now that you are comfortable with creating plots in &kst;, we can explore some of the plot manipulation features
+available through the &kst; graphical user interface.
+Start &kst; and load the <filename>mykstsession.kst</filename> file you saved earlier.
+This can be done one of three ways:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+ From the command line: <userinput><command>kst mykstsession.kst</command></userinput>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Selecting <guimenuitem>Open</guimenuitem> from the toolbar or from the
+ <guimenuitem>File</guimenuitem> menu and selecting <filename>mykstsession.kst</filename>
+ from wherever you saved it.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Selecting <filename>mykstsession.kst</filename> from
+ <guimenuitem>Recent Files</guimenuitem> in the <guimenuitem>File</guimenuitem> menu.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+All the plots you created earlier should now be loaded in &kst;.
+Consider the plot of Column 1.
+To take a closer look at that plot, right
+click in it and select the <guimenuitem>Maximize</guimenuitem> menu
+item (see below). Notice that the menu item shows that <guimenuitem>Z</guimenuitem>
+is a shortcut for this, so you could also just type <keycap>Z</keycap> in the plot rather than
+using the context menu for this. Selecting <guimenuitem>Maximize</guimenuitem> (either with <keycap>Z</keycap> or with the menu) will cause the selected plot to fill the entire kst window.
+</para>
+<screenshot>
+<screeninfo>Maximizing a plot</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-zoom.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Maximizing a plot</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<screenshot>
+<screeninfo>A plot after Maximizing</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-zoomed.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Maximizing a plot</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+<para>
+Selecting <guimenuitem>Maximize</guimenuitem> (or typing <keycap>Z</keycap> in the plot) again will restore it the plots to their previous
+arrangement. This is especially valuable if you have a grid of many small plots
+and want to temporarily look at just one of them. Obviously typing <keycap>Z</keycap> is going to be the most convienient way
+to do this, but the context menu is there in case you forget.
+</para>
+
+<para>
+In &kst;, it is very easy to zoom and scroll the data, using either the
+mouse or the keyboard. To do this you should be in <guimenuitem>XY Zoom/Scroll</guimenuitem>
+mode, selected by selecting the
+
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="Icon-kst-xymousezoom.png" format="PNG"/>
+</imageobject>
+</inlinemediaobject>
+
+icon in the tool bar. This is the default mode.
+</para>
+<para>
+To zoom into a region of interest, left-click drag a box in the window with the mouse.
+When you release the mouse, the window will zoom in X and Y into the region you selected.
+Holding &Shift; when you do this will cause the plot to zoom only in Y.
+Holding &Ctrl; when you do this will cause the plot to zoom only in X.
+</para>
+<para>
+Arrow keys scroll the plot. Arrow keys with &Shift; held down will change the scale.
+The <keycap>M</keycap> key auto-zooms the plots to view all of the data. Play around with these
+options to become familier with the various options.
+</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 an instrument. Since
+these two plots are related, it can be useful to zoom and scroll them
+simultaneously. Click on the circles located at the top right corners
+of the two plots. They should turn dark in color to indicate that
+the two plots are now tied together:
+</para>
+
+<screenshot>
+<screeninfo>Tied Zoom</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-tiedzoom.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Tied Zoom</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+Now try zooming in with the mouse on a portion of the green curve in
+the middle plot. You will find
+that the lower plot will become blank. This is because the lower plot
+axes have changed to match the upper plot axes, and there is no data
+in that particular region of the lower plot. Type <keycap>M</keycap>
+while the mouse cursor is over either plot to return to maximum zoom
+on both plots. Now hold down &Ctrl; (this is
+equivalent to selecting <guimenu>X Mouse Zoom Mode</guimenu> from the
+<guimenu>Mode</guimenu> menu or clicking the
+<inlinemediaobject><imageobject><imagedata
+fileref="Icon-kst-xmousezoom.png"
+format="PNG"/></imageobject></inlinemediaobject> toolbar button). If you
+then move the mouse, you will see that it is now dragging a vertical line
+the heght of the plots in both of the plots that are tied to gether.
+While keeping
+&Ctrl; held down, drag a rectangle in the middle plot.
+While dragging, the region you are selecting will be displayed in both
+tied plots. Both plots will rescale to the region you have selected.
+</para>
+
+<screenshot>
+<screeninfo>Tied Zoom</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-tiedzooming.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Tied Zoom</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+
+<para>
+As with the mouse actions, the keyboard based zoom/scrolling actions
+described earlier will now be applied to both plots.
+</para>
+<tip>
+<para>
+You can quickly tie or untie all the plots in the window by selecting
+<guimenuitem>Toggle Tied Zoom</guimenuitem> from the <guimenu>Mode</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
+close &kst;. There is no need to save the plots this time (unless you
+wish to).
+</para>
+
+</sect1>
+
+
+
+<sect1 id="overviewdataobjects">
+<title>A Brief Overview of Data Objects</title>
+<para>
+In addition to simple plotting, &kst; has the ability to do real time analysis of
+data using a number of <quote>Data Objects</quote>, which include spectra, equations,
+histograms, fits, and filters.
+</para>
+
+<para>
+As a quick demo of Data Objects, lets create a spectrum. Start &kst; and re-load
+<filename>mykstsession.kst</filename> that you created in previous sections.
+Then, from the <guimenu>Create</guimenu> menu select
+<guimenuitem>Power Spectrum</guimenuitem>. The New Power Spectrum menu will appear.
+</para>
+
+<screenshot>
+<screeninfo>New Spectrum Dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-new-spectrum.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>The New Spectrum Dialog</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>Fill out the dialog as shown. Make sure you select <quote>Column 3 (V4)</quote>
+ as the Data vector, set the FFT length to <quote>2^13</quote>, Sample rate to
+ <quote>60</quote> and select <quote>In new tab</quote> under Placement. Then select
+ <guibutton>OK</guibutton>. A plot of the spectrum of <quote>Column 3 (V4)</quote>
+ will appear in a new tab.
+</para>
+
+<screenshot>
+<screeninfo>Spectrum</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-spectrum_linear.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Spectrum</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+ It is hard to see any details in this plot - a log-log plot would be
+ much easier. To toggle the Y axis to log press <keycap>l</keycap> (that is, small <keycap>L</keycap>) and
+ to toggle the X axis to log press <keycap>g</keycap>. (These options
+ are also available in the context menu under the
+ <guimenuitem>Zoom</guimenuitem> submenu in case you forget the keyboard
+ commands). The plot will now be log-log, as shown:
+</para>
+
+<screenshot>
+<screeninfo>Spectrum</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-spectrum_log.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Spectrum</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+ Hitting <keycap>l</keycap> (small <keycap>L</keycap>) and <keycap>g</keycap> will toggle back to linear axis.
+</para>
+
+<para>
+ From the <guimenu>Create</guimenu> you can similarly create histograms, spectrograms and equations
+ of fields you have loaded.
+</para>
+</sect1>
+
+<sect1 id="tutorial-filters">
+<title>Filters</title>
+<para>
+With &kst;, we can apply a variety of fits and filters to vectors in kst.
+The results of these will be updated in real time as new data comes in.
+To demonstrate this, load in the first 1000 samples of second column of
+<filename>gyrodata.dat</filename>
+using either the Data Wizard, as demonstrated earlier, or from the command line:
+
+<screen><userinput><command>kst2 gyrodata.dat -f 0 -n 1000 -y 2</command></userinput></screen>
+
+</para>
+<para>
+ Once it is loaded, right click in the plot and select <guimenuitem>Column 1 vs INDEX (C1)</guimenuitem>
+ from the <guimenu>Filter</guimenu> menu, as shown:
+</para>
+
+<screenshot>
+<screeninfo>Spectrum</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-filter-menu.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Spectrum</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+
+<para>
+This will bring up the New Filter Dialog:
+</para>
+
+<screenshot>
+<screeninfo>Spectrum</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-filter-dialog.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Spectrum</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+ Fill out the dialog as shown. In particular,
+ select <guimenuitem>Low Pass Filter</guimenuitem> as the Plugin, set
+ <guilabel>Cutoff Frequency/Sample Rate</guilabel> to 0.05, and select
+ <guilabel>Place in existing plot</guilabel>. Here we have also set the
+ line to be red, and the <guilabel>Weight</guilabel> to 2, so the line will
+ be more visible. When you are satisfied, select <guibutton>OK</guibutton>.
+</para>
+<para>
+ This will add the low-pass filtered data as a new curve in the plot:
+</para>
+
+<screenshot>
+<screeninfo>Filtered Curve</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="Screenshot-kst-filtered-curve.png" format="PNG" />
+</imageobject>
+<textobject>
+<phrase>Filtered Curve</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+ In the same way you can fit a variety of functions to curves using the
+ <guimenu>Fit</guimenu> submenu after right-clicking in a plot.
+</para>
+
+</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:
+-->
+
More information about the kde-doc-english
mailing list