[Kst] branches/work/kst/newdocs/doc/kst

Duncan Hanson duncan.hanson at gmail.com
Wed Nov 22 01:30:34 CET 2006 

SVN commit 606850 by dhanson:

Update docs for Histogram, Power Spectra, and Image data objects. Update docs for the data menu as well.

 AM            Screenshot-kst-histogramwindow.png  
 AM            Screenshot-kst-imagewindow.png  
 AM            Screenshot-kst-powerspectrawindow.png  
 M  +103 -42   data-chapter.docbook  
 M  +6 -2      plotsandwindows-chapter.docbook  


** branches/work/kst/newdocs/doc/kst/Screenshot-kst-histogramwindow.png #property svn:mime-type
   + application/octet-stream
** branches/work/kst/newdocs/doc/kst/Screenshot-kst-imagewindow.png #property svn:mime-type
   + application/octet-stream
** branches/work/kst/newdocs/doc/kst/Screenshot-kst-powerspectrawindow.png #property svn:mime-type
   + application/octet-stream
--- branches/work/kst/newdocs/doc/kst/data-chapter.docbook #606849:606850
@@ -860,15 +860,15 @@
 <sect2 id="Histograms">
 <title>Histograms</title>
 <para>
-A histogram data object simply represents a histogram of a particular vector.  Histogram objects are plottable.
+This object calculates the histogram of a chosen vector. 
 </para>
 <para>
-The following is a screenshot of the window displayed when creating or editing histograms.  Explanations of the
+The following is a screenshot of the histogram specific options when creating or editing histograms.  Explanations of the
 settings are listed below.
 </para>
 
 <screenshot>
-<screeninfo>Edit Equation</screeninfo>
+<screeninfo>Edit Histogram</screeninfo>
 <mediaobject>
 <imageobject>
 <imagedata fileref="Screenshot-kst-histogramwindow.png" format="PNG" />
@@ -990,8 +990,7 @@
 <listitem>
 <para>
 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.
+the number of elements in the largest bin (the bin with the greatest number of elements).
 </para>
 </listitem>
 </varlistentry>
@@ -1005,15 +1004,14 @@
 <sect2 id="power-spectra">
 <title>Power Spectra</title>
 <para>
-"The below definitions assume basic knowledge of power spectra&mdash;for further details,
-refer to Numerical Recipes in C: The Art of Scientific Computing, published by Cambridge University Press."
-
+The below definitions assume basic knowledge of power spectra&mdash;for further details, refer to "Numerical Recipes in C: The Art of Scientific Computing", published by Cambridge University Press.
+</para>
+<para>
 A power spectrum data object represents the power spectrum of a vector, defined as
 <quote>the square root of the absolute value of the
 mean of the interleaved Fast Fourier Transforms of length <literal>2^x</literal> of the vector</quote>, where x is the
-value entered in the <guilabel>FFT Length</guilabel> selection box. The below definitions assume
-basic knowledge of power spectra&mdash;for further details,
-refer to Numerical Recipes in C: The Art of Scientific Computing, published by Cambridge University Press.
+value entered in the <guilabel>FFT Length</guilabel> selection box. 
+<!--- FIXME: we need a clearer definition of the power spectrum. this should be done after the code in PSDcalculator has been documented. -->
 </para>
 
 <screenshot>
@@ -1031,7 +1029,7 @@
 <sect3 id="powerspectracurvecontents">
 <title>Curve Contents</title>
 <para>
-The source vector, as well as basic power spectrum properties, can be modified from this section.
+The source vector for the power spectrum can be modified from this section.
 </para>
 
 <variablelist>
@@ -1045,28 +1043,57 @@
 </para>
 </listitem>
 </varlistentry>
+</variablelist>
+</sect3>
 
+<sect3 id="powerspectrafftoptions">
+<title>FFT Options</title>
+<para>
+The basic settings for the FFT can be configured here.
+</para>
+
+<variablelist>
 <varlistentry>
 <term>
+<guilabel>Apodize, Function, and Sigma</guilabel>
+</term>
+<listitem>
+<para>
+If this option is selected, the data is apodized using a the window function selected from the drop-down menu at right. Apodization can be used to reduce bin-to-bin leakage. If a Gaussian apodization function is chosen, then a sigma value may also be entered to define its effective width.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<guilabel>Remove Mean</guilabel>
+</term>
+<listitem>
+<para>
+Select this option to remove the mean from the selected data (i.e. translate the data so that the mean is zero).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
 <guilabel>Interleaved average</guilabel> and <guilabel>FFT Length</guilabel>
 </term>
 <listitem>
 <para>
 Selecting <guilabel>Interleaved average</guilabel> allows the length of the interleaved Fast Fourier
-Transforms to be specified.  The length is specified as a power of 2.
-  If <guilabel>Interleaved average</guilabel> is unchecked, &kst;
-will determine the length based on the length of the vector.
+Transforms to be specified.  The length is specified as a power of 2. If <guilabel>Interleaved average</guilabel> is unchecked, &kst; will choose the smallest possible FFT length which is greater than the data vector length.
 </para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>
-<guilabel>Data units</guilabel> and <guilabel>Rate units</guilabel>
+<guilabel>Interpolate Over Holes</guilabel>
 </term>
 <listitem>
 <para>
-The units specified in these textboxes are used for the purpose of auto-generating axes labels for the plots.
+If the data vector contains NaN values, then selecting this option will cause &kst; to interpolate through them when calculating the power spectrum.
 </para>
 </listitem>
 </varlistentry>
@@ -1077,6 +1104,7 @@
 </term>
 <listitem>
 <para>
+This is the number of data vector samples per unit time.
 The sample rate is used to generate the X axis of power spectrum plots.
 </para>
 </listitem>
@@ -1084,22 +1112,23 @@
 
 <varlistentry>
 <term>
-<guilabel>Apodize</guilabel>
+<guilabel>Vector units</guilabel> and <guilabel>Rate units</guilabel>
 </term>
 <listitem>
 <para>
-If this option is selected, the data is apodized using a Hanning window, to reduce bin-to-bin leakage.
+The units specified in these textboxes are used for the purpose of auto-generating axes labels for the plots.
 </para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
 <term>
-<guilabel>Remove Mean</guilabel>
+<guilabel>Output</guilabel>
 </term>
 <listitem>
 <para>
-Select this option to remove the mean from the selected data (i.e. translate the data so that the mean is zero).
+The option selected from this drop-down menu determines which variant of the fundamental power spectrum should be computed. The amplitude spectrum is calculated by taking the square root of the power spectrum. Spectral densitites are calculated by multiplying the Power or Amplitude Spectra by the number of data samples divided by the sample rate entered above.
+<!--- FIXME: improve this once a clear definition of the power spectrum itself has been entered at the start of this section. -->
 </para>
 </listitem>
 </varlistentry>
@@ -1247,7 +1276,7 @@
 <variablelist>
 <varlistentry>
 <term>
-<guilabel>Matrix</guilabel>
+<guilabel>Matrix Selection</guilabel>
 </term>
 <listitem>
 <para>
@@ -1304,26 +1333,58 @@
 
 <varlistentry>
 <term>
-<guilabel>Lower Z threshold</guilabel>, <guilabel>Upper Z threshold</guilabel> and <guibutton>Auto Threshold</guibutton>
+<guilabel>Threshold-</guilabel> <guilabel>Lower</guilabel> and <guilabel>Upper</guilabel>
 </term>
 <listitem>
 <para>
 Enter the lower and upper thresholds to use for the mapping of colors.  Palette colors are evenly distributed
-between <guilabel>Lower Z threshold</guilabel> and <guilabel>Upper Z threshold</guilabel>.  Any cells in the
-selected matrix with z values less than <guilabel>Lower Z threshold</guilabel> are mapped to the first color in the palette.
-Any cells in the selected matrix with z values greater than <guilabel>Upper Z threshold</guilabel> are mapped
-to the last color in the palette.  Clicking <guibutton>Auto Threshold</guibutton> will fill in the
-lower and upper threshold values using the least and greatest z values found in the selected matrix.
+between the lower and upper thresholds.  Any cells in the
+selected matrix with z values less than the lower threshold are mapped to the first color in the palette.
+Any cells in the selected matrix with z values greater than the upper threshold are mapped
+to the last color in the palette.
 </para>
 </listitem>
 </varlistentry>
+
+<varlistentry>
+<term>
+<guilabel>Max/Min</guilabel>
+</term>
+<listitem>
+<para>
+Clicking this button causes the lower and upper threshold values to be set to the current minimum and maximum z values of the selected matrix.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<guilabel>Smart</guilabel> and <guilabel>Percentile</guilabel>
+</term>
+<listitem>
+<para>
+Clicking the <guilabel>Smart</guilabel> button causes the lower and upper threshold values to be set such that the percentage of z values in the selected matrix contained between them is equal to the value in the percentile numberbox.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<guilabel>Real-time auto threshold</guilabel>
+</term>
+<listitem>
+<para>
+Selecting this option causes the lower and upper threshold values to be always set to the minimum and maximum of the z values for the selected matrix, even when the matrix updates.
+</para>
+</listitem>
+</varlistentry>
 </variablelist>
 </sect3>
 
 <sect3 id="imagecontourmapparameters">
 <title>Contour Map Parameters</title>
 <para>
-A contour map draws a set of lines, with each line representing a certain z value. This section is only available
+A contour map draws a set of lines, with each line representing a particular z value. This section is only available
 if <guilabel>Contour Map</guilabel> or <guilabel>Color Map and Contour Map</guilabel> is selected under
 <guilabel>Image Type</guilabel>.
 </para>
@@ -1365,7 +1426,6 @@
 </para>
 </listitem>
 </varlistentry>
-
 </variablelist>
 </sect3>
 
@@ -1392,19 +1452,19 @@
 </varlistentry>
 
 <varlistentry>
-<term><guimenuitem>Data Wizard...</guimenuitem></term>
+<term><guimenuitem>Data Manager</guimenuitem></term>
 <listitem>
 <para>
-Displays the <link linkend="datawizard">Data Wizard</link>.
+Displays the <link linkend="datamanager">Data Manager</link>.
 </para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
-<term><guimenuitem>Data Manager</guimenuitem></term>
+<term><guimenuitem>View Manager</guimenuitem></term>
 <listitem>
 <para>
-Displays the <link linkend="datamanager">Data Manager</link>.
+Displays the <link linkend="viewmanager">View Manager</link>.
 </para>
 </listitem>
 </varlistentry>
@@ -1421,7 +1481,7 @@
 </varlistentry>
 
 <varlistentry>
-<term><guimenuitem>View Scalars</guimenuitem></term>
+<term><guimenuitem>View Scalar Values</guimenuitem></term>
 <listitem>
 <para>
 Displays a dialog from which the values of all the scalars in the current &kst; session
@@ -1431,7 +1491,7 @@
 </varlistentry>
 
 <varlistentry>
-<term><guimenuitem>View Vectors</guimenuitem></term>
+<term><guimenuitem>View Vector Values</guimenuitem></term>
 <listitem>
 <para>
 Displays a dialog from which the values in all the current vectors can be viewed. Select
@@ -1442,22 +1502,23 @@
 </varlistentry>
 
 <varlistentry>
-<term><guimenuitem>View Fit Results</guimenuitem></term>
+<term><guimenuitem>View Matrix Values</guimenuitem></term>
 <listitem>
 <para>
-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
+Displays a dialog from which the values in all the current matrices can be viewed. Select
+a matrix to view using the drop-down list. The dialog
 is updated dynamically if the values change.
 </para>
 </listitem>
 </varlistentry>
 
 <varlistentry>
-<term><guimenuitem>Change Data File</guimenuitem></term>
+<term><guimenuitem>View Fit Results</guimenuitem></term>
 <listitem>
 <para>
-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 <guibutton>Apply</guibutton> to save the changes.
+Displays a dialog which shows all the resulting values from fit plugins. Select
+a fit result to view using the drop-down list. The dialog
+is updated dynamically if the values change.
 </para>
 </listitem>
 </varlistentry>
--- branches/work/kst/newdocs/doc/kst/plotsandwindows-chapter.docbook #606849:606850
@@ -1668,11 +1668,15 @@
 To move a plot from one window to another, you can use the <guimenuitem>Move To</guimenuitem> function of the
 <link linkend="manipulatingplotlayoutcontextmenu">layout mode context menu</link>.  
 </para>
-
-
 </sect2>
 </sect1>
 
+<sect1 id="viewmanager">
+<title>The View Manager</title>
+<para>
+<!-- FIXME: add documentation -->
+</para>
+</sect1>
 
 </chapter>

More information about the Kst mailing list