The watch window can be used to show some values on the screen. They will be periodically updated (calculated). The main intention for the watch window is for debugging (like in the IDE of a modern programming language), but it is also useful if you want to show the results of the text export function. In fact, you can display (but not modify) almost everything 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 ,
file export function .
(remember to use the browser's "back" button to return here..)
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:
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.
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").
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.
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 !
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 !
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:
peak_a(freq1, freq2)
returns the amplitude (maybe dB's) of the strongest signal in the specified
frequency range
peak_f(freq1, freq2)
returns the frequency (in Hz) of the strongest signal in the specified frequency
range
noise_n(freq1, frequ2)
returns the noise level in the specified frequency range, normalized to a
1-Hz-RX bandwidth
azim(freq1, freq2)
returns the angle-of-arrival ('bearing') of the strongest signal in the specified
frequency range. Only works in radio-direction-finder mode.
See also: Overview of numeric functions in the documentation of the command interpreter.
still under construction !
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.
Notes:
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 ...
On this tab sheet you define..
defines how the grid for the vertical scale shall be drawn, like "dotted lines", "thin lines", "bold lines" or "no lines at all".
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.
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.
enter a text string which shall appear close to the left vertical axis, like "dBuV/m" like in the sample diagram.
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.
defines if -and where- the legend shall be drawn; how much details shall be in the legend and the font to be used.
On this tab sheet you define..
the interval between two one-pixel-scrolls of the graph area (if the horizontal magnification is set to 100 percent).
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).
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".
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.
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.
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.
On this tab sheet you define..
the color of grid lines,
the background color,
the color for text labels inside the graph plotting area (like time labels etc),
the color for all plotter pens
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:
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.
If this checkmark is enabled, the minimum value of this channel during an aquisition period (or "scroll interval") is visible.
If this checkmark is enabled, the maximum value of this channel during an aquisition period (or "scroll interval") is visible.
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.
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.
This box is used to define some properties of an ASCII file. This allows you to post-process data files generated with other programs or with Spectrum Lab's text-file export function. Some controls in this box are:
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.
The decimal code of a special character in the files used to separate the columns. Use "9" for the TABULATOR character, this is very often used. The charater sequence to separate two lines in an ASCII file is carriage return + new line as usual (cannot be changed).
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.
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.
The following interpreter functions and procedures can be called from Spectrum Lab's command window, or as a periodic or scheduled action:
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.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.
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.