Spectrum Lab's "watch window"

The watch window can be used to show some values on the screen. The displayed values are periodically updated (calculated), and the result displayed in numeric or graphic form. You can display (but not modify) almost anyything in the watch window which can be accessed with the built-in interpreter.

This document describes

See also: Spectrum Lab's main index , numeric expressions,  interpreter functions ,  phase-and amplitude metersfile export function  .
(remember to use the browser's "back" button to return here..)

back to top


The watch list

The "watch list" is a table with numeric expressions (formulae) which you can watch in real time. Some of the columns in this table must be filled out by you (the user), others (like the "Result" column) are filled by the program. The watch list looks like this :

The columns in the watch table are:


Nr

The line number of a definition in the table (also called "plotter channel number"). Cannot be edited ! To move (or 'swap') definition lines, place the mouse cursor in this column, hold the left button down, and move the mouse up or down. A black marker shows the position where the line can be inserted. This feature can be used to sort your definition table by frequency, importance, or whatever - after adding new entries at the end of the table. The maximum count of entries can be modified on the 'Memory, Misc.' tab.


Title

You may define a title for every line, which will make the history plot more readable because the title can be displayed in the legend. If you are familiar with the File Export function, this may sound familiar but it's not the same. If you want to display some of the exported values in the watch window, you can type a string reference instead of plain text for the title, for example: export.title[2] if the title of the second export file column shall be used as title in the watch list (and the history plotter).
The title of a watch definition can also be used to access the calculated result (value) through the interpreter function wv ("watch value").


Expression

Enter an expression here. It will be periodically evaluated after you finished the input to a cell with the enter key (while you are editing, the cell is not evaluated to avoid trouble and 'side effects'). The expression can be a simple function call, but also a long formula, up to 80 characters long.
If you want to display an "already calculated" result from the exported values here, use a reference to the export definition table, for example: export.value[2] (returns the current VALUE from the 2nd column of the export definition table). Frequently used expressions for the watch table can be found at the end of this chapter.


Format

Defines how the result shall be displayed ("formatted"). If you leave this cell(s) empty, the result will be displayed as a floating point number as required. As you can see in the screenshot, some characters in the format string (like #, Y,M,D,h,m,s) have special meanings. An overview of formatting options is here (remember the browser's "back"-button ;-)
Characters which are not recognized in a format string appear in the result string, like the unit "dB" in the screenshot.
IMPORTANT: The format string should have enough "non-optional digit placeholders" (like 0.000###)  to display enough important digits, because is will also be used to draw some numbers to the vertical axis on the left and/or right side of the plot window ! The width of the axis area in the plot window is determined automatically using the min and max values, converted into strings using the format string. Check the effect of different format strings in the result column !


Result (value)

In this column the resulting values are displayed. If the interpreter detects an error in the expression, an error message will appear instead of the value. You can access this value from anywhere through the interpreter function "wv" (watch value) if you need.
Editing the contents of this column makes no sense !


Min Value, Max Value

Use these two columns to define the visible value range for the plotter. Enter the values as numbers or numeric expressions.


You can modify the column widths of the watch table with the mouse. Place the cursor in the grey table headline and move the column separator left or right with the left mouse button pressed.

Frequently used expressions for the watch list:

See also: Overview of numeric functions in the documentation of the command interpreter.

back to top


The History Plotter

still under construction !

(sample diagram)

The plotter can be used to display the latest results of the watch list as slowly scrolling Y(t) diagram. The scrolling speed and other display options can be set on different tabs of this window.

Y-axis
The scaling of the Y-axis for each channel must be defined in the 'min'- and 'max'-columns in the watch list. Because there will (usually) be more than one curve displayed, the Y-axis is scaled from 0 to 100 Percent. Two vertical axises can be visible in the diagram, connected to different channels.
See also: Notes about the verical axis(es) for the 'Layout' tab. (use your browser's 'back' button to return here!).
If the (automatically detected) with for vertical scale (-numbers) fails, a too short format string may be the reason.
X-axis
For this simple plotter, the X-axis is always the time axis. The time when a new sample has been recorded is placed in a buffer, which is saved in a temporary file. For this reasons, there may be 'gaps' along the X-axis. If the sample buffer contains more data than visible on the screen, a "time scroller" appears at the lower edge of the plot window. You can use this to scroll the displayed area from the "present" back into the "past".
Legend
can be displayed on the top, bottom, left or right side of the diagram. Usually, the legend shows the colors and names of all visible channels. By clicking into the legend area of a channel, you can select one channel to modify some settings on the bottom (below the diagram bitmap, not visible in the screenshot shown above).

Notes:

Mouse-tracking readout function

When hovering the mouse over the curve area (in the plotter), the contents of the currently selected channel is displayed either in the window title bar, or in the status bar on the bottom of the window (configurable in the menu under 'View/Windows', 'On window bottom, show cursor-readout' or something else).
If the window is configured for displaying the cursor info on the bottom, you can even copy that info into the clipboard because the text is displayed in a single-line editor control. Mark the text with the mouse (it will not change while the mouse is outside the curve area), and press CTRL-C to copy the selected text into the windows clipboard.

back to top


Plotter Settings

The plotter settings are divided on a number of tab sheets:

Here you can define the plotter's Layout, Horizontal Axis + Timebase, Vertical Axis, Channels, Colors, Legend, and other options ...

 


Layout (tab)

On this tab sheet you define..


Vertical Grid Style

defines how the grid for the vertical scale shall be drawn, like "dotted lines", "thin lines", "bold lines" or "no lines at all".


Vertical Axis Font

defines some properties of the font used to draw numbers and labels for the vertical scales. Click on the 'font' panel to open a dialog where you can select one of the windows fonts and define the font size. The other "font" selection panels work the same way; they are not mentioned in this document.


Left Vertical Axis

declares if a vertical axis shall appear on the left side of the plotter diagram, and to which channel the scale shall be assigned. The vertical axis uses the scale range defined in a channel's "min" and "max" value definition in the watch list (!). The scaling and range of the LEFT vertical axis also define the position of the vertical grid (in contrast to the RIGHT vertical axis).
The width for the numbers on a vertical axis is detected automatically by trying to format the "min" and "max" values into a string, using the "format"-string from the watch definition table.


Left Axis Label

enter a text string which shall appear close to the left vertical axis, like "dBuV/m" like in the sample diagram.


Right Vertical Axis, ..Label

same as the Left Vertical Axis but this axis appears (if required) on the right side of the diagram... but: the right vertical axis does not affect the vertical grid overlay of the graph area.


Legend

defines if -and where- the legend shall be drawn; how much details shall be in the legend and the font to be used.

 

 


Horizontal (tab)

On this tab sheet you define..


Scroll rate

the interval between two one-pixel-scrolls of the graph area (if the horizontal magnification is set to 100 percent).


Horizontal Magnification

Can -one fine day- be used to zoom into a part of the diagram. Usually, this value must be 100 % (and, by the time of this writing, it did not have any function at all).


Markers

There are two types of time markers, which can have different styles. The most important difference is, that 'large' markers will be labelled with a date and/or time expression as defined under "Time Format".


Marker Interval

Is the time (in seconds) between two markers. Be careful: Too large values, and you hardly see any marker, too low values, and the screen will get crowded with markers. A good choice is to set the small marker interval to 15*60 (which means small marker every quarter of an hour) and large markers to 60*60 (which means every full hour). You can let the program do the multiplication for you.


Marker Grid Style

Defines how a marker shall be drawn. You have the choice between thin lines, dotted lines, bold lines, or small, medium or large "ticks". A tick is a short line at the bottom of the diagram, while a "line" in this context is a vertical line across the whole graph area. You should use a 'decent' style for small markers and full lines for large markers. In the sample diagram, dotted lines were used for small markers and thin lines for large markers.


Time format for large markers

Use hh:mm if you need the hour and minute information only, or YYYY-MM-DD if you want to see the date displayed (there is a large variety of valid format strings, more info can be found in the description of the built-in interpreter).
You can use a different format string at the beginning of a new day, like in the sample diagram.

 


Channels & Colors (tab)

On this tab sheet you define..

Colors:

To change a color, click on one of the colored panels and the well-known color selection dialog opens.

Channel settings:

First select the channel number, to see all display properties for a particular channel. This includes:


Graph Style

Defines, HOW the three following values of a channel shall be displayed :
- "off" means the channel is not displayed at all.
- "single dots" means that min,max,average are all displayed as single dots (not joined by lines).
- "mixed" means that min and max are displayed as single dots, but the average value is drawn as a joined line (author's choice..)
- "all lines" means that min,max,average are all displayed as joined lines. Not too good for "noisy" data on a small screen.


Show Min Value

If this checkmark is enabled, the minimum value of this channel during an aquisition period (or "scroll interval") is visible.


Show Max Value

If this checkmark is enabled, the maximum value of this channel during an aquisition period (or "scroll interval") is visible.


Show Averave Value

If this checkmark is enabled, the average value of this channel during an aquisition period (or "scroll interval") is visible.


 

Note: Under certain conditions, there is no difference between "Min", "Max", and "Average" value; especially when the scroll rate of the diagram is quite high.


Other Options (tab)

On this tab sheet you define..

Memory, Misc: defines the dimensions of a file which saves the latest plot data. Enter the number of samples and the number of channels you need. If you use the temporary plot files for an "archive", make the number of samples high enough. The program uses a memory-mapped file as a buffer, so you don't loose data if you exit and restart the program.

Also on this tab are some "special" options, mainly used for testing :


Private

Don't care about this. I used it for debugging.

Data Import/Export:

This box is used to define some properties of an ASCII data file. Such files can be used to exchange data between Spectrum Lab and other programs, mainly for post-processing. Some controls in this box are:


File

defines the name of a text file to import or export data.
Note: You can also change the name of the export file through an interpreter command.


Column Separator Character

The decimal code of a special character in the files used to separate the columns. Possible column separators are comma, semicolon, space, or tab character. The charater sequence to separate two lines in an ASCII file is carriage return + new line as usual (this cannot be changed, not even for Linux users).


Time Column Number

Usually on column in the import/export file holds the TIME of a sample point. If you know that the time in your ASCII files is in the first column, enter "1" in this field. Otherwise the program looks into the first line of the file (which is the "title" line) and looks for the strings "Date", "Time" etc to detect the column number itself. If the time column is not automatically recognized when you try to import data from an ASCII file, you must define this field.


Time Format (string)

Because there are a dozen different ways to write a time+date, you must enter a format string here with a couple of placeholders for all letters in the "time" column of the imported or exported ASCII file. Examples:
YYMMDD hh:mm:ss is a good and 'very logical' format for a machine (most significant value first),
DD/MM/YY hh:mm:ss is prefered by humans.


back to top


Interpreter functions to control the watch window and it's plotter

The following interpreter functions and procedures can be called from Spectrum Lab's command window, or as a periodic or scheduled action:


plot.capture("<filename.ext>")

Saves the current diagrams as an image (like a screen capture).
Examples:


plot.capture("p"+str("YMMDDhh",now)+".jpg")

Saves the diagram as a JPEG image, a date-and-time dependent file name will be automatically generated.

plot.capture("plotted.jpg",70)

Saves the diagram as a JPEG image with a quality of 70 (percent) which is usually ok for the plot screen, so even small letters are readaby. If you use quite large fonts for axis and legend, the quality may be reduced to 50 percent to save disk space. If the quality value is not specified in the argument list, the value from the screen capture options dialog is used.
Note: The plotter only works if its window is visible. For this reason, "plot.capture" fails if the plotter window is not open !

plot.window.left, ..top, ..width, ..height

Retrieve or modify the position and size of the watch/plot window (measured in pixels).

plot.export("filename.txt")

Exports the entire plot data buffer as a textfile, in a "single over". This is the same as the function "Export to Text File" in the watch window's FILE menu. You don't need this function if the option 'periodically export the plotted data' is already set in the "Export" tab, because in that case, the data will be written to the file immediately (appended to the file, line by line, as soon as the new data are available).

plot.export_file = "new_filename.txt"

Changes the name of the exported file on the fly. This only makes sense if the option 'periodically export the plotted data' is set on the "Export" tab, because otherwise you can specify the filename for the exported data in the plot.export command.

wv.XXXX

Accesses one of the calculated values ("watch value") in the watch table. XXXX must be the title of a watch definition. For example, if you have defined a watch named "Noise" which measures the noise level, then wv.Noise will always return that value (called "result" in the watch list). Can be used to show that value anywhere else (outside the watch table).
Note: In contrast to a normal interpreter variable, a title may also begin with a digit. For example, 440k044 is a valid watch title, but not a valid interpreter variable. An example for the wv-function can be found here.

An overview of numeric interpreter functions which can be used in the "expression" column of the watch window (to define the contents of the plotter channels) can be found here.

 

back to top


Last modified (ISO 8601,  YYYY-MM-DD): 2009-07-17