From c2f9868c0dbffbf9857ef4bd7204de43c87efefa Mon Sep 17 00:00:00 2001 From: Barth Netterfield Date: Fri, 18 Aug 2017 14:42:33 -0400 Subject: [PATCH] Docbook updates. --- docbook/kst/data-chapter.docbook | 176 +++++++++++++++++++++++-------- 1 file changed, 131 insertions(+), 45 deletions(-) diff --git a/docbook/kst/data-chapter.docbook b/docbook/kst/data-chapter.docbook index 79621f88f..36178e274 100644 --- a/docbook/kst/data-chapter.docbook +++ b/docbook/kst/data-chapter.docbook @@ -362,11 +362,39 @@ Curves are created by the data wizard, from the creation dialog from Data Object Equations - An equation data object, created by selecting Equation from the - Create menu, produces an output vector which is the function of one or - more data vectors. An example of creating an equation, and the resulting plot is shown below. - In this example, a Generated Vector consisting of 1000 points from -10 to 10 was selected for - the x vector. Recall that a Generated vector can be created by selecting the new vector icon, + Equations are data objects whose outputs are: + + + + + A vector (...:y) which is the function of one or more data vectors. + + + + + A vector (...:x) which passes through the X input vector. + + + + + + The inputs are: + + + + + A vector which is used as the x variable in equations. + + + + + Any vectors or scalars specified by name in the equation text. + + + + + + Equations are used to produce vectors which are the point-by-point function of one or more input vectors and scalars. They are created by selecting Equation from the Create menu. An example of creating an equation, and the resulting plot is shown below. In this example, a Generated Vector consisting of 1000 points from -10 to 10 was selected for the x vector. Recall that a Generated vector can be created by selecting the new vector icon, @@ -374,8 +402,7 @@ Curves are created by the data wizard, from the creation dialog from Data Object - which appears to the right of the X Vector field. The equation, sin(x)/x, - was entered into the Equation field. + which appears to the right of the X Vector field. The equation, sin(x)/x, was entered into the Equation field. @@ -403,11 +430,52 @@ Curves are created by the data wizard, from the creation dialog from Data Object - Equations can use any vector or scalar as their input vectors, not just the X vector. In the next example, - the bottom right plot shows the signal in Column 2 with the signal in Column 1 regressed out of it. - This has been done by subtracting Column 1, scaled by the slope of a fit to Column 2 vs Column 1, - from Column 2. The fit had been created previously using the Fit option in the right - mouse button menu of the top right plot. + Equations support the following operators: + + + + + + Arithmetic operators: +, -, *, /, % (modulus operator) and ^ (power operator). + + + + + Bitwise operators: &, |. These operators assume the vector is comprised of integers. + + + + + Logical operators: !, &&, ||, <, <=, ==, >=, >, and !=. These functions output 1 for True and 0 for False. + + + + + + Functions supported by kst are: + + +PLUGIN() + + + + Trig functions working in Radians: SIN(), COS(), TAN(), ASIN(), ACOS(), ATAN(), ATAN2(), SEC(), CSC() and COT(). + + + + + Trig functions working in Degrees: SIND(), COSD(), TAND(), ASIND(), ACOSD(), ATAND(), SECD(), CSCD() and COTD(). + + + + + Other functions: ABS(), SQRT(), CBRT(), SINH(), COSH(), TANH(), EXP(), LN(), LOG() and STEP(). STEP() returns 1 if the argument is greater than 0, and 0 otherwise. + + + + + + Equations can use any vector or scalar as their input vectors, not just the X vector. In the next example, the bottom right plot shows the signal in Column 2 with the signal in Column 1 regressed out of it. This has been done by subtracting Column 1, scaled by the slope of a fit to Column 2 vs Column 1, from Column 2. The fit had been created previously using the Fit option in the right mouse button menu of the top right plot. @@ -491,30 +559,46 @@ set to be automatically reset with each data update by selecting Power Spectra -A power spectrum data object represents the power spectrum of a vector, defined as -the square root of the absolute value of the -mean of the interleaved Fast Fourier Transforms of length 2^x of the vector, where x is the -value entered in the FFT Length selection box. The below definitions assume -basic knowledge of power spectra—for further details, -refer to Numerical Recipes in C: The Art of Scientific Computing, published by Cambridge University Press. + Spectra are data objects whose outputs are a vector with the fft-based spectrum of the input + vector (...:psd), and a vector containing the centers of the corresponding + frequency bins (...:f). + + + + The following plot shows an example spectrum. The plot has been converted to log-log mode (hit 'l' and 'g' in the plot window to toggle Y and X log axes respectvely). -Power Spectra Window +Spectrum - + -Power Spectra Window +Spectrum - -Curve Contents + -The source vector, as well as basic power spectrum properties, can be modified from this section. + The spectrum dialog (select Power Spectrum from the Create menu) used to create this plot is shown below: + + + +New Spectrum Dialog + + + + + +The New Spectrum Dialog + + + + + + The dialog entries are as follows: @@ -531,72 +615,74 @@ The data vector to create a power spectrum from. -Interleaved average and FFT Length +Remove Mean -Selecting Interleaved average allows the length of the interleaved Fast Fourier -Transforms to be specified. The length is specified as a power of 2. - If Interleaved average is unchecked, &kst; -will determine the length based on the length of the vector. +Remove a constant from the input vector to make it mean zero before calculating the spectrum. -Data units and Rate units +Apodize -The units specified in these textboxes are used for the purpose of auto-generating axes labels for the plots. +Apodize the data with the selected function before calculating the power spectrum to reduce +bin to bin leackage. The default is a Hanning Window. -Sample rate +Interleaved average and FFT Length -The sample rate is used to generate the X axis of power spectrum plots. + When Interleaved average is not set, the spectrum is based on an FFT + whose lengh is power of two larger or equal to the length of the unput vector. The remaining points are zero padded. For cases like this, apodization and mean removal is quite important. + + + When Interleaved average is set, the spectrum is based on the average of FFTs of length 2^x where x is specified by the FFT Length entry, interleaved such that no zero padding is required. Choosing this option reduces the noise of the spectrum, at the cost of reduced resolution. -Apodize +Sample rate -If this option is selected, the data is apodized using a Hanning window, to reduce bin-to-bin leakage. - +The frequency bin output vector (...:f) will be calculated assuming the input vector was uniformly sampled at this sample rate. -Remove Mean +Data units and Rate units -Select this option to remove the mean from the selected data (i.e. translate the data so that the mean is zero). +Auto-generating axes labels for plots will be based on these units. + - Plugins -A plugin data object represents a &kst; plugin. All plugins have a common format, and show up as type Plugin -in the Data Manager. For more information about plugins, please see Plugins and Filters +A plugin data object represents a &kst; plugin. All plugins have a common format, and show +up as type Plugin in the Data Manager. For more information about plugins, +please see Plugins and Filters @@ -612,10 +698,10 @@ An event monitor data object represents an instance of an event monitor. For mo Matrices -A matrix represents a set of three-dimensional data points (x, y, z) arranged in a two-dimensional grid. -The z values of the matrix are obtained from a vector, and the grid structure is manually specified using -the Edit or New Matrix dialog. The descriptions below refer to the following diagram depicting -&kst;'s matrix structure. +A matrix represents a set of three-dimensional data points (x, y, z) arranged in a +two-dimensional grid. The z values of the matrix are obtained from a vector, and the +grid structure is manually specified using the Edit or New Matrix dialog. The descriptions +below refer to the following diagram depicting &kst;'s matrix structure.