<chapter id="common-tasks">
<title>Common Tasks</title>

<para>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.</para>

<sect1 id="plotting-simple-graphs">
<title>Plotting Simple Graphs</title>

<para>How to plot a simple points-on-a-grid graph</para>

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

<orderedlist>

<listitem><para>Choose your data file. &kst; will read many types of
data file, the simplest being a plain text (<acronym>ASCII</acronym>)
file with the data in columns. For definiteness, we'll use the data
file from <xref linkend="gettingstarted"/>, with the filename <filename>simpledata.dat</filename>.</para>
</listitem>

<listitem><para>Open &kst;. You are presented with the
<guilabel>QuickStart</guilabel> dialog:

<screenshot>
<screeninfo>The QuickStart dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-quickstart.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The QuickStart dialog</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para>Click on <guibutton>Data Wizard</guibutton>, and, in the wizard
that appears, select your data file using the <guibutton>Open
File</guibutton> button:
<inlinemediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-open-file-button.png" format="PNG"
/>
</imageobject>
</inlinemediaobject>.
</para>
</listitem>

<listitem>
<para>The <guibutton>Next</guibutton> page is where you select which
data to use. Column 2 in the data file contains the y-axis values, so
tick the box next to 2 in the <guilabel>Field/Column</guilabel> list on the
left-hand side. The INDEX field is a special field created by &kst;,
but we won't be using it for this example.</para>
</listitem>

<listitem>
<para>Under <guilabel>Plot Types</guilabel>, leave the default
<guilabel>XY</guilabel> as it is, but change the <guilabel>X axis
vector</guilabel> to 1.</para>
</listitem>

<listitem>
<para>On the next page, we'll just change one thing: under
<guilabel>Curve Style</guilabel>, select <guilabel>Points
only</guilabel> to draw just the data points, and not lines joining them.</para>
</listitem>

<listitem>
<para>Click on <guibutton>Finish</guibutton> and you're done! The new
plot appears in the main &kst; window.</para>
</listitem>

</orderedlist>

<!-- TODO: Link to other places in the handbook, perhaps with a little -->
<!-- more description -->

</sect1>

<sect1 id="curve-fitting">
<title>Curve Fitting</title>

<para>&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 <xref linkend="plotting-simple-graphs"/>.</para>

<orderedlist>

<listitem><para>With the plot done, open the plugins dialog from
<menuchoice><guimenu>Data</guimenu><guimenuitem>New Plugin</guimenuitem>
</menuchoice>.</para>
</listitem>

<listitem><para>The <guilabel>Plot selection</guilabel> combo box
contains all the &kst; fitting plugins, and more. Since the example
data here are quadratic, we'll use the <guilabel>Fit
polynomial</guilabel> plugin. Select the <guilabel>X Array</guilabel>
and <guilabel>Y Array</guilabel> vectors for the fit &ndash; if you
used the default names when producing the plot, select
<guilabel>V0-1</guilabel> for the <guilabel>X Array</guilabel> and
<guilabel>V1-2</guilabel> for the <guilabel>Y Array</guilabel>. </para>
</listitem>

<listitem><para>As it happens, the <guilabel>Order</guilabel> of the
polynomial is set
to 2 by default, which is what we want. You can set the
<guilabel>Order</guilabel> to any integer, one of the predefined
scalar quantities, or some statistical value based on one of the
available vectors (for example, <guilabel>V1-2-Mean</guilabel>).</para>
</listitem>

<listitem><para>Hit <guibutton>OK</guibutton> to generate the
values.</para>
</listitem>

</orderedlist>

<para>That's all we need to do to generate the values, so now we need
to look at the output of the fitting process. Select
<menuchoice><guimenu>Data</guimenu><guimenuitem>View Fit Results</guimenuitem>
</menuchoice> from the menus, and the fit values are shown in the
dialog which appears: the coefficients for x^2, x^1 and x^0 (the
constant), along with the chi-squared value and the covariances
between the coefficients.</para> 

<para>The curve generated by the fitting is not automatically
superimposed on the data points. To do this, use the <guilabel>New
Curve</guilabel> dialog by selecting
<menuchoice><guimenu>Data</guimenu><guimenuitem>New Curve...</guimenuitem>
</menuchoice>. For the <guilabel>X axis vector</guilabel>, select
V0-1 (if you've been using the automatically generated names), and for
the <guilabel>Y axis vector</guilabel>, choose
<quote>P1-kstfit_polynomial_unweighted-Y Fitted</quote>. Click on
<guibutton>OK</guibutton> once you've set any other options that you
want. The curve is plotted in its own window: for this example, we
don't want that, so delete the new plot by right-clicking on it and
choosing <guimenuitem>Delete</guimenuitem> in the popup menu that
appears.</para>

<para>Now, to add the curve fit to the data plot, open the Plot dialog
from <menuchoice><guimenu>Plots</guimenu><guimenuitem>Edit
Plot...</guimenuitem>
</menuchoice>. On the <guilabel>Content</guilabel> tab that
appears, the vector containing the fit data is shown under
<guilabel>Available objects</guilabel>. Select this vector, and add it
to the <guilabel>Displayed objects</guilabel> list by clicking on the
left arrow button. Click on <guibutton>Apply Edits</guibutton>, and
then <guibutton>Close</guibutton>, and you're finished.</para>

</sect1>

<sect1 id="plotting-a-power-spectrum">
<title>Plotting a Power Spectrum</title>

<para>&kst; makes plotting power spectra extremely easy. There are two
ways to do this: with the Data Wizard, or by creating a power spectrum
from an existing vector.</para>

<sect2 id="power-spectra-data-wizard">
<title>Power spectra with the Data Wizard</title>

<para>This is almost the same as plotting a simple graph. Here are the
full instructions:</para>

<para>Open the <guibutton>Data Wizard</guibutton> and select your data
file using the <guibutton>Open File</guibutton> button:

<inlinemediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-open-file-button.png" format="PNG"
/>
</imageobject>
</inlinemediaobject>.
</para>

<orderedlist>
<listitem>
<para>The <guibutton>Next</guibutton> page is where you select which
data to plot the power spectrum of. Column 2 in the data file contains the y-axis values, so
tick the box next to 2 in the <guilabel>Field/Column</guilabel> list on the
left-hand side.</para>
</listitem>

<listitem>
<para>Under <guilabel>Plot Types</guilabel>, select <guilabel>Power
spectrum</guilabel>. There are also some options specifying how the
power spectrum is calculated, which we'll leave as defaults in this example.</para>
</listitem>

<listitem>
<para>On the <guilabel>Next</guilabel> page, the options specific to a
power spectrum are found under <guilabel>Power Spectrum Axis
Mode</guilabel>. The x and y axes can both be made logarithmic here.</para>
</listitem>

<listitem>
<para>Click on <guibutton>Finish</guibutton> and you're done! The new
plot appears in the main &kst; window.</para>
</listitem>

</orderedlist>


</sect2>

<sect2 id="power-spectra-existing-plot">
<title>Power Spectra from an existing plot</title>
<para>Using the <filename>simpledata.dat</filename> example from <xref
linkend="plotting-simple-graphs"/>, we can do the following to produce
its power spectrum:</para>

<orderedlist>

<listitem><para>Open the <guilabel>Power Spectrum dialog</guilabel>
from <menuchoice><guimenu>Data</guimenu><guimenuitem>New Power
Spectrum...</guimenuitem></menuchoice>.</para>
</listitem>

<listitem><para>From the <guilabel>Data vector</guilabel> combo box,
choose the vector representing your data. In our
<filename>simpledata.dat</filename> example, the required vector is
called V1-2.</para>
</listitem>

<listitem><para>Click on <guibutton>OK</guibutton> and the power
spectrum is displayed in a new plot.</para>
</listitem>

</orderedlist>

</sect2>

</sect1>

<sect1 id="using-kst-from-the-command-line">
<title>Using &kst; from the Command Line</title>

<para>The command line switches to perform the tasks above</para>

</sect1>

<!--
The interface for this is not finalized, so it's commented out for -->
<!--now, but definitely something useful to have in the future -->

<!--
<sect1 id="making-a-color-map">
<title>Making a Color Map</title>
<para>How to make a color map, since the interface isn't very intuitive</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:
-->
