Joe English
Last updated: Saturday 18 November 2000, 10:37
package require Splot
NOTE --You can check the current version of SPLOT by examining the global variable $SPLOT(VERSION).
The plot command is the main interface to SPLOT. It has several subcommands:
plot page subcommand ...
Configures page-wide options; see 2.4. ``Labels, titles, and captions'' and 2.5. ``Multiple graphs per page'' for details.
plot graph subcommand ...
Creates and configures graphs; see 2.3. ``Graphs''.
plot curve create x y [ options... ]
Adds curves to the current graph; see 2.1. ``Curves''.
plot clear
Deletes all graphs from the current page and resets all plot options to the defaults.
The plot curve command creates and modifies curves.
plot curve create x y [ options ]
Adds a new curve to the current graph. x and y specify the data to plot (see 6. ``Specifying the data to plot'').
x specifies the ordinate and y specifies the abscissa. for linear and log-plots. If both x and y are vectors, then both values must be the same length. If x is a scalar, then it is taken as the increment along the X axis.
For polar plots, x corresponds to the length ``r'' and y corresponds to the angle ``theta''.
plot curve create returns a curve id.
plot curve configure options ...
Modifies the current curve. If no options... are specified, returns the current configuration as a paired list of name-value pairs. If a single argument is specified for options... it is interpreted as a paired list.
Valid options for curve configure and curve create are:
plot curve select id
Makes id the current curve, and its parent graph the current graph. id is the curve ID returned from a previous call to plot curve create. Curve IDs are unique within a plot.
Markers allow the user to mark points on the graph with a selected mark style and an optional textual label.
plot marker create [ xcoord ycoord ] [ options... ]
xcoord and ycoord are the position in world coordinates to draw the mark.
Valid options are:
plot graph create [ options... ] plot graph configure [ options... ]
graph create creates a new graph. graph configure changes options on the current graph.
plot graph create returns a graph handle.
plot graph configure with no further arguments returns a paired list of the current graph's configuration options. If further arguments are specified, updates the current graph's configuration. If options is specified as a single argument, it is treated as a paired list of -option-value pairs.
Configuration options are:
plot graph clear
Deletes all curves from the current graph and resets all options to their defaults.
plot graph select graphId
Makes graphId the current graph. graphId is the return value of a previous graph create command.
plot graph list
Returns a list of all the currently active graph IDs.
plot graph curves
Returns a list of all the curve IDs in the current graph.
Labels, titles, and captions may be attached to individual graphs and to the overall page.
plot page label string [ options... ] plot graph label string [ options... ]
plot page label adds a page label. plot graph label adds a label to the current graph.
The following options are supported:
Multiple labels may be specified on any side. Labels are placed from the outside in, in the order in which they are specified. For example:
plot page label "First title line" -fontsize large -side top plot page label "Second title line" -fontsize medium -side top plot page label "Bottom caption" -side bottom
NOTE --Bug: There is no way to modify or delete labels once they have been created.
See also 2.5. ``Multiple graphs per page''.
SPLOT allows multiple graphs to be placed on a page. Graphs are arranged in a regular grid. The dimensions of the grid are specified with the plot page layout command, giving the number of rows and columns of the grid.
plot page layout rows cols
For example, plot page layout 3 2 would allow up to six graphs -- three down and two across -- to be placed on the page.
New graphs are created with the graph create command. The location and size of each graph is specified by the -row and -column graph options. Rows and columns are numbered from 1; i.e., graph create -row 1 -column 1 would place the new graph in the upper left-hand corner of the page and -row 3 -column 2 would be the lower right corner in a 3 by 2 layout.
Graphs may span more than one column on the grid by specifying the -placement option instead. The argument to the -placement is either a pair of numbers "r c" or four numbers "r1 c1 r2 c2". The first case is identical to specifying -row and -column; the second case also specifies the ending row and column.
A legend may be attached to each graph, as well as page-wide legend. Graph legends and page legends are configured with the plot graph legend and plot page legend commands, respectively.
plot [graph|page] legend label "text" [ options ]
Adds a new label to the current legend with the specified label string and curve options. options is as for curves.
There are two options for specifying the location of a graph legend. It can be placed next to the graph with the place subcommand, or on the graph itself with the position subcommand.
plot graph legend side side
Places the legend next to the graph; side is one of top, left, bottom, or right (same as for labels). The graph area shrinks accordingly.
plot graph legend position x y
Places the legend on the graph itself. x and y are floating point values between 0.0 and 1.0 specifying the position of the legend's lower-left corner on the graph. The position 0.0 0.0 is the bottom left corner of the graph, 1.0 1.0 is the upper right corner.
Absolute positions are not supported for page legends; they may only be placed on one side of the page.
plot page legend side side
side is as for graph legends.
%%% Legend position should be configurable via options
%%% position should be extended to allow negative numbers, meaning the position of the (right | top) corner wrt the (right | top) of the view area. *OR*, use -anchor (nw|n|ne|...), like Tk. (-anchor would also be useful for legend -place; allow top right, etc.)
%%% Allow legends to be placed on the grid as with graphs.
plot postscript write filehandle [ options... ] plot postscript file filename [ options... ] plot postscript configure [ options... ]
plot postscript write writes a Postscript rendition of the current plot to a Tcl file handle (typically this will be a pipeline to a print spooler process). plot postscript file saves the output to a named file. plot postscript configure sets Postscript configuration options without producing any output.
Valid options are:
For example:
# Open pipe to print spooler: set fp [open "|lp" w] plot postscript write $fp close $fp
plot pick option x y
Returns information about the plot element at point (x,y). Valid options are:
As with the curve option, returns the empty list if no curve is near the specified point.
NOTE --BUG: for plot pick curve ..., the user must click directly on a data point, not on the line between two points.
The Tk interface to SPLOT consists of a plot widget. The plotter command creates a new plot widget, which may be used like any other Tk widget.
plotter pathName [ options ]
The plotter command creates a new window (given by the pathName argument) and makes it into a plotter widget. The widget command accepts the same subcommands as the plot command described above:
pathName curve [ options ... ] pathName graph [ options ... ] pathName page [ options ... ] pathName clear [ ... ]
In addition, it supports the usual Tk widget command options:
pathName configure [ options... ] pathName cget [ options... ]
plotter .p pack .p -expand true -fill both .p page label "Example" -side top .p curve create y t
The plotdb load command can at present only load data files in Scope Save format. This format stores multiple data elements in one file. Data elements are accessed by name, and may be scalars, vectors, or 2-D matrices.
Data files contain a series of records, each record begins with a one-line header followed by the data. Lines beginning with a pound sign (#) are comments, and are ignored.
The format of a header line is as follows:
name #rows [ #cols [ fmt ]]
name is the name of the data set. The name contains only alphanumeric characters, and must begin with a letter. Record names are case-insensitive, though upper-case is recommended. Note that underscores (_) are not allowed in record names.
#rows and #cols are base-10 integers specifying the number of rows and the number of columns, respectively. If #cols is omitted, it is assumed to be 1 (i.e., a vector).
fmt, if present, should be 0.
Free-form floating point numbers follow the header line. Exponential notation is supported (e.g., 1.0e-3). Line breaks, spaces, and tabs are ignored. Exactly #rows times #cols numbers must be present, and there must be a newline at the end of the data.
Matrix data is stored in column-major format; that is, all the values in column 1 are written first, followed by column 2, and so on.
For example:
#Description: Example SPLOT data file #Contents: # X -- 10-element vector # Y -- 2 by 3 matrix [11 12 13 ; # 21 22 23 ] # X 10 1 0 0.5878 0.9511 0.9511 0.5878 0.0000 -0.5878 -0.9511 -0.9511 -0.5878 0.0000 # Note that matrices are stored column-major, so they # are "transposed" from the usual way of writing them Y 2 3 0 11 21 12 22 13 23 # End of file
Graph types other than linear are not fully implemented.
The ordinate and abscissa arguments to the plot curve create command are interpreted as follows:
Otherwise, the argument is parsed as a name. Names must contain only alphanumeric characters and are case-sensitive in general.
To resolve named arguments, SPLOT first checks the plot database, then the names of local Tcl variables, then any addition data sources as described below.
The plot database associates names with data sets. Names are alphanumeric and case-insensitive. Data sets are vectors of floating point numbers.
The plotdb command manipulates the plot database.
plotdb set name value
Adds name to the plot database, with value value. value is a list of floating point numbers.
plotdb get name
Returns the value of the data set name in the plot database, if it exists. Signals an error otherwise.
plotdb list
Returns a list of the names of all the data sets currently in the plot database.
plotdb load filename
Reads the contents file filename into the plot database; filename. See 4. ``Data file formats'' for a description of the data file format.
SPLOT can also use BLT vectors as a data source if the BLT package is available. BLT vectors can be referenced by name in the plot curve command.
Note: plot database variables are case-insensitive; BLT vector names are case-sensitive. If a plot database variable exists with the same name as a BLT vector, the plot database variable takes precedence.
... to be written.
Added pick command.
The Plotter widget now behaves more like other Tk widgets; configure and configure -option commands now work as expected; the focus highlight and 3-d relief are now implemented.
The default size of the plotter widget has been increased.
The legend place has been renamed to legend side. legend place is temporarily still supported for backwards-compatibility.
Found a new autoscaling algorithm; this one seems to work pretty well.
plot graph create now returns a graph handle. This can be passed to plot graph select to reselect (and modify) a graph after other graphs have been created.
Added curve configure and curve select commands, analogous to plot graph select.
Important note: The syntax of the plot curve has changed. Instead of
plot curve y xuse:
plot curve create x y
This change is to enable forward compatibility with other curve options, and to fix the order of the arguments. The old syntax will still be supported temporarily.
The plotdb command is no longer necessary. It is now possible to use a list of floating point values as the ordinate and abscissa arguments to the plot curve create command; see 6. ``Specifying the data to plot''.
Several other new features have been added.