Using DataPlotter - KerryL/DataPlotter GitHub Wiki
Table of Contents
- Main Screen
- Select Data Dialog
- Create Signal Dialog
- Frequency Response Dialog
- Filter Dialog
- Fast Fourier Transform Dialog
- Channel Operations
- Math Channels
- Time Units
- Curve Fitting
- Custom File Formats
Main Screen
This is the main screen in DataPlotter. The buttons at the bottom left of the window provide some basic functionality, but most of the functionality is accessed through mouse interactions and context menus.
Buttons
The Open displays a dialog that allows you to open a file. Alternatively, files may be opened by dragging and dropping them onto the DataPlotter window. After a file has been selected, the user will be presented with the Select Data dialog.
The Auto Scale button rescales the plot axes to fit all data.
If a curve is selected in the curve list at the bottom of the main window, the Remove button can be used to remove it.
The Reload Data button can be used to bypass the Open button and reload the data from the last file loaded. The user will still be prompted with the Select Data dialog.
Context Menus
Most of the functionality of DataPlotter is accessed by right-clicking to pop-up a context menu. There are several areas where a different set of options is provided in the menu:
Plot Area
Right-clicking on the plot area will display a context menu with the following options:
Copy
Copies the current plot image to the clipboard. Using platform-dependent shortcut keys will achieve the same result.
Paste
Pastes text data as plot curves. If valid data is contained in the clipboard text buffer, the Select Data dialog will be displayed. Using platform-dependent shortcut keys will achieve the same result.
Write Image Data File
Displays a Save As dialog, asking where and in what format the image file should be saved.
Export Data
Exports all of the current plot data to a text file in the specified format.
Major Gridlines
Toggles the major gridlines associated with all axes. These changes are not stored and so do not persist.
Minor Gridlines
Toggles the minor gridlines associated with all axes. These changes are not stored and so do not persist.
Legend
Toggles the legend on and off. Legend displays the text in the Curve column of the curve list.
Auto Scale
Same as clicking the Auto Scale button.
Set Background Color
Displays a color-selection dialog permitting the user to choose a different background color. These changes are not stored and so do not persist.
Set Gridline Color
Displays a color-selection dialog permitting the user to choose a different gridline color. These changes are not stored and so do not persist.
Plot Axes
Right-clicking on one of the plot axes will display a context menu with the following options:
Major Gridlines
Toggles visibility of the major gridlines corresponding only to the selected axis.
Minor Gridlines
Toggles visibility of the minor gridlines corresponding only to the selected axis.
Auto Scale Axis
Sets the range of the selected axis such that all data lies between the lower and upper limits.
Set Range
Displays the Set Range Dialog, allowing the user to specify the minimum and maximum values for the selected axis.
Set Major Resolution
Displays a dialog allowing the user to specify the major resolution to use for the selected axis. To switch back to automatically-calculated major resolutions, specify a resolution of 0.
Logarithmic Scale
If the plotted data contains only positive values on the selected axis, the axis scale may be set (or unset) to be logarithmic.
Edit Label
Displays an input box permitting the user to edit the text used to describe the selected axis.
Curve List Headings
Right-clicking on the headings of the curve list will display the following menu item, even if no data is currently plotted.
Create Signal
Displays the Create Signal dialog.
Curve List (X-Axis Row)
Right-clicking on the entry for the x-axis in the curve list will display a menu with the following entries:
Add Math Channel
Displays an input box allowing the user to define a math channel.
Frequency Response
Displays the Frequency Response dialog.
Create Signal
Displays the Create Signal dialog.
Set Time Units
Displays an input box allowing the user to specify the time units.
Scale X-Data
Displays an input box allowing the user to specify a scale factor to apply to the X-data for all curves. Note that this differs from Plot Time-Scaled in that this changes X-data for existing curves rather than generating new curves.
Curve List (Curve Rows)
Right-clicking on an entry for a specific curve in the curve list will display a menu with the following entries:
Add Math Channel
Displays an input box allowing the user to define a math channel.
Frequency Response
Displays the Frequency Response dialog.
Create Signal
Displays the Create Signal dialog.
Plot Derivative
Plots the derivative of the selected curve.
Plot Integral
Plots the integral of the selected curve.
Plot RMS
Plots the root-mean-square of the selected curve.
Plot FFT
Displays the Fast Fourier Transform dialog.
Plot Time-Shifted
Prompts the user to enter the desired time-shift, then plots the selected curve shifted to the right or left, as specified.
Plot Time-Scaled
Prompts the user to enter the desired scale factor, then generates a new curve with the scale factor applied to the X-data. Note that this differs from Scale X-Data in that this does not affect the X-data for existing curves.
Plot Bit
Extracts a specific bit from the curve and plots its value.
Filter Curve
Displays the Filter dialog.
Fit Curve
Displays a dialog asking for the user to describe the model, then generates a linear regression to fit the data.
Remove Curve
Same as clicking the Remove button.
Mouse Plot Interactions
TODO
- Click-and-drag to pan
- Right-click-and-drag to zoom to box
- Middle-click to undo zoom
- CTRL + click-and-drag to zoom, left and bottom fixed? (Buggy, also, zoom stack broken by this)
- SHIFT + click-and-drag is similar, and similarly broken (both right and left click work with CTRL and SHIFT, but right click still displays context menu, which isn't right)
- Double-click to create a cursor
Select Data Dialog
The Select Data dialog gives the users the opportunity to specify which of the columns of data contained in a file should be plotted. The Select All button can be used to toggle the selection of curves to plot between all and none. The Remove Existing Curves check box specifies whether or not the data currently plotted should be removed prior to importing new data, or if the new data should be plotted along side of the existing data. In case of large numbers of available signals, the Filter textbox can be used to show only signals with names that match the specified pattern.
Create Signal Dialog
For convenience, it is possible to generate data for some common signal types from within DataPlotter. To create a new signal, right-click on any row in the curve list, or the curve list heading, and select Create Signal.
For all signals, the following fields are required:
- Start Time - The value of the time value for the first data point in the series in seconds
- Duration - The length of the signal to create in seconds
- Sample Rate - The frequency of data points in the signal in Hertz
The supported signal types are listed below, along with the corresponding parameters required to define the curve. Note that as different types are selected different text boxes will become enabled or disabled, and some text boxes will have different meanings (text box labels will change).
Step
The following Step-specific fields must be specified:
- Initial Value
- Final Value
- Event Time
Step signals start at the Initial Value, then at the Event Time instantaneously change to the Final Value.
The Event Time is, as the name implies, the absolute time at which the step occurs, not the time elapsed since the beginning of the signal (unless Start Time is zero, in which case the elapsed time and the absolute time are the same).
Ramp
The following Step-specific fields must be specified:
- Initial Value
- Final Value
- Slope
- Event Time
Ramp signals start at the Initial Value, then at the Event Time, begin changing towards the Final Value at a rate equal to Slope. After reaching the Final Value, the curve flattens out and the ramp stops.
The Event Time is, as the name implies, the absolute time at which the ramp begins, not the time elapsed since the beginning of the signal (unless Start Time is zero, in which case the elapsed time and the absolute time are the same).
Sinusoid
The following Sinusoid-specific fields must be specified:
- Amplitude
- Offset
- Frequency or Period
- Phase Angle or Phase Delay
The Amplitude is the peak-amplitude (half of the peak-to-peak amplitude). The Offset is the center value of the signal (equal to half of the quantity maximum value minus minimum value).
Either the Frequency or the Period may be specified - it is not necessary to specify both. Similarly, either the Phase Angle or Phase Delay may be specified.
The function is implemented as Offset + Amplitude * sin(time * Frequency + Phase Angle). When Phase Angle is zero, the resulting function is a pure sine funciton. When Phase Angle is 90 degrees, the resulting function is a pure cosine function.
Square
The following Square-wave-specific fields must be specified:
- Amplitude
- Offset
- Duty Cycle
- Frequency or Period
- Phase Angle or Phase Delay
The Amplitude is the peak-to-peak-amplitude (unlike the Sinusoid field). The Offset is the center value of the signal (equal to half of the quantity maximum value minus minimum value).
The Duty Cycle defines the percentage of time that the signal is equal to Offset + Amplitude / 2 (the "ON" portion). The remainder of the time the signal is equal to Offset - Amplitude / 2 (the "OFF" portion).
Either the Frequency or the Period may be specified - it is not necessary to specify both. Similarly, either the Phase Angle or Phase Delay may be specified. The signal's "ON" portion comes before the "OFF" portion, so a signal with a Phase Angle of zero will be "ON", then "OFF."
Triangle
The following Triangle-wave-specific fields must be specified:
- Amplitude or Slope
- Offset
- Frequency or Period
- Phase Angle or Phase Delay
The Amplitude is the peak-to-peak amplitude. It is related to the Slope (assuming a fixed Frequency), so only one or the other must be specified. The Offset is the center value of the signal (equal to half of the quantity maximum value minus minimum value).
Either the Frequency or the Period may be specified - it is not necessary to specify both. Similarly, either the Phase Angle or Phase Delay may be specified.
Sawtooth
The following Sawtooth-specific fields must be specified:
- Amplitude or Slope
- Offset
- Frequency or Period
- Phase Angle or Phase Delay
The parameters have the same meanings as they do for the Triangle signal, except that the relationship between Amplitude and Slope is modified to account for the slope not changing sign every half-Period.
Chirp
The following Chirp-specific fields must be specified:
- Amplitude
- Offset
- Frequency Rate
- Initial Frequency or Initial Period
- Phase Angle or Phase Delay
The meanings of the parameters for the Chirp signal are the same as for the Sinusoid, except that the Initial Frequency or Initial Period only describe the signals frequency at the signal's Start Time, and then the frequency increases linearly with time according to the Frequency Rate.
The Chirp signal is implemented as Offset + Amplitude * sin(time * (Initial Frequency + Frequency Rate * time) + Phase Angle).
White Noise
The following White Noise-specific fields must be specified:
- Amplitude
- Offset
White noise is generated by choosing random values that fall in the range Offset + Amplitude / 2 to Offset - Amplitude / 2.
Frequency Response Dialog
The frequency response function computes the relationship between stimulus data and response data in terms of amplitude change and phase shift. It is a method of experimentally obtaining a system's Bode plot.
As the Number of Averages increases, the resulting function becomes smoother, but has less frequency resolution.
The amplitude response is always plotted, but the phase and coherence data can also be plotted, if desired. If the phase data is plotted, an option is provided to force the reported data into the range of ±180 deg. The amplitude data is given in decibels.
Filter Dialog
The Filter Dialog includes several built-in filters, but also provides users with the ability to specify custom transfer functions to apply to their data. As the filter type and parameters are adjusted, the corresponding transfer function is shown at the bottom of the dialog.
Built-in filters include Low-Pass, High-Pass, Band-Stop, Band-Pass and Notch.
For Low-Pass, High-Pass and Band-Stop filters, an option is provided to compute Butterworth filters (for a maximally smooth pass-band). If Butterworth filters are not selected and the filter Order is greater than one, the user must specify the Damping Ratio. All built-in filters also require that the Cuttoff Frequency is defined.
All filters (including custom filters) can be applied as a Phaseless filter, which means that the filter is applied twice - once in the forward direction and once in the reverse direction.
Fast Fourier Transform Dialog
The Fast Fourier Transform Dialog gives the user the option to select one of several Window functions. These are:
- Uniform - somtimes called "Boxcar Window" (no window function is applied)
- Hann - reduces effects of aliasing
- Hamming - intended to minimize side lobes
- Flat Top - provides very accurate amplitudes
- Exponential - for use with impulse response data
The available Window Sizes are based on the number of points in the sample being analyzed. By default, the maximum window size is selected, which provides the minimum Resolution. As smaller windows are selected, the number of Averages increases, which can result in a smoother frequency spectrum. The number of Averages can also be increased by specifying an Overlap, which is the percent of each window that is also included in the next window.
If the entire time history of the signal is not visible, the user is given the option to Use Zoomed Region Only. Additionally, the user can specify that the Data Plotter should Subtract Mean Value from the data prior to processing, which can help to eliminate extermely large DC components in the frequency spectrum.
Range and Resolution are also provided for reference. The Range is a function of the sampling frequency of the source data while the Resolution is a function of the number of points used in each window (Window Size).
Channel Operations
This section describes the operations that may be performed on a channel.
Derivatives
The derivative function is implemented as a simple finite difference.
Integrals
The integral function is implemented as a simple right-endpoint integral, assuming an initial value of zero.
Root-Mean-Square
For more information on the Root-Mean-Square function, visit the Wikipedia page.
Time-Shifting
Applying a time-shift to the data adds an offset to the x-data of the channel. Positive values shift the data to the right.
Extracting Bits
Sometimes, if recording a status word, for example, it is desirable to see how individual bits of an integer value change over time. The bit numbering begins with zero, so the least-significant bit is bit zero.
Math Channels
Mathematical operations can be performed on curves (or multiple curves), and the result of these operations can be added to the plot as another curve. To add a math channel, the user can right-click on any entry in the curve list and choose Add Math Channel. The user will be prompted to enter the desired expression. The user can specify constant values or datasets (curve values) as part of the expression. Datasets are specified by using square brackets around the row number of the curve. The x-data row is row 0, the first curve is row 1, and so on. To add 6 to every value in the third curve, for example, one would enter 6+[3]. Each expression must include at least one dataset. Note that the original data is never modified - math channels are always added as new curves.
In addition to addition, subtraction, multiplication and division, the following functions are defined:
- log10 - base 10 logarithm
- int - integral (argument must not be a scalar)
- ddt - time derivative (argument must not be a scalar)
- fft - Fast Fourier Transform (argument must not be a scalar; FFT is computed using defaults of a single average over all time and a Hann window)
- log - natural logarithm
- exp - exponential function
- abs - absolute value
Time Units
For some operations, like filtering and Fourier Transforms, the units of the x-axis data must be know (and must be units of time). If DataPlotter was unable to determine the time units while parsing the input file, or if the determined units are incorrect, the user can manually set the time units by right-clicking on the entry in the curve list corresponding to the time data, and choosing Set Time Units.
Curve Fitting
Currently DataPlotter's curve fitting functionality is simplistic, and only support models that take the form of polynomials. To fit a polynomial to a data series, right-click on the row of the curve list corresponding to the desired curve, and choose Fit Curve. The user will be prompted with to enter the order of the polynomial model. The linear least squares fit to the data will be added to the plot as another curve.
Custom File Formats
TODO