diff --git a/docbook/kst/tutorial/tutorial.docbook b/docbook/kst/tutorial/tutorial.docbook new file mode 100644 index 00000000..885ab343 --- /dev/null +++ b/docbook/kst/tutorial/tutorial.docbook @@ -0,0 +1,862 @@ + + +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. For a detailed description of this +concept, see . + + + + + +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 +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. +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. + + + + + + + +