diff --git a/docbook/kst/index.docbook b/docbook/kst/index.docbook index 426b1610..bd589620 100644 --- a/docbook/kst/index.docbook +++ b/docbook/kst/index.docbook @@ -1,165 +1,163 @@ Kst"> ]> - + The &kst; Handbook Rick Chern
kst@kde.org
 Philip Rodrigues
phil@kde.org
 Barth Netterfield
netterfield@astro.utoronto.ca
 - - - + 2004 The University of British Columbia 2005 The University of Toronto 2017 C. Barth Netterfield &FDLNotice; 2017-01-31 2.0.0 &kst; is a data plotting and manipulation program with powerful plugin support. KDE Kst plotting plot &intro-chapter; &tutorial; &commontasks-chapter; &data-chapter; &plotsandwindows-chapter; &saving-chapter; &eventmonitoring-chapter; &plugins-chapter; &miscfeatures-chapter; &license-chapter; &commandline-chapter; &creatingplugins-chapter; &additionalformats-chapter; &dcop-chapter; &debuglog-chapter; &install-chapter; diff --git a/docbook/kst/tutorial.docbook b/docbook/kst/tutorial.docbook index 031d2c0d..d4f0f2bc 100644 --- a/docbook/kst/tutorial.docbook +++ b/docbook/kst/tutorial.docbook @@ -1,807 +1,814 @@ Barth Netterfield
kst@kde.org
 Rick Chern
kst@kde.org
 2004 The University of British Columbia 2004 - 2017 C. Barth Netterfield 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;. It is based on the &kst; Quick Tour by Barth Netterfield. You are invited to further investigate any features at any time. All features are documented in the rest of this Handbook. Starting &kst; 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 linux or osX. This tutorial uses a demo package of data files which are available online at http://omega.astro.utoronto.ca/kst/tutorial/kst_tutorialdata.tgz. Download and untar the package, and change to the resulting directory: tar -zxvf kst_tutorialdata.tgz cd kst_tutorialdata 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 We will first take a look at reading the ASCII file gyrodata.dat, included in the demo package. 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 CtrlQ. 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 A Quick Tour of 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 + + 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 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. + + 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 way) will cause the selected plot to fill the entire kst window. 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. Maximizing a plot Maximizing a plot 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. 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 convert the Y axis to log hit L and to convert the X axis to log hit 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 From the Create you can similarly create histograms, equations of fields you have loaded, Save your session - we will be using it again in the next section of the tutorial. + - + Filters Conclusion This concludes the &kst; tutorial. Hopefully you have gained enough knowledge to become comfortable with &kst;. Keep in mind that this tutorial does not cover all the functionality of &kst;—there is still much to explore and experiment with. The rest of this Handbook is an in-depth guide to concepts ranging from window layout fundamentals to creation of custom plugins and data source readers. You are encouraged to use &kst; in interesting and innovative ways—you will most likely find that it not only meets, but exceeds your needs and requirements.