diff --git a/docbook/kst/data-chapter.docbook b/docbook/kst/data-chapter.docbook index 7b478002..d7b9d635 100644 --- a/docbook/kst/data-chapter.docbook +++ b/docbook/kst/data-chapter.docbook @@ -1,1050 +1,1050 @@ Working With Data Data Sources Data Source Concepts A data source in &kst; is simply a supported data file. Currently, Kst supports ASCII text files, dirfiles, and NetCDF, for vectors and scalars, and FITS images, BIT image streams, 16 bit TIFF images, and any image format supported by QImage, (jpg, png, bmp, etc) for images. The following concepts are important in understanding how &kst; works with different data sources. Some terminology is also introduced in this section. Fields Data in &kst; are accessed by field names. A field name can refer to a single scalar or string, to a vector of values from a single sensor, or to a matrix. For example, a column in an ASCII data file can be read in as a vector. An image in a png file can be read in as a matrix. Datasource readers provide functions for reading and obtaining fields and field names. Frames When reading in a vector from a data source field, data are addressed by their Frame number, not by their sample number. Each field in a data source has its own fixed number of samples per frame. For some data sources (eg, ASCII files) every frame contains exactly one sample (ie, for ASCII files, a frame is a valid row of data, and every row has exactly one sample for each field). However, for other data sources (eg, dirfiles), there may be multiple samples per frame. In the illustration below, the first 3 frames of an imaginary dirfile are shown. In this particular data file, Field1 has a 1 sample per frame, Field2 has 4 samples per frame, and Field3 has 2 samples per frame. Every field must have a constant number of samples per frame throughout the file. In the figure, imagine that time proceeds from top to bottom. &kst; assumes that the first sample in a frame is simultaneous for every field in the data source, and that the rest of the samples are sampled evenly throughout the frame, as shown. - When plotting one vector agains another, &kst; assumes that the first and last samples of each vector are simultaneous, and interpolates the shorter vector up to the resolution of the longer vector. Since only the first sample in a frame can be assumed to be simultaneous across fields, when &kst; reads data into a vector, it only reads up to the first sample of the last frame requested, so that plotting one vector against another will make sense. The rest of the last frame will not be read. + When plotting one vector against another, &kst; assumes that the first and last samples of each vector are simultaneous, and interpolates the shorter vector up to the resolution of the longer vector. Since only the first sample in a frame can be assumed to be simultaneous across fields, when &kst; reads data into a vector, it only reads up to the first sample of the last frame requested, so that plotting one vector against another will make sense. The rest of the last frame will not be read. So if the first three frames of Field1 and Field2 are read from the data source in the figure, 3 samples will be read from Field1, and 9 samples will be read from Field2 (ending at first sample of Frame 3) - not 12 as one might expect. INDEX Field As well as the explicit data fields in a data file, &kst; implicitly creates an INDEX field for all data sources. The INDEX field is 1 sample per frame, and simply contains integers from 0 to N-1, where N is the number of frames in the data file. It is common to plot vectors against INDEX. This is convenient since the INDEX of a sample or event is just the frame number, allowing easy identification and retrieval of events from a data file. ASCII Input Files &kst; is capable of reading vectors from a wide range of ASCII formats. As long as the data are in columns, and as long as each non-comment row has the same number of collumns, &kst; can probably read it. Consider reading this simple ASCII csv file: each comma separated column represents a field. Length,Width m,m 1.1,6.2 2.4,9.3 4.3,4.7 5.2,8.8 When you enter an ascii source into a data source selection widget (such as on the first page of the data wizard) the file will be identified as an ASCII file, and the Configure button will be enabled, as shown below. Clicking on Configure will bring up the ASCII data source configuration dialog. Note that the first few lines of the file are shown. The dialog in the screen shot has been filled out to read this file: looking at the first lines of the file, we see that data starts at line 3, line 1 holds the field names, and line 2 holds the units (which will be used by &kst; in plot labels). Additionally, as this is a csv file, a "," has been selected as the Custom delimiter. Selecting OK will assign this configuration to this file. &kst; will continue to use this configuration with this file until the configuration options are changed again in this dialog, or until Clear datasource settings in the Settings menu is selected. The Data Manager The Data Manager provides a central location for deleting and modifying all the data objects used in &kst;. It can be accessed by selecting Data Manager from the Tools menu or by clicking the icon in the tool bar. The window lists all data objects currently loaded in kst, as well as their type and basic properties. To edit an object, double click on it, or select it and click the Edit button. It will bring up the appropriate edit dialog. Items that have child-vectors can be expanded to list them. Items also have right button context menus with common tasks for the items, such as making curves or power spectra from vectors, or adding curves to plots. - Items can also be deleted from this dialog by selecting them and clicking Delete. This will delete the selected item and all items which depend on it. So if you delete a vector, all curves, spectra, historgrams, or equations that depend on it will also be deleted. Be careful, because this can not be undone. + Items can also be deleted from this dialog by selecting them and clicking Delete. This will delete the selected item and all items which depend on it. So if you delete a vector, all curves, spectra, histograms, or equations that depend on it will also be deleted. Be careful, because this can not be undone. Clicking Purge will remove all undisplayed data objects. If deleting an object (and everthing that depends on it) will not change any plots or labels, then it is deleted. Nothing that is displayed is deleted. This can not be undone. Data Types Plots in &kst; are created by building up objects into the displayed curves. In &kst;, there are 5 major classes: Data Sources: data files which are recognized by &kst;. Primitives: These are basic data types, including Strings, Scalars (which are single numbers), Vectors (which are ordered lists of numbers) and Matrices (which are 2D arrays of numbers). Relations: these objects describe how vectors or matrices are displayed in a plot. They include Curves (which display an XY pair of vectors) and Images (which display matrices). Data Objects: these classes take Primitives as inputs, process them, and output Primitives. These include Spectra, Histograms, Equations, Fits, Filters, and other Plugins. View Items: these are objects that can be drawn, and include plots, labels, lines, etc. Plots can display Relations (curves and images). Labels can display Scalars and Strings. As an example of how these various classes work together, consider the example session in the chapter on Filters. In this session, a curve from a data file was plotted, along with a low pass filtered version of the curve. The resulting data structures are as follows: &kst; Data Types - The plot displays two curves. One curve takes two data vectors (INDEX and Column 2) as inputs. The other takes INDEX as its X vector, and the ouput vector of the Low Pass Filter as its Y vector. The low pass filter takes the Column 2 vector, and two Scalars as its inputs. The two data vectors get their data from the Data Source. + The plot displays two curves. One curve takes two data vectors (INDEX and Column 2) as inputs. The other takes INDEX as its X vector, and the output vector of the Low Pass Filter as its Y vector. The low pass filter takes the Column 2 vector, and two Scalars as its inputs. The two data vectors get their data from the Data Source. The data manager for this sessions is shown below. Note that the literal scalars [4 (X30)] and [0.05 (X29)] are not listed. To keep things clean, and because '4' is not editable, literal scalars like this are not presented in the UI. This structure could have been chained together further. For example, the output of the Filter could have been used as the input to a Histogram, and the Histogram of the output of the filtered data could have been plotted instead. Descriptions of each data type are provided below. Vectors Vectors are ordered lists of numbers. They are used as the inputs to Data Objects. They are also used to define the X or Y axis for curves. While different types of vectors are created in different ways, they can all be used in Data Objects or curves in the same way. Data Vectors aquire their data from Data Sources (ie, data files). They can be created from the Vector option in the Create menu, or by selecting the icon in any vector selector. Generated Vectors are lists of equally spaced numbers whose range and spacing is defined in the GUI. They can be created from the Vector option in the Create menu, or by selecting the icon in any vector selector. Editable Vectors have their data defined through the Python interface. They can not be created or edited in the GUI. Output Vectors are the output of data objects, such as histograms or filters. Curves Curves are used to create plottable objects from vectors. Curves are created from two vectors - an X axis vector and a Y axis vector. These two vectors are interpreted as a set of (X,Y) pairs to be plotted. When the X and Y vectors have the same length, the interpretation is obvious. If, however, the X vector is of a different length than the Y vector, then the first and last points of each are assumed to represent the first and last (X,Y) pair, and the shorter vector is resampled using linear interpolation to have the same number of samples as the longer vector. Curves are created by the data wizard, from the creation dialog from Data Objects (such as histograms) or by using the Curve option in the Create menu. The latter produces the following: New Curve New Curve Here, in the Curve Contents box, the curve has been set up to use INDEX (V1) as the X axis vector and Column 2 (V3) as the Y axis vector. Note that vectors holding X and Y axis error bars can also be selected. The icon in any of the vector selectors will bring up a new vector dialog. The icon will edit the selected vector. - The appearance of curves is adjusted in the Appearance box. Some of the flexability of curves in kst is shown in the next figure. + The appearance of curves is adjusted in the Appearance box. Some of the flexibility of curves in kst is shown in the next figure. Note that the options are not exclusive - for example, Lines and Points can both be selected. The Size field specifies the dimensions of display elements such as points and error flags in points (the same way as font sizes are defined.) The Weight field specifies the width of lines, bar graph borders, and the strokes for points. The color selector to the right of the example line sets the color of lines, points, and bargraph borders. The color selector to the right of the Bargraph checkbox sets the fill color for bargraphs. The last (most recent) point of a - curve can be indicated by slecting Head and specifying + curve can be indicated by selecting Head and specifying a point type and color. The color selector to the right of the Head sets the color for this point. Curve Demo Curve Demo The Placement box specifies what plot the curve will be displayed in. Both the Placement and Appearance boxes appear in data object creation dialogs as well, and work the same way. Equations 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, which appears to the right of the X Vector field. The equation, sin(x)/x, was entered into the Equation field. New Equation New Equation sin(x)/x sin(x)/x 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: 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() (absolute value), SQRT() (square root), CBRT() (cube root), SINH(), COSH(), TANH(), EXP(), LN() (natural logarithm), LOG() (base 10 logarithm) and STEP() (returns 1 if the argument is greater than 0, and 0 otherwise). Equations also support the constants PI and e. 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. Regression Regression - The New Equation dialog which created this plot is shown below. Note that vectors are identified by enclosing their names in [ ]. So Column 2 is indicated by [Column 2 (V2)]. The Equation line widget has a fairly powerful autocomplete mechanism with a scrollable list of all possible scalars (in its first colum) or vectors (in its second column) as you enter the name of the object. Similarly, the auto complete lists all valid functions and operators as relevant while you type. The Esc key hides the autocomplete widget. + The New Equation dialog which created this plot is shown below. Note that vectors are identified by enclosing their names in [ ]. So Column 2 is indicated by [Column 2 (V2)]. The Equation line widget has a fairly powerful autocomplete mechanism with a scrollable list of all possible scalars (in its first column) or vectors (in its second column) as you enter the name of the object. Similarly, the auto complete lists all valid functions and operators as relevant while you type. The Esc key hides the autocomplete widget. If the vectors were set to Read to end mode, all elements would be updated real time as new data came in. Complex Equation Complex Equation Histograms Histograms are data objects whose outputs are: A vector (...:num) which contains the (optionally normalized) count of samples from the input vector which lie within each interval. A vector (...:bin) which contains the center of each interval for which the counts have been calculated. The input is: A vector for which the histogram is calculated. In the New Histogram dialog, the bins can be set manually, can be preset once by selecting Auto Bin or can be set to be automatically reset with each data update by selecting Real-time auto bin. By selecting Bargraph in the dialog, the histogram can be shown in the standard bar-graph form, below. New Histogram New Histogram Histogram Histogram Power Spectra Power Spectra are data objects whose outputs are: A vector (...:psd) which contains the fft-based spectrum of the input vector. A vector (...:f) which contains the centers of the corresponding frequency bins. The input is: A vector for which the power spectrum is calculated. Uniform sampling is assumed. - 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). + 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 respectively). Spectrum Spectrum 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: Data vector The data vector to create a power spectrum from. Remove Mean Remove a constant from the input vector to make it mean zero before calculating the spectrum. Apodize Apodize the data with the selected function before calculating the power spectrum to reduce -bin to bin leackage. The default is a Hanning Window. +bin to bin leakage. The default is a Hanning Window. Interleaved average and FFT Length 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. Sample rate The frequency bin output vector (...:f) will be calculated assuming the input vector was uniformly sampled at this sample rate. Data units and Rate units Auto-generating axes labels for plots will be based on these units. Fits Fits are data objects whose outputs are: A vector (...:Fit) which is the fit to the data, evaluated at the X value corresponding to each input Y point. A vector (...:Residuals) which is the difference between the input Y vector and the fit. One or more named scalars which correspond to the fit parameters. For example, for linear fits, the scalars are ...:Intercept and ...:Gradient. A scalar (...:chi^2/nu which holds the reduced chi squared of the fit. A vector (...:Covariance) which holds the Covariance matrix of the fit in an arbitrary order. Because the parameters are listed in an arbitrary order, this vector is not currently particularly useful. A vector (...:Parameters) which is a list of the fit parameters in some arbitrary order. This vector is rarely useful and may be removed in the future. The named parameter scalars are a much more useful interface to the fit parameters. The inputs are: A vector which is to be fit to. (The Y axis vector) A vector which is used to generate the X values corresponding to the Y vector. Note that if the X vector is not the same length as the Y vector, then the X vector will be resampled to have the same number of points as the Y vector in order to generate a series of (X, Y) pairs. If a weighted fit is chosen: A vector which describes the error bars for the Y vector. A number of fits are available in kst, including weighted (in which the error bar for each Y value is specified) and unweighted fits to lines, polynomials, Gaussians, Lorentians, and exponentials. The easiest way to create a fit is by selecting Create fit from the plot context menu (right click in the plot, and then selecting the curve you would like to fit. The following dialog will appear. New Spectrum Dialog The Create Fit Dialog A linear fit has been selected in the Plugin Selection combo box. The X and Y vectors have been automatically selected from the curve which was selected and can not be changed. The curve properties and placement of the automatically generated curve can be selected as usual. When Ok has been selected, the curve is placed in the selected plot, and a label with the fit parameters is automatically created. Click the mouse whereever you want the label to go. You can also create a fit plugin by selecting the appropriate fit from the Fit plugin submenu in the Create menu. With this dialog you can select the input vectors, but it does not automatically create a curve. You will have to create a curve by hand by selecting Curve in the Create menu. Filters Filters are data objects whose output is: A vector (...:Filtered) which is the same size as the input vector. The inputs are: A vector which is to be filtered. A number of numbers or scalars which are parameters for the filter. A number of filters are available in kst. The band pass, band stop, high pass and low pass filters are conventional zero phase shift fourier domain filters whose band edges follow the shape of a Butterworth filter. A higher order filter is a steeper cutoff. Numerical Integrals can be created with the Cumulative Sum filter, and Numerical Derivatives with the Fixed Step Differentiation filter. In both of these dX takes the size of the step between samples. - For fields such as angles which have (for example) a discontinuity at 360 degrees, the Unwind Fliter can be used to make the signal continuous. So if the unfiltered signal goes from 359.5 degrees to 0.5 degrees in consecutive samples, the filtered signal will go from 359.5 degrees to 360.5 degrees. + For fields such as angles which have (for example) a discontinuity at 360 degrees, the Unwind Filter can be used to make the signal continuous. So if the unfiltered signal goes from 359.5 degrees to 0.5 degrees in consecutive samples, the filtered signal will go from 359.5 degrees to 360.5 degrees. The Flag filter can be used to mask a vector with NaNs whenever certain bit patters in the flag field are true. The easiest way to create a filter is by selecting Create filter from the plot context menu (right click in the plot, and then selecting the curve you would like to fit. You can also create a filter plugin by selecting the appropriate filter from the Filter plugin submenu in the Create menu. With this dialog you can select the input vectors, but it does not automatically create a curve. You will have to create a curve by hand by selecting Curve in the Create menu. Standard Plugins Plugins that do not fit the requirements of being either fits are filters can be created from the Standard Plugin submenu in the Create menu. They are not well documented. Matrices Matrices are two dimensional tables of numbers. They can be used as the inputs to Data Objects. They are also used to define the values for Images. While different types of Matrices are created in different ways, they can all be used in Data Objects or Images in the same way. Data Matrices aquire their data from Data Sources (ie, data files). They can be created from the Matrix option in the Create menu, or by selecting the icon in any matrix selector (for example, in the Image dialog). Editable Matrices have their data defined through the Python interface. They can not be created or edited in the GUI. Output Matrices are the output of data objects, such as Spectrograms. New Matrix Dialog The New Matrix Dialog Matrices can be read from: Any data file compatible with QImage - (jpg, png, tiff, bmp, gif, etc). For color images, four matrices can be read: RED, GREEN, BLUE, and GRAY. conventional 2D FITS images (if built with cfitsio). - BIT Image Streams (BIS) fiiles. + BIT Image Streams (BIS) files. The BIS data source can provide matrices from an image stream. In these cases, the frame number can be selected when the Matrix is created. Images Images are used to create plottable objects from Matrices. The pixels are directly mapped from the matrix. ie, rows in the matrix are rows in the image. Columns in the matrix are columns in the image. The value of the Matrix sets the color of the pixel. Images are typically created from selecting Image from the Create menu. The Image dialog is shown below: New Image Dialog The New Image Dialog A matrix has been read from a png file, and selected in the Matrix selector (GRAY (M1)). A color map rather than a contour map has been selected, and a grey scale color pallet has been selected. With Real-time auto threshold selected, the maximum value in the matrix will be set to the maximum value of the color pallet, and the minimum value in the matrix will be set to the minimum value of the color pallet. All other values will be linearly interpolated. Alternatively, the maximum and minimum values can be set once, either using Smart/Percentile tool, or by manually setting the thresholds. The resulting image is shown below. Note that, by default, the image will automatically fill the plot window, and will not preserve aspect ratio. New Image Dialog The New Image Dialog The aspect ratio can be normalized by selecting Normalize X-Axis to Y-Axis in the X Zoom submenu of the Zoom plot context menu, or by pressing the "n" key in a plot window. The image will now have square pixels. New Image Dialog The New Image Dialog The range of the color pallet can be adjusted from the curve edit dialog, or by pressing 'i' in an image. This will cycle the color limits, allowing an increasing fraction of the pixels to be saturated at either end of the color scale before returning to full range. diff --git a/docbook/kst/debuglog-chapter.docbook b/docbook/kst/debuglog-chapter.docbook index 55145f1c..dddcf4eb 100644 --- a/docbook/kst/debuglog-chapter.docbook +++ b/docbook/kst/debuglog-chapter.docbook @@ -1,50 +1,50 @@ Troubleshooting -Unfortunately, things can sometimes go wrong with &kst;. This section lists somee things that can be useful to unbreak things. +Unfortunately, things can sometimes go wrong with &kst;. This section lists some things that can be useful to unbreak things. Clearing Defaults - For convenience reasons, &kst; makes agressive use of sticky defaults - that is to say, &kst; will generally remember what you did last time, and make that the new default behaviour. Unfortunately, this can sometimes leave the program in an odd state where the assumptions it is making make no sense. This most often happens with files and file defaults. + For convenience reasons, &kst; makes aggressive use of sticky defaults - that is to say, &kst; will generally remember what you did last time, and make that the new default behaviour. Unfortunately, this can sometimes leave the program in an odd state where the assumptions it is making make no sense. This most often happens with files and file defaults. - If you find that &kst; has broken for you (that is, something that used to work no longer does), bad defaults is a pretty plausable explaination (though we do keep trying to track these situations down and remove them). You can completely restore &kst; to it's default, just-installed configuration by selecting Clear datasource settings and Clear settings and defaults from the Settings menu. Unfortunately, this will erase all of your settings and defaults, but it may be necessary in some cases. If the problem seems to have something to do with data files, try Clear datasource settings first because it is generally less destructive and more likely to help. + If you find that &kst; has broken for you (that is, something that used to work no longer does), bad defaults is a pretty plausible explanation (though we do keep trying to track these situations down and remove them). You can completely restore &kst; to it's default, just-installed configuration by selecting Clear datasource settings and Clear settings and defaults from the Settings menu. Unfortunately, this will erase all of your settings and defaults, but it may be necessary in some cases. If the problem seems to have something to do with data files, try Clear datasource settings first because it is generally less destructive and more likely to help. The Debug Dialog The Debug Dialog, selected from the Help is useful to check your installation, and find out if &kst; thinks something has gone wrong. The Data Sources tab lists all of the data sources that &kst; has successfully loaded. If you are using a data file that depends on a data source plugin that is not listed, then there is probably something wrong with your build or installation. The Log tab provides a log the loading of all data sources and data plugins, as well as logging some errors, such as out of memory errors. This log tab can be a useful place to look if things are not working out well. diff --git a/docbook/kst/plugins-chapter.docbook b/docbook/kst/plugins-chapter.docbook index 59802daf..4a680404 100644 --- a/docbook/kst/plugins-chapter.docbook +++ b/docbook/kst/plugins-chapter.docbook @@ -1,2343 +1,2343 @@ Plugins, Fits, and Filters -Many of the mathematical data operators in &kst;, including fits and filters, are implemented as plugins. Plugins are loaded at run time and use a stable API, so it is possible to write your own plugins and include them in your local installation without re-compiling &kst;. Fits and Filters are simply subsets of the set of plugins, and thus behave identically to generic plugins, with the exception of additional convenience dialog functionality when selected from the plot contect menu. See here for a general description of the creation of fits and filters. +Many of the mathematical data operators in &kst;, including fits and filters, are implemented as plugins. Plugins are loaded at run time and use a stable API, so it is possible to write your own plugins and include them in your local installation without re-compiling &kst;. Fits and Filters are simply subsets of the set of plugins, and thus behave identically to generic plugins, with the exception of additional convenience dialog functionality when selected from the plot context menu. See here for a general description of the creation of fits and filters. To date, there are more than 25 built-in plugins available in &kst; that perform functions from taking cross correlations of two vectors to producing periodograms of a data set. The following screenshot shows the settings window for a typical plugin, created by selecting the desired plugin from the Standard Plugin, Fit Plugin or Filter Plugin submenues in the Create toolbar menu. Plugins Window Plugins Windowpluginswindow The following sections describe the purpose, key algorithms or formulas used to perform calculations, and inputs and outputs for each plugin. Note that fitting and filtering plugins are included in the following sections. Autocorrelation The autocorrelation plugin calculates correlation values between a series (vector) and a lagged version of itself, using lag values from floor(-(N-1)/2) to floor((N-1)/2), where N is the number of points in the data set. The time vector is not an input as it is assumed that the data is sampled at equal time intervals. The correlation value r at lag k is: Autocorrelation formula Inputs X Array (vector) The array x of values to calculate correlation values for. Outputs Step Number (vector) The array of step, or lag values. Correlation Value (vector) The array of correlation values calculated using the corresponding step number in the Step Number vector. Bin The bin plugin bins elements of a single data vector into bins of a specified size. The value of each bin is the mean of the elements belonging to the bin. For example, if the bin size is 3, and the input vector is [9,2,7,3,4,74,5,322,444,2,1], then the outputted bins would be [6,27,257]. Note that any elements remaining at the end of the input vector that do not form a complete bin (in this case, elements 2 and 1), are simply discarded. Inputs Input Vector (vector) The vector to bin. Bin Size (scalar) The size to use for each bin. Outputs Bins (vector) The array of means for each bin. Butterworth band-pass The Butterworth band-pass plugin filters a set of data by calculating the Fourier transform of the data and recalculating the the frequency responses using the following formula Autocorrelation formula where f is the frequency, fc is the low frequency cutoff, b is the bandwidth of the band to pass, and n is the order of the Butterworth filter. The inverse Fourier transform is then calculated using the new filtered frequency responses. Inputs X Array (vector) The array of values to filter. Order (scalar) The order of the Butterworth filter to use. Low cutoff frequency (scalar) The low cutoff frequency of the Butterworth band pass filter. Band width (scalar) The width of the band to pass. This should be the difference between the desired high cutoff frequency and the low cutoff frequency. Outputs X Filtered (vector) The array of filtered data values. Butterworth band-stop The Butterworth band-stop plugin filters a set of data by calculating the Fourier transform of the data and recalculating the the frequency responses using the following formula Autocorrelation formula where f is the frequency, fc is the low frequency cutoff, b is the bandwidth of the band to stop, and n is the order of the Butterworth filter. The inverse Fourier transform is then calculated using the new filtered frequency responses. Inputs X Array (vector) The array of values to filter. Order (scalar) The order of the Butterworth filter to use. Low cutoff frequency (scalar) The low cutoff frequency of the Butterworth band stop filter. Band width (scalar) The width of the band to stop. This should be the difference between the desired high cutoff frequency and the low cutoff frequency. Outputs X Filtered (vector) The array of filtered data values. Butterworth high-pass The Butterworth high-pass plugin filters a set of data by calculating the Fourier transform of the data and recalculating the the frequency responses using the following formula Autocorrelation formula where f is the frequency, fc is the high frequency cutoff, and n is the order of the Butterworth filter. The inverse Fourier transform is then calculated using the new filtered frequency responses. Inputs X Array (vector) The array of values to filter. Order (scalar) The order of the Butterworth filter to use. Cutoff frequency (scalar) The cutoff frequency of the Butterworth high pass filter. Outputs X Filtered (vector) The array of filtered data values. Butterworth low-pass The Butterworth low-pass plugin filters a set of data by calculating the Fourier transform of the data and recalculating the the frequency responses using the following formula Autocorrelation formula where f is the frequency, fc is the low frequency cutoff, and n is the order of the Butterworth filter. The inverse Fourier transform is then calculated using the new filtered frequency responses. Inputs X Array (vector) The array of values to filter. Order (scalar) The order of the Butterworth filter to use. Cutoff frequency (scalar) The cutoff frequency of the Butterworth low pass filter. Outputs X Filtered (vector) The array of filtered data values. Chop The chop plugin takes an input vector and divides it into two vectors. Every second element in the input vector is placed in one output vector, while all other elements from the input vector are placed in another output vector. Inputs Array (vector) The array of values to perform the chop on. Outputs Odd Array (vector) The array containing the odd part of the input array (i.e. it contains the first element of the input array). Even Array (vector) The array containing the even part of the input array (i.e. it does not contain the first element of the input array). Difference Array (vector) The array containing the elements of the odd array minus the respective elements of the even array. Index Array (vector) An index array the same length as the other three output arrays. Convolution The convolution plugin generates the convolution of one vector with another. The convolution of two functions f and g is given by: The order of the vectors does not matter, since f*g=g*f. In addition, the vectors do not need to be of the same size, as the plugin will automatically extrapolate the smaller vector. Inputs Array One (vector) One of the pair of arrays to take the convolution of. Array Two (vector) One of the pair of arrays to take the convolution of. Outputs Convolved (vector) The convolution of the two input vectors. Crosscorrelation The crosscorrelation plugin calculates correlation values between two series (vectors) x and y, using lag values from floor(-(N-1)/2) to floor((N-1)/2), where N is the number of elements in the longer vector. The shorter vector is padded to the length of the longer vector using 0s. The time vector is not an input as it is assumed that the data is sampled at equal time intervals. The correlation value r at lag k is: crosscorrelation formula Inputs X Array (vector) The array x used in the cross-correlation formula. Y Array (vector) The array y used in the cross-correlation formula. Outputs Step Number (vector) The array of step, or lag values. Correlation Value (vector) The array of correlation values calculated using the corresponding step number in the Step Number vector. Deconvolution The deconvolution plugin generates the deconvolution of one vector with another. Deconvolution is the inverse of convolution. Given the convolved vector h and another vector g, the deconvolution f is given by: The vectors do not need to be of the same size, as the plugin will automatically extrapolate the shorter vector. The shorter vector is assumed to be the response function g. Inputs Array One (vector) One of the pair of arrays to take the deconvolution of. Array Two (vector) One of the pair of arrays to take the deconvolution of. Outputs Deconvolved (vector) The deconvolution of the two input vectors. Fit exponential weighted The Fit exponential weighted plugin performs a weighted non-linear least-squares fit to an exponential model: An initial estimate of a=1.0, =0, and b=0 is used. The plugin subsequently iterates to the solution until a precision of 1.0e-4 is reached or 500 iterations have been performed. Inputs X Array (vector) The array of x values for the data points to be fitted. Y Array (vector) The array of y values for the data points to be fitted. Weights (vector) The array of weights to use for the fit. Outputs Y Fitted (vector) The array of fitted y values. Residuals (vector) The array of residuals. Parameters (vector) The best fit parameters a, , and b. Covariance (vector) The covariance matrix of the model parameters, returned row after row in the vector. chi^2/nu (scalar) The weighted sum of squares of the residuals, divided by the degrees of freedom. Fit exponential The Fit exponential plugin is identical in function to the Fit exponential weighted plugin with the exception that the weight value wi is equal to 1 for all index values i. As a result, the Weights (vector) input does not exist. Fit gaussian weighted The Fit gaussian weighted plugin performs a weighted non-linear least-squares fit to a Gaussian model: An initial estimate of a=(maximum of the y values), =(mean of the x values), and =(the midpoint of the x values) is used. The plugin subsequently iterates to the solution until a precision of 1.0e-4 is reached or 500 iterations have been performed. Inputs X Array (vector) The array of x values for the data points to be fitted. Y Array (vector) The array of y values for the data points to be fitted. Weights (vector) The array of weights to use for the fit. Outputs Y Fitted (vector) The array of fitted y values. Residuals (vector) The array of residuals. Parameters (vector) The best fit parameters , , and a. Covariance (vector) The covariance matrix of the model parameters, returned row after row in the vector. chi^2/nu (scalar) The weighted sum of squares of the residuals, divided by the degrees of freedom. Fit gaussian The Fit gaussian plugin is identical in function to the Fit gaussian weighted plugin with the exception that the weight value wi is equal to 1 for all index values i. As a result, the Weights (vector) input does not exist. Fit gradient weighted The gradient weighted plugin performs a weighted least-squares fit to a straight line model without a constant term: The best-fit is found by minimizing the weighted sum of squared residuals: for b, where wi is the weight at index i. Inputs X Array (vector) The array of x values for the data points to be fitted. Y Array (vector) The array of y values for the data points to be fitted. Weights (vector) The array containing weights to be used for the fit. Outputs Y Fitted (vector) The array of y values for the points representing the best-fit line. Residuals (vector) The array of residuals, or differences between the y values of the best-fit line and the y values of the data points. Parameters (vector) The parameter b of the best-fit. Covariance (vector) The estimated covariance matrix, returned row after row, starting with row 0. Y Lo (vector) The corresponding value in Y Fitted minus the standard deviation of the best-fit function at the corresponding x value. Y Hi (vector) The corresponding value in Y Fitted plus the standard deviation of the best-fit function at the corresponding x value. chi^2/nu (scalar) The value of the sum of squares of the residuals, divided by the degrees of freedom. Fit gradient The Fit linear plugin is identical in function to the Fit gradient weighted plugin with the exception that the weight value wi is equal to 1 for all index values i. As a result, the Weights (vector) input does not exist. Fit linear weighted The Fit linear weighted plugin performs a weighted least-squares fit to a straight line model: The best-fit is found by minimizing the weighted sum of squared residuals: for a and b, where wi is the weight at index i. Inputs X Array (vector) The array of x values for the data points to be fitted. Y Array (vector) The array of y values for the data points to be fitted. Weights (vector) The array containing weights to be used for the fit. Outputs Y Fitted (vector) The array of y values for the points representing the best-fit line. Residuals (vector) The array of residuals, or differences between the y values of the best-fit line and the y values of the data points. Parameters (vector) The parameters a and b of the best-fit. Covariance (vector) The estimated covariance matrix, returned row after row, starting with row 0. Y Lo (vector) The corresponding value in Y Fitted minus the standard deviation of the best-fit function at the corresponding x value. Y Hi (vector) The corresponding value in Y Fitted plus the standard deviation of the best-fit function at the corresponding x value. chi^2/nu (scalar) The value of the sum of squares of the residuals, divided by the degrees of freedom. Fit linear The Fit linear plugin is identical in function to the Fit linear weighted plugin with the exception that the weight value wi is equal to 1 for all index values i. As a result, the Weights (vector) input does not exist. Fit lorentzian weighted The Fit lorentzian weighted plugin performs a weighted non-linear least-squares fit to a Lorentzian model: An initial estimate of a=(maximum of the y values), x0=(mean of the x values), and =(the midpoint of the x values) is used. The plugin subsequently iterates to the solution until a precision of 1.0e-4 is reached or 500 iterations have been performed. Inputs X Array (vector) The array of x values for the data points to be fitted. Y Array (vector) The array of y values for the data points to be fitted. Weights (vector) The array of weights to use for the fit. Outputs Y Fitted (vector) The array of fitted y values. Residuals (vector) The array of residuals. Parameters (vector) The best fit parameters x0, , and a. Covariance (vector) The covariance matrix of the model parameters, returned row after row in the vector. chi^2/nu (scalar) The weighted sum of squares of the residuals, divided by the degrees of freedom. Fit lorentzian The Fit lorentzian plugin is identical in function to the Fit lorentzian weighted plugin with the exception that the weight value wi is equal to 1 for all index values i. As a result, the Weights (vector) input does not exist. Fit polynomial weighted The Fit polynomial weighted plugin performs a weighted least-squares fit to a polynomial model: where n is the degree of the polynomial model. Inputs X Array (vector) The array of x values for the data points to be fitted. Y Array (vector) The array of y values for the data points to be fitted. Weights (vector) The array of weights to use for the fit. Order (scalar) The order, or degree, of the polynomial model to use. Outputs Y Fitted (vector) The array of fitted y values. Residuals (vector) The array of residuals. Parameters (vector) The best fit parameters c0, c1,..., cn. Covariance (vector) The covariance matrix of the model parameters, returned row after row in the vector. chi^2/nu (scalar) The weighted sum of squares of the residuals, divided by the degrees of freedom. Fit polynomial The Fit polynomial plugin is identical in function to the Fit polynomial weighted plugin with the exception that the weight value wi is equal to 1 for all index values i. As a result, the Weights (vector) input does not exist. Fit sinusoid weighted The Fit sinusoid weighted plugin performs a least-squares fit to a sinusoid model: where T is the specified period, and n=2+2H, where H is the specified number of harmonics. Inputs X Array (vector) The array of x values for the data points to be fitted. Y Array (vector) The array of y values for the data points to be fitted. Weights (vector) The array of weights to use for the fit. Harmonics (scalar) The number of harmonics of the sinusoid to fit. Period (scalar) The period of the sinusoid to fit. Outputs Y Fitted (vector) The array of fitted y values. Residuals (vector) The array of residuals. Parameters (vector) The best fit parameters c0, c1,..., cn. Covariance (vector) The covariance matrix of the model parameters, returned row after row in the vector. chi^2/nu (scalar) The weighted sum of squares of the residuals, divided by the degrees of freedom. Fit sinusoid The Fit sinusoid plugin is identical in function to the Fit sinusoid weighted plugin with the exception that the weight value wi is equal to 1 for all index values i. As a result, the Weights (vector) input does not exist. Interpolation Akima spline The Interpolation Akima spline plugin generates a non-rounded Akima spline interpolation for the supplied data set, using natural boundary conditions. Inputs X Array (vector) The array of x values of the data points to generate the interpolation for. Y Array (vector) The array of y values of the data points to generate the interpolation for. X' Array (vector) The array of x values for which interpolated y values are desired. Outputs Y Interpolated (vector) The interpolated y values. Interpolation Akima spline periodic The kstinterp akima periodic plugin generates a non-rounded Akima spline interpolation for the supplied data set, using periodic boundary conditions. Inputs X Array (vector) The array of x values of the data points to generate the interpolation for. Y Array (vector) The array of y values of the data points to generate the interpolation for. X' Array (vector) The array of x values for which interpolated y values are desired. Outputs Y Interpolated (vector) The interpolated y values. Interpolation cubic spline The Interpolation cubic spline plugin generates a cubic spline interpolation for the supplied data set, using natural boundary conditions. Inputs X Array (vector) The array of x values of the data points to generate the interpolation for. Y Array (vector) The array of y values of the data points to generate the interpolation for. X' Array (vector) The array of x values for which interpolated y values are desired. Outputs Y Interpolated (vector) The interpolated y values. Interpolation cubic spline periodic The Interpolation cubic spline periodic plugin generates a cubic spline interpolation for the supplied data set, using periodic boundary conditions. Inputs X Array (vector) The array of x values of the data points to generate the interpolation for. Y Array (vector) The array of y values of the data points to generate the interpolation for. X' Array (vector) The array of x values for which interpolated y values are desired. Outputs Y Interpolated (vector) The interpolated y values. Interpolation linear The Interpolation linear plugin generates a linear interpolation for the supplied data set. Inputs X Array (vector) The array of x values of the data points to generate the interpolation for. Y Array (vector) The array of y values of the data points to generate the interpolation for. X' Array (vector) The array of x values for which interpolated y values are desired. Outputs Y Interpolated (vector) The interpolated y values. Interpolation polynomial The Interpolation polynomial plugin generates a polynomial interpolation for the supplied data set. The number of terms in the polynomial used is equal to the number of points in the supplied data set. Inputs X Array (vector) The array of x values of the data points to generate the interpolation for. Y Array (vector) The array of y values of the data points to generate the interpolation for. X' Array (vector) The array of x values for which interpolated y values are desired. Outputs Y Interpolated (vector) The interpolated y values. Noise Addition The Noise addition plugin adds a Gaussian random variable to each element of the input vector. The Gaussian distribution used has a mean of 0 and the specified standard deviation. The probability density function of a Gaussian random variable is: Inputs Array (vector) The array of elements to which random noise is to be added. Sigma (scalar) The standard deviation to use for the Gaussian distribution. Outputs Output Array (vector) The array of elements with Gaussian noise added. Periodogram The periodogram plugin produces the periodogram of a given data set. One of two algorithms is used depending on the size of the data set—a fast algorithm is used if there are greater than 100 data points, while a slower algorithm is used if there are less than or equal to 100 data points. Inputs Time Array (vector) The array of time values of the data points to generate the interpolation for. Data Array (vector) The array of data values, dependent on the time values, of the data points to generate the interpolation for. Oversampling factor (scalar) The factor to oversample by. Average Nyquist frequency factor (scalar) The average Nyquist frequency factor. Outputs Frequency (vector) The frequency vector. Periodogram (vector) The frequency response vector for the periodogram. Statistics The statistics plugin calculates statistics for a given data set. Most of the output scalars are named such that the values they represent should be apparent. Standard formulas are used to calculate the statistical values. Inputs Data Array (vector) The array of data values to calculate statistics for. Outputs Mean (scalar) The mean of the data values. Minimum (scalar) The minimum value found in the data array. Maximum (scalar) The maximum value found in the data array. Variance (scalar) The variance of the data set. Standard deviation (scalar) The standard deviation of the data set. Median (scalar) The median of the data set. Absolute deviation (scalar) The absolute deviation of the data set. Skewness (scalar) The skewness of the data set. Kurtosis (scalar) The kurtosis of the data set. diff --git a/docbook/kst/saving-chapter.docbook b/docbook/kst/saving-chapter.docbook index 610aefed..821dd4d4 100644 --- a/docbook/kst/saving-chapter.docbook +++ b/docbook/kst/saving-chapter.docbook @@ -1,234 +1,234 @@ Saving and Printing &kst; provides various methods of saving and exporting data and plots. These methods are described below. Session Files: A capture of the entire &kst; session can be saved for future use. Exporting Vectors: The numerical values of one or more vectors can be written out to an ASCII file. Printing Tabs: One or more of the current tabs can be printed. Exporting Tabs: One or more of the current tabs can be saved to an image file (eg, a png or svg file). Copy Tab Image: A bitmap image of the current tab contents can be saved to the clipbard for pasting into an other application by Selecting Copy Tab Image from the Edit. The image will have the dimensions (in pixels) of the tab in the kst window. Session Files Saving - Selecting Save or Save As from the File menu will save the state of the current kst session. By default, these session files have the extentions .kst. If this session file is opened later, the state of kst, including the loading of all data files, and the saving of all plots will be returned to the state when it was saved. + Selecting Save or Save As from the File menu will save the state of the current kst session. By default, these session files have the extensions .kst. If this session file is opened later, the state of kst, including the loading of all data files, and the saving of all plots will be returned to the state when it was saved. Loading Session files are loaded by: Selecting Open from the File menu. Selecting one of the session files in the Recent Sessions submenu in the File menu. Selecting one of the sessions listed at the bottom of the File menu. using the commend line. For example: kst2 sessionfile.kst Details There are a few details to be aware of with sessions files: Data read from data source files are not embedded in the kst session file. Instead, the file name and frame ranges are stored, and when the session is loaded, the data files are re-loaded from the data source file. If the the data source files have been moved or deleted, then loading will fail. If the contents of the data source files have changed, then the data loaded will be whatever is now in the data file. Vectors which have been created from numpy arrays through the python interface are embedded in the data file, so reloading the session reloads the vectors that have been copied through pyKst. When a session file is loaded, the current session is cleared. When a session file is loaded, the undo stack is cleared. Exporting Vectors Vectors in &kst; can be exported to ascii files. To export or save a vector to a file, select Save Vectors to Disk... from the File menu. From the Export Vectors dialog, select the vectors you want to export, and select the file name where you want to save it. In the dialog example, below, gyro\_x and t\_rw have been selected. Export Vectors Export Vectors to an ASCII file The vectors will be saved to an ascii file. Each field is in a separate column, and the first row lists the field names. If the vectors are of different lengths, then the shorter ones will be linearly interpolated to be the same size as the largest one, with the first and last samples of each vector assumed to be simultaneous. Printing Tabs Printing works as expected. To print, select Print... from the File menu. A system print dialog will be displayed. By default, all tabs will be printed. If the OS supports it, the plots can be exported here to a pdf file. Otherwise, you can use the Exporting Tabs option described in the next section to export to a pdf file. - Each page will be rescaled to fit whatever page size and orientation has been selected. The scaling and resizing rules are the same when a &kst; window is resized. If the page is the same size as has been set as the Reference view size (under Scaling in the Kst Settings dialog, selected by Configure Kst from the Settings menu), then the fonts will all have the sizes they have been set to in the various dialogs. If the selected print size is larger or smaller than this, then the fonts will be also be proportionaly larger or smaller. + Each page will be rescaled to fit whatever page size and orientation has been selected. The scaling and resizing rules are the same when a &kst; window is resized. If the page is the same size as has been set as the Reference view size (under Scaling in the Kst Settings dialog, selected by Configure Kst from the Settings menu), then the fonts will all have the sizes they have been set to in the various dialogs. If the selected print size is larger or smaller than this, then the fonts will be also be proportionally larger or smaller. Exporting Tabs To export &kst; plots to a graphics file, select Export as Image(s)... from the File menu. The following dialog box will appear. Export to Graphics File Export to Graphics File - The root file name is specified in the File name: entry. If Automatic extension is selected, then the file name extension appropriate to the file type is automacially added to the file name. + The root file name is specified in the File name: entry. If Automatic extension is selected, then the file name extension appropriate to the file type is automatically added to the file name. If Export all tabs is selected, then all tabs will be saved in separate files using the rules suggested in the label. So, for example, if the file name selected in File name: is "demo", the file type is png, and Automatic extension is selected, and there are three tabs, then the three tabs will be saved in "demo_View1.png", "demo_View2.png", and "demo_View3.png". SVG images, as well all file types supported by QImage are supported by kst. This includes most common output formats. For vector formats, such as SVG, the output, including text, is in vector format. The Include: Vector formats and Bitmap formats checkboxes select what file types are listed in the File format list to make selection easier. The size of the output image is specified in pixels. The Specify selection has 4 options: In order to preserve the aspect ratio of the on-screen window, the Width and Maintain Aspect Ratio or Height and Maintain Aspect Ratio options can be chosen. The other two options are to specify the Width and Height of the output files, or if you want the output to be a Square, to specify the Size of Square. In the Save Options section, if Save Once is selected, the imaged will be saved with the specified options and settings when Ok or Apply are pressed. If, instead, you would like to output the image at repeated intervals, say for providing a dynamic image for a web page, then select Autosave every and input the desired time between images (note that this is the time to wait after the previous image is complete, and not a high precision timer). Once either the Ok or Apply buttons are pressed, &kst; will begin performing an image export to the specified file names at the interval selected, silently overwriting the existing files. This will continue until Save Once is selected and the tabs are exported, or &kst; is exited. A web page based on this is, admittedly, a little hacky, as it can be subject to displaying partial images if the write is not complete, but it does make for a very quick and easy way of making a kst session viewable remotely. diff --git a/docbook/kst/tutorial.docbook b/docbook/kst/tutorial.docbook index 29430b16..a06ac2f9 100644 --- a/docbook/kst/tutorial.docbook +++ b/docbook/kst/tutorial.docbook @@ -1,861 +1,861 @@ The &kst; Tutorial Welcome 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;: Quickly plot multiple graphs using only the command-line. Analyze data using an extensive set of tools including histograms, power spectra, and custom equations. Effortlessly zoom in and out of interesting areas of plots using either the mouse or keyboard Monitor live streaming data using &kst;'s real-time plotting capabilities. 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. Creating plots from the Command-line 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. The following instructions assume you are working in a broadly bash-compatible shell, such as you would in linux or osX. To obtain an overview of all available &kst; command-line options, type: kst2 --help A syntax description and list of commands similar to the following will be displayed: 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 This tutorial uses a demo ascii data file which is available at gyrodata.dat.gz. Download the file with your browser, and gunzip it. gunzip gyrodata.dat.gz We will first take a look at reading the ASCII file gyrodata.dat 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: kst2 gyrodata.dat -y 1 All the data in the first column will be plotted: 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 Quit from the File menu, or by typing &Ctrl;Q. gyrodata.dat 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: kst2 gyrodata.dat -f 7000 -n 10000 -y 1 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 gyrodata.dat. 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 gyrodata.dat, enter the following: kst2 gyrodata.dat -n 1000 -y 1 If gyrodata.dat was being updated, the plot would continuously scroll to display only the last 1000 frames. Note that the description of the option states that Multiple instances of the option are allowed. This allows quick plotting of more than one curve. To plot all three fields in gyrodata.dat in separate plots, arranged in one column, enter the following: kst2 gyrodata.dat -m 1 -y 1 -y 2 -y 3 The option specifies that the plots should be in a single column. To plot column 1 in one plot, and columns 2 and three in a second plot, displayed side by side enter: kst2 gyrodata.dat -m 2 -P 1 -y 1 -P 2 -y 2 -y 3 Creating plots with the Data Wizard &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 Data Wizard... from the Data menu or click the button on the toolbar. You will be prompted to select a data source by the following dialog: Data Wizard Screen 1 Data Wizard Screen 2 Select the gyrodata.dat 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 icon and browse to the file). Once you have selected the file, the Next button will be enabled. Click on it to proceed to the next page. The following window will be displayed: Data Wizard Screen 2 Data Wizard Screen 2 Fields in gyrodata.dat available to be plotted are listed in the Available data box on the left. Fields that have been selected for plotting are listed in the Selected data box on the right. In the image shown, Column 1 has been selected for plotting. Select Column 1, Column 2, and Column 3 for plotting by moving them to the Selected data box. To move a field from Available data to Selected data, double click on it, or highlight it (with mouse or keyboard) and click on the 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 *, ? and [ ] are supported. Click Next once you have selected the three columns of data. Data Wizard Screen 3 Data Wizard Screen 2 The next tab is used to select the data range to be plotted, and whether to create XY plots, spectrum plots, or both. The Data Range 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 frames. For ASCII files such as gyrodata.dat, a frame is simply a row of data, though for other formats this can be more complicated. Start, End, Count from end, Range, and Read to end 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). 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 Count from end and enter 1000 in Range. &kst; would scroll the data along as new data were appended to the data file. Read 1 sample per N frames and Boxcar filter first The number of data points plotted can be reduced using this option. If Read 1 sample per N frames is not selected, all samples in the selected range will be read. Alternatively, frames in the data file can be skipped by selecting Read 1 sample per N frames. For now, read all of the data by deselecting Read 1 sample per N frames, as shown. In this tutorial, we are only going to plot the gyroscope time series, and not spectra. To do this, select Create XY plots and deselect Create Spectra Plots as shown. Set the X axis vectors for the curves to be The vector to be INDEX by selecting Create from field and selecting INDEX in vector selector, as shown. The FFT Options subsection in the Plot Types section is available only if a power spectrum is to be plotted. This tutorial will not deal with the details of power spectra. Once you are satisfied with all the settings, click Next to advance to the next window. Data Wizard Screen 4 Data Wizard Screen 3 From here, you can change general plotting settings. Most of the settings are self-explanatory. Select 1 new plot per curve for Curve Placement. Once you are satisfied with all the settings, click Finish and the plots will be generated: The Generated Plots The Generated Plots 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 Save As... from the File menu, and save the session as mykstsession.kst: 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. Once the file has been saved, you can exit &kst;. The Basics of Plot Manipulation 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 mykstsession.kst file you saved earlier. This can be done one of three ways: From the command line: kst mykstsession.kst Selecting Open from the toolbar or from the File menu and selecting mykstsession.kst from wherever you saved it. Selecting mykstsession.kst from Recent Files in the File menu. 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 Maximize menu item (see below). Notice that the menu item shows that Z is a shortcut for this, so you could also just type Z in the plot rather than using the context menu for this. Selecting Maximize (either with Z or with the menu) will cause the selected plot to fill the entire kst window. Maximizing a plot Maximizing a plot A plot after Maximizing Maximizing a plot Selecting Maximize (or typing Z 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 Z is going to be the most convienient way +and want to temporarily look at just one of them. Obviously typing Z is going to be the most convenient way to do this, but the context menu is there in case you forget. 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 XY Zoom/Scroll mode, selected by selecting the icon in the tool bar. This is the default mode. 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. Arrow keys scroll the plot. Arrow keys with &Shift; held down will change the scale. The M key auto-zooms the plots to view all of the data. Play around with these options to become familier with the various options. Now look at the plots with y axes labeled Column 2 and Column 3. 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: Tied Zoom Tied Zoom 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 M 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 X Mouse Zoom Mode from the Mode menu or clicking the 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. +the height of the plots in both of the plots that are tied together. 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. Tied Zoom Tied Zoom As with the mouse actions, the keyboard based zoom/scrolling actions described earlier will now be applied to both plots. You can quickly tie or untie all the plots in the window by selecting Toggle Tied Zoom from the Mode menu or by clicking the toolbar button. 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). A Brief Overview of Data Objects In addition to simple plotting, &kst; has the ability to do real time analysis of data using a number of Data Objects, which include spectra, equations, histograms, fits, and filters. As a quick demo of Data Objects, lets create a spectrum. Start &kst; and re-load mykstsession.kst that you created in previous sections. Then, from the Create menu select Power Spectrum. The New Power Spectrum menu will appear. New Spectrum Dialog The New Spectrum Dialog Fill out the dialog as shown. Make sure you select Column 3 (V4) as the Data vector, set the FFT length to 2^13, Sample rate to 60 and select In new tab under Placement. Then select OK. A plot of the spectrum of Column 3 (V4) will appear in a new tab. Spectrum Spectrum 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 l (that is, small L) and to toggle the X axis to log press g. (These options are also available in the context menu under the Zoom submenu in case you forget the keyboard commands). The plot will now be log-log, as shown: Spectrum Spectrum Hitting l (small L) and g will toggle back to linear axis. From the Create you can similarly create histograms, spectrograms and equations of fields you have loaded. Filters 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 gyrodata.dat using either the Data Wizard, as demonstrated earlier, or from the command line: kst2 gyrodata.dat -f 0 -n 1000 -y 2 Once it is loaded, right click in the plot and select Column 1 vs INDEX (C1) from the Filter menu, as shown: Spectrum Spectrum This will bring up the New Filter Dialog: Spectrum Spectrum Fill out the dialog as shown. In particular, select Low Pass Filter as the Plugin, set Cutoff Frequency/Sample Rate to 0.05, and select Place in existing plot. Here we have also set the line to be red, and the Weight to 2, so the line will be more visible. When you are satisfied, select OK. This will add the low-pass filtered data as a new curve in the plot: Filtered Curve Filtered Curve In the same way you can fit a variety of functions to curves using the Fit submenu after right-clicking in a plot.