Documentation generated from fossil trunk

NAME

Plotchart -
Simple plotting and charting package

SYNOPSIS

package require Tcl  ? 8.5 ? 
package require Tk  ? 8.5 ? 
package require Plotchart  ? 2.0.0 ? 
::Plotchart::createXYPlot w xaxis yaxis args
::Plotchart::createStripchart w xaxis yaxis
::Plotchart::createTXPlot w timeaxis xaxis
::Plotchart::createXLogYPlot w xaxis yaxis
::Plotchart::createLogXYPlot w xaxis yaxis
::Plotchart::createLogXLogYPlot w xaxis yaxis
::Plotchart::createPolarPlot w radius_data
::Plotchart::createWindrose w radius_data sectors
::Plotchart::createIsometricPlot w xaxis yaxis stepsize
::Plotchart::createHistogram w xaxis yaxis
::Plotchart::create3DPlot w xaxis yaxis zaxis
::Plotchart::create3DRibbonPlot w yaxis zaxis
::Plotchart::createPiechart w
::Plotchart::createSpiralPie w
::Plotchart::createRadialchart w names scale style
::Plotchart::createBarchart w xlabels yaxis noseries
::Plotchart::createHorizontalBarchart w xaxis ylabel noseries
::Plotchart::create3DBarchart w yaxis nobars
::Plotchart::create3DRibbonChart w names yaxis zaxis
::Plotchart::createBoxplot w xdata ydata orientation
::Plotchart::createTimechart w time_begin time_end args
::Plotchart::createGanttchart w time_begin time_end args
::Plotchart::createRightAxis w yaxis
::Plotchart::createTableChart w columns  ? widths ? 
$anyplot title text position
$anyplot canvas
$anyplot saveplot filename args
$anyplot xtext text
$anyplot ytext text
$anyplot vtext text
$anyplot xconfig -option value ...
$anyplot yconfig -option value ...
$anyplot background part colour_or_image dir  ? brightness ? 
$anyplot xticklines colour  ? dash ? 
$anyplot yticklines colour  ? dash ? 
$anyplot legend series text  ? spacing ? 
$anyplot removefromlegend series
$anyplot legendconfig -option value ...
$anyplot balloon x y text dir
$anyplot balloonconfig args
$anyplot plaintext x y text dir
$anyplot plaintextconfig args
$anyplot object itemtype series args
$xyplot plot series xcrd ycrd
$xyplot plotlist series xlist ylist every
$histogram plotcumulative series xcrd ycrd
$xyplot trend series xcrd ycrd
$xyplot rchart series xcrd ycrd
$xyplot interval series xcrd ymin ymax  ? ycentr ? 
$xyplot box-and-whiskers series xcrd ycrd
$xyplot vector series xcrd ycrd ucmp vcmp
$xyplot vectorconfig series -option value ...
$xyplot dot series xcrd ycrd value
$xyplot dotconfig series -option value ...
$xyplot contourlines xcrd ycrd values  ? classes ? 
$xyplot contourlinesfunctionvalues xvec yvec valuesmat  ? classes ? 
$xyplot contourfill xcrd ycrd values  ? classes ? 
$xyplot contourbox xcrd ycrd values  ? classes ? 
$xyplot colorMap colours
$xyplot legendisolines values classes
$xyplot legendshades values classes
$xyplot grid xcrd ycrd
$xyplot xband ymin ymax
$xyplot yband xmin xmax
$xyplot labeldot x y text orient
$polarplot plot series radius angle
$windrose plot data colour
$plot3d plotfunc function
$plot3d plotfuncont function contours
$plot3d gridsize nxcells nycells
$plot3d plotdata data
$plot3d colours fill border
$plot3d ribbon yzpairs
$plot3d plot yzpairs
$xyplot dataconfig series -option value ...
$pie plot data
$pie colours colour1 colour2 ...
$pie explode segment
$radial plot data colour thickness
$pie colours colour1 colour2 ...
$barchart plot series ydata colour  ? dir ?   ? brightness ? 
$barchart config -option value ...
$barchart plot series xdata colour  ? dir ?   ? brightness ? 
$barchart config -option value ...
$barchart plot label yvalue colour
$barchart config -option value ...
$ribbon line xypairs colour
$ribbon area xypairs colour
$boxplot plot series label values
$timechart period text time_begin time_end colour
$timechart milestone text time colour
$timechart vertline text time
$timechart hscroll scrollbar
$timechart vscroll scrollbar
$ganttchart task text time_begin time_end completed
$ganttchart milestone text time colour
$ganttchart vertline text time
$ganttchart connect from to
$ganttchart summary text args
$ganttchart color keyword newcolor
$ganttchart font keyword newfont
$ganttchart hscroll scrollbar
$ganttchart vscroll scrollbar
$isoplot plot rectangle x1 y1 x2 y2 colour
$isoplot plot filled-rectangle x1 y1 x2 y2 colour
$isoplot plot circle xc yc radius colour
$isoplot plot filled-circle xc yc radius colour
$table row items
$table separator
$table formatcommand procname
$table cellconfigure args
::Plotchart::viewPort w pxmin pymin pxmax pymax
::Plotchart::worldCoordinates w xmin ymin xmax ymax
::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
::Plotchart::coordsToPixel w x y
::Plotchart::coords3DToPixel w x y z
::Plotchart::polarCoordinates w radmax
::Plotchart::polarToPixel w rad phi
::Plotchart::pixelToCoords w x y
::Plotchart::pixelToIndex w x y
::Plotchart::determineScale xmin xmax inverted
::Plotchart::determineScaleFromList values inverted
::Plotchart::plotconfig charttype component property value
::Plotchart::plotstyle subcmd style args
::Plotchart::createTargetDiagram w limits scale
$target plot series xvalues yvalues
::Plotchart::createPerformanceProfile w max
$performance plot series_and_data_pairs
::Plotchart::plotmethod charttype methodname plotproc
::Plotchart::plotpack w dir args
$anyplot bindplot event command args
$anyplot bindlast series event command

DESCRIPTION

Plotchart is a Tcl-only package that focuses on the easy creation of xy-plots, barcharts and other common types of graphical presentations. The emphasis is on ease of use, rather than flexibility. The procedures that create a plot use the entire canvas window, making the layout of the plot completely automatic.

This results in the creation of an xy-plot in, say, ten lines of code:

    package require Plotchart

    canvas .c -background white -width 400 -height 200
    pack   .c -fill both

    #
    # Create the plot with its x- and y-axes
    #
    set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]

    foreach {x y} {0.0 32.0 10.0 50.0 25.0 60.0 78.0 11.0 } {
        $s plot series1 $x $y
    }

    $s title "Data series"

A drawback of the package might be that it does not do any data management. So if the canvas that holds the plot is to be resized, the whole plot must be redrawn. The advantage, though, is that it offers a number of plot and chart types:

With version 1.5 a new command has been introduced: plotconfig, which can be used to configure the plot options for particular types of plots and charts (cf. CONFIGURATION OPTIONS) With version 1.8.3 several new features were introduced, which allow more interactivity (cf. INTERACTIVE USE)

PLOT CREATION COMMANDS

You create the plot or chart with one single command and then fill the plot with data:
::Plotchart::createXYPlot w xaxis yaxis args
Create a new xy-plot (configuration type: xyplot).
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order. For an inverted axis, where the maximum appears on the left-hand side, use: maximum, minimum and a negative stepsize.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order. For an inverted axis, where the maximum appears at the bottom, use: maximum, minimum and a negative stepsize.
listargsin
  Zero or more options that influence the appearance of the plot:
  • -xlabels {labels}: Custom labels for the x-axis. If the labels are numeric, they are positioned according to the given scale, otherwise they are positioned with equal distance, based on the number of labels. Note: this only works if the stepsize of the xaxis argument is the empty string.
  • -ylabels {labels}: Similarly, custom labels for the y-axis.
  • -box {measures}: See ARRANGING MULTIPLE PLOTS IN A CANVAS
  • -axesbox {measures}: See ARRANGING MULTIPLE PLOTS IN A CANVAS

::Plotchart::createStripchart w xaxis yaxis
Create a new strip chart (configuration type: stripchart). The only difference to a regular XY plot is that the x-axis will be automatically adjusted when the x-coordinate of a new point exceeds the maximum.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order. Note that an inverted x-axis is not supported for this type of plot.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order. For an inverted axis, where the maximum appears at the bottom, use: maximum, minimum and a negative stepsize.

::Plotchart::createTXPlot w timeaxis xaxis
Create a new time-x-plot (configuration type: txplot). The horizontal axis represents the date/time of the data and the vertical axis the values themselves.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listtimeaxisin
  A 3-element list containing the minimum and maximum date/time to be shown and the stepsize (in days) for the time-axis, in this order. Note that an inverted time-axis is not supported.
listxaxisin
  A 3-element list containing minimum, maximum and stepsize for the vertical axis, in this order. For an inverted axis, where the maximum appears at the bottom, use: maximum, minimum and a negative stepsize.

::Plotchart::createXLogYPlot w xaxis yaxis
Create a new xy-plot where the y-axis has a logarithmic scale (configuration type: xlogyplot).
The data should be given as for a linear scale, as the logarithmic transformation is taken of internally.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order. For an inverted axis, where the maximum appears on the left-hand side, use: maximum, minimum and a negative stepsize.
listyaxisin
  A 2-element list containing minimum and maximum for the y-axis, in this order. Note that an inverted logarithmic axis is not supported.

::Plotchart::createLogXYPlot w xaxis yaxis
Create a new xy-plot where the x-axis has a logarithmic scale (configuration type: logxyplot).
The data should be given as for a linear scale, as the logarithmic transformation is taken of internally.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 2-element list containing minimum and maximum for the x-axis, in this order. Note that an inverted logarithmic axis is not supported.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order. For an inverted axis, where the maximum appears on the left-hand side, use: maximum, minimum and a negative stepsize.

::Plotchart::createLogXLogYPlot w xaxis yaxis
Create a new xy-plot where both the x-axis and the y-axis have a logarithmic scale (configuration type: logxlogyplot).
The data should be given as for a linear scale, as the logarithmic transformation is taken of internally.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 2-element list containing minimum and maximum for the x-axis, in this order. Note that an inverted logarithmic axis is not supported.
listyaxisin
  A 2-element list containing minimum and maximum for the y-axis, in this order. Note that an inverted logarithmic axis is not supported.

::Plotchart::createPolarPlot w radius_data
Create a new polar plot (configuration type: polarplot).
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listradius_datain
  A 2-element list containing maximum radius and stepsize for the radial axis, in this order.

::Plotchart::createWindrose w radius_data sectors
Create a new windrose diagram. The diagram will consist of concentric circles as defined by the radius_data argument and a number of sectors (given by the sectors argument). The sectors are drawn in the "nautical" convention, that is: the first is located at the positive y-axis, the second is to the right and so on in a clockwise direction.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the diagram
listradius_datain
  A 2-element list, the first element is the maximum radius, the second is the step to be used for the circles.
intsectors
  Number of sectors to use (defaults to 16).

::Plotchart::createIsometricPlot w xaxis yaxis stepsize
Create a new isometric plot, where the vertical and the horizontal coordinates are scaled so that a circle will truly appear as a circle (configuration type: isometric).
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 2-element list containing minimum, and maximum for the x-axis, in this order.
listyaxisin
  A 2-element list containing minimum, and maximum for the y-axis, in this order.
float|noaxes stepsizein
  Either the stepsize used by both axes or the keyword noaxes to signal the plot that it should use the full area of the widget, to not draw any of the axes.

::Plotchart::createHistogram w xaxis yaxis
Create a new histogram (configuration type: histogram).
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.

::Plotchart::create3DPlot w xaxis yaxis zaxis
Create a new 3D plot.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
listzaxisin
  A 3-element list containing minimum, maximum and stepsize for the z-axis, in this order.

::Plotchart::create3DRibbonPlot w yaxis zaxis
Create a new 3D ribbon plot. It is a simplification of the full 3D plot and allows for the drawing of a ribbon only (the x-axis is dropped).
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
listzaxisin
  A 3-element list containing minimum, maximum and stepsize for the z-axis, in this order.

::Plotchart::createPiechart w
Create a new piechart (configuration type: piechart).
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.

::Plotchart::createSpiralPie w
Create a new "spiral pie" (configuration type: spiralpie), a variation on the ordinary piechart. The value is used to scale the radius, rather than the angle. By default the data are sorted.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.

::Plotchart::createRadialchart w names scale style
Create a new radial chart (the data are drawn as a line connecting the spokes of the diagram) (configuration type: radialchart).
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listnamesin
  Names for the spokes.
floatscalein
  Scale value to determine the position of the data along the spokes.
floatstylein
  Style of the chart (optional). One of:
  • lines - the default: draw the data as independent polylines.
  • cumulative - draw the data as polylines where the data are accumulated.
  • filled - draw the data as filled polygons where the data are accumulated

::Plotchart::createBarchart w xlabels yaxis noseries
Create a new barchart with vertical bars (configuration type: vertbars). The horizontal axis will display the labels contained in the argument xlabels. The number of series given by noseries determines both the width of the bars, and the way the series will be drawn.
If the keyword stacked was specified the series will be drawn stacked on top of each other. Otherwise each series that is drawn will be drawn shifted to the right.
The number of series determines the width of the bars, so that there is space of that number of bars. If you use a floating-point number, like 2.2, instead of an integer, like 2, a small gap between the sets of bars will be drawn - the width depends on the fractional part.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxlabelsin
  List of labels for the x-axis. Its length also determines the number of bars that will be plotted per series.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
int|stacked noseriesin
  The number of data series that will be plotted. This has to be an integer number greater than zero (if stacked is not used).

::Plotchart::createHorizontalBarchart w xaxis ylabel noseries
Create a new barchart with horizontal bars (configuration type: horizbars). The vertical axis will display the labels contained in the argument ylabels. The number of series given by noseries determines both the width of the bars, and the way the series will be drawn.
If the keyword stacked was specified the series will be drawn stacked from left to right. Otherwise each series that is drawn will be drawn shifted upward.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
listylabelsin
  List of labels for the y-axis. Its length also determines the number of bars that will be plotted per series.
int|stacked noseriesin
  The number of data series that will be plotted. This has to be an integer number greater than zero (if stacked is not used).

::Plotchart::create3DBarchart w yaxis nobars
Create a new barchart with 3D vertical bars (configuration type: 3dbars). The horizontal axis will display the labels per bar. The number of bars given by nobars determines the position and the width of the bars. The colours can be varied per bar. (This type of chart was inspired by the Wiki page on 3D bars by Richard Suchenwirth.)
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
intnobarsin
  The number of bars that will be plotted.

::Plotchart::create3DRibbonChart w names yaxis zaxis
Create a new "ribbon chart" (configuration type: 3dribbon). This is a chart where the data series are represented as ribbons in a three-dimensional axis system. Along the x-axis (which is "into" the screen) the names are plotted, each representing a single series. The first plot command draws the furthest series, the second draws the series in front of that and so on.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
widgetwin
  Names of the series, plotted as labels along the x-axis
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis (drawn horizontally!), in this order.
listzaxisin
  A 3-element list containing minimum, maximum and stepsize for the z-axis (drawn vertically), in this order.
intnobarsin
  The number of bars that will be plotted.

::Plotchart::createBoxplot w xdata ydata orientation
Create a new boxplot with horizontal or vertical boxes (box-and-whiskers) (configuration type: boxplot). Depending on the orientation the x- or y-axis is drawn with labels. The boxes are drawn based on the raw data (see the plot subcommand for this type of plot).
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxdatain
  This is either a 3-element list containing minimum, maximum and stepsize for the x-axis, in this order (when orientation is horizontal), or a list of labels for the x-axis (when orientation is vertical). The length of the label list also determines the number of boxes that can be plotted. The labels are also used in the plot subcommand.
listydatain
  This is either a 3-element list containing minimum, maximum and stepsize for the y-axis, in this order (when orientation is vertical), or a list of labels for the y-axis (when orientation is horizontal). The length of the label list also determines the number of boxes that can be plotted. The labels are also used in the plot subcommand.
stringorientationin
  If given, "horizontal" or "vertical" determines the orientation of the boxes. This optional value (default: horizontal) also determines the interpretation of the xdata and ydata arguments.

::Plotchart::createTimechart w time_begin time_end args
Create a new timechart (configuration type: timechart). The time axis (= x-axis) goes from time_begin to time_end, and the vertical spacing is determined by the number of items to plot.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
stringtime_beginin
  The start time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
stringtime_endin
  The end time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
argumentsargsin
  The remaining arguments can be:
  • The expected/maximum number of items. This determines the vertical spacing. (If given, it must be the first argument after "time_end"
  • The keyword -barheight and the number of pixels per bar. This is an alternative method to determine the vertical spacing.
  • The keyword -ylabelwidth and the number of pixels to reserve for the labels at the y-axis.
::Plotchart::createGanttchart w time_begin time_end args
Create a new Gantt chart (configuration type: ganttchart). The time axis (= x-axis) goes from time_begin to time_end, and the vertical spacing is determined by the number of items to plot. Via the specific commands you can then add tasks and connections between the tasks.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
stringtime_beginin
  The start time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
stringtime_endin
  The end time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
argumentsargsin
  The remaining arguments can be:
  • The expected/maximum number of items. This determines the vertical spacing. (If given this way, it must be the first argument after "time_end")
  • The expected/maximum width of the descriptive text (roughly in characters, for the actual space reserved for the text, it is assumed that a character is about ten pixels wide). Defaults to 20. (If given this way, it must be the second argument after "time_end").
  • The keyword -barheight and the number of pixels per bar. This is an alternative method to determine the vertical spacing.
  • The keyword -ylabelwidth and the number of pixels to reserve for the labels at the y-axis.
::Plotchart::createRightAxis w yaxis
Create a plot command that will use a right axis instead of the left axis (configuration type: inherited from the existing plot). The widget (w) must already contain an ordinary plot, as the horizontal axis and other properties are reused. To plot data using the right axis, use this new command, to plot data using the left axis, use the original plot command.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
::Plotchart::createTableChart w columns ? widths ?
Create a command to draw a table. You can use a variety of commands to draw the actual rows of the table, but the number of columns is fixed. (See TABLE CHARTS for an example)
TypeNameMode
widgetwin
  Name of the canvas widget to hold the table.
listcolumnsin
  The headers of the columns in the table. The number of elements determines the number of columns.
listwidthsin
  If given, either a single value, the width in pixels for all columns or for each column the width of that column. If not given, the table is spread out over the width of the canvas (minus the margins).

PLOT METHODS

Each of the creation commands explained in the last section returns the name of a new object command that can be used to manipulate the plot or chart. The subcommands available to a chart command depend on the type of the chart.

General subcommands for all types of charts. \$anyplot is the command returned by the creation command:

$anyplot title text position
Specify the title of the whole chart.
TypeNameMode
stringtextin
  The text of the title to be drawn.
stringpositionin
  The position of the title. The default position is "center", but you can alternatively use "left" or "right". You can use multiple titles with different positions.

$anyplot canvas
Return the name of the canvas (or the alias if you use more than one plot within a canvas). Use this value for the coordinate transformations.
$anyplot saveplot filename args
Draws the plot into a file, using PostScript.
TypeNameMode
stringfilenamein
  Contain the path name of the file to write the plot to.
listargsin
  If the standard PostScript output is used, the option -plotregion can be specifed to save the whole plot (value: bbox) regardless of what is visible in the window. The default (value: window) is to only plot the visible part of the plot.
Optionally you can specify the option -format "some picture format" to store the plot in a different file than a PostScript file. This, however, relies on the Img package to do the actual job.
Note: Because the window holding the plot must be fully visible before Img can successfully grab it, it is raised first. On some systems, for instance Linux with KDE, raising a window is not done automatically, but instead you need to click on the window in the task bar. Similar things happen on Windows XP.
There seems to be something wrong under some circumstances, so instead of waiting for the visibility of the window, the procedure simply waits two seconds. It is not ideal, but it seems to work better.

$anyplot xtext text
Specify the title of the (horizontal) x-axis, for those plots that have a straight x-axis.
TypeNameMode
stringtextin
  The text of the x-axis label to be drawn.

$anyplot ytext text
Specify the title of the (horizontal) y-axis, for those plots that have a straight y-axis.
TypeNameMode
stringtextin
  The text of the y-axis label to be drawn.
$anyplot vtext text
Draw a vertical label to the y-axis. Note: this requires Tk 8.6 or later, for older versions it does nothing.
TypeNameMode
stringtextin
  Text to drawn to the y-axis

$anyplot xconfig -option value ...
Set one or more configuration parameters for the x-axis. The following options are supported:
format fmt
The format for the numbers along the axis.
ticklength length
The length of the tickmarks (in pixels).
ticklines boolean
Whether to draw ticklines (true) or not (false).
scale scale_data
New scale data for the axis, i.e. a 3-element list containing minimum, maximum and stepsize for the axis, in this order.
Beware: Setting this option will clear all data from the plot.

$anyplot yconfig -option value ...
Set one or more configuration parameters for the y-axis. This method accepts the same options and values as the method xconfig.
$anyplot background part colour_or_image dir ? brightness ?
Set the background of a part of the plot
TypeNameMode
stringpart
  Which part of the plot: "axes" for the axes area and "plot" for the inner part. The interpretation depends on the type of plot. Two further possibilities are:
  • image, in which case a predefined image is loaded into the background of the plot.
  • gradient, in which case the background is coloured in different shades of the given colour. The "dir" argument specifies the direction in which the colour gets whiter.
stringcolour_or_image
  Colour for that part or the name of the image if "part" is "image"
stringdir
  The direction of the gradient. One of: top-down, bottom-up, left-right or right-left.
stringbrightness
  Indicates whether the colour should become brighter (bright) or darker (dark). Defaults to bright

$anyplot xticklines colour ? dash ?
Draw vertical ticklines at each tick location
TypeNameMode
stringcolour
  Colour of the lines. Specifying an empty colour ("") removes them again. Defaults to "black"
stringdash
  Optional argument to specify the dash pattern for the lines. Defaults to "lines" Possible values: lines, dots1, dots2, dots3, dots4, dots5. The actual effect depends on the platform.

$anyplot yticklines colour ? dash ?
Draw horizontal ticklines at each tick location
TypeNameMode
stringcolour
  Colour of the lines. Specifying an empty colour ("") removes them again Defaults to "black"
stringdash
  Optional argument to specify the dash pattern for the lines. Defaults to "lines" Possible values: lines, dots1, dots2, dots3, dots4, dots5. The actual effect depends on the platform.

$anyplot legend series text ? spacing ?
Add an entry to the legend. The series determines which graphical symbol is to be used. (As a side effect the legend is actually drawn.)
TypeNameMode
stringseries
  Name of the data series. This determines the colour of the line and the symbol (if any) that will be drawn.
stringtext
  Text to be drawn next to the line/symbol.
integerspacing
  Optional argument to specify the vertical spacing between the entries (in pixels). (Note that this spacing will be reused later.)

$anyplot removefromlegend series
Remove an entry for a series from the legend and redraw it.
TypeNameMode
stringseries
  Name of the data series to be removed.

$anyplot legendconfig -option value ...
Set one or more options for the legend. The legend is drawn as a rectangle with text and graphics inside.
background colour
Set the colour of the background (the default colour is white). Set to the empty string for a transparant legend.
border colour
Set the colour of the border (the default colour is black). Set to the empty string if you do not want a border.
canvas c
Draw the legend in a different canvas widget. This gives you the freedom to position the legend outside the actual plot.
font font
Set the font used to draw the text next to the symbol.
legendtype
Override the type of the legend, that is pre-defined for the current type of plot. May be one of: rectangle or line.
position corner
Set the position of the legend. May be one of: top-left, top-right, bottom-left or bottom-right. (Default value is top-right.)

$anyplot balloon x y text dir
Add balloon text to the plot (except for 3D plots). The arrow will point to the given x- and y-coordinates. For xy-graphs and such, the coordinates are directly related to the axes; for vertical barcharts the x-coordinate is measured as the number of bars minus 1 and similar for horizontal barcharts.
TypeNameMode
floatx
  X-coordinate of the point that the arrow of the balloon will point to.
floaty
  Y-coordinate of the point that the arrow of the balloon will point to.
stringtext
  Text to be drawn in the balloon.
stringdir
  Direction of the arrow, one of: north, north-east, east, south-east, south, south-west, west or north-west.

$anyplot balloonconfig args
Configure the balloon text for the plot. The new settings will be used for the next balloon text.
font fontname
Font to be used for the text
justify left|center|right
Way to justify multiline text
textcolour colour
Colour for the text (synonym: textcolor)
background colour
Background colour for the balloon
outline colour
Colour of the outline of the balloon
margin value
Margin around the text (in pixels)
rimwidth value
Width of the outline of the balloon (in pixels)
arrowsize value
Length factor for the arrow (in pixels)
$anyplot plaintext x y text dir
Add plain text to the plot (except for 3D plots). The text is positioned at the given x- and y-coordinates. For xy-graphs and such, the coordinates are directly related to the axes; for vertical barcharts the x-coordinate is measured as the number of bars minus 1 and similar for horizontal barcharts.
TypeNameMode
floatx
  X-coordinate of the text position
floaty
  Y-coordinate of the text position
stringtext
  Text to be drawn.
stringdir
  Anchor for the text, one of: north, north-east, east, south-east, south, south-west, west or north-west.

$anyplot plaintextconfig args
Configure the plain text annotation for the plot. The new settings will be used for the next plain text.
font fontname
Font to be used for the text
justify left|center|right
Way to justify multiline text
textcolour colour
Colour for the text (synonym: textcolor)
$anyplot object itemtype series args
Draw a canvas item in the plot where the coordinates are scaled using the coordinate system of the plot. In addition to the standard canvas types, it also supports circles, dots and crosses.
Note: Currently implemented for xy-plots, (vertical and horizontal) barcharts, and piecharts.
Note: To add an entry in the legend for the object, you can use the dataconfig subcommand with a type "rectangle". This will cause a rectangle to be shown.
TypeNameMode
stringitemtypein
  Name of a standard canvas item or "circle", "dot" or "cross"
stringseriesin
  The data series it belongs to, used for setting the default drawing options
listargsin
  List of coordinates and drawing options

Note: The commands xconfig and yconfig are currently implemented only for XY-plots and only the option -format has any effect.

For xy plots, stripcharts, histograms and time-x-plots:

$xyplot plot series xcrd ycrd
Add a data point to the plot.
TypeNameMode
stringseriesin
  Name of the data series the new point belongs to.
floatxcrdin
  X-coordinate of the new point. (For time-x plots this must be valid date/time that can be read with the clock scan command).
floatycrdin
  Y-coordinate of the new point.

For xy plots there is the additional command plotlist, which is useful for plotting a large amount of data:

$xyplot plotlist series xlist ylist every
Draw a series of data as a whole. If symbols are asked for, draw them only for every Nth data point.
TypeNameMode
stringseriesin
  Name of the data series the new point belongs to.
floatxlistin
  List of X-coordinates for the data series.
floatycrdin
  List of Y-coordinates for the data series.
inteveryin
  Optional argument stating how often a symbol (if any) should be drawn. If left out, use a simple heuristic: N = sqrt(number of data points).

Note on histograms:

For histograms the x-coordinate that is given is interpreted to be the x-coordinate of the right side of the bar (or line segment). The first bar starts at the y-axis on the left. To completely fill the range of the x-axis, you should draw a bar at the maximum x-coordinate.

For histograms you can also use the plotcumulative command:

$histogram plotcumulative series xcrd ycrd
The arguments mean exactly the same as for the plot command, but the data are accumulated to the previous values.

For xy plots:

$xyplot trend series xcrd ycrd
Draw or update a trend line using the data given sofar.
TypeNameMode
stringseriesin
  Name of the data series the trend line belongs to.
floatxcrdin
  X-coordinate of the new data point
floatycrdin
  Y-coordinate of the new data point
$xyplot rchart series xcrd ycrd
Draw data in the same way as the plot method, but with two lines added that indicate the expected range (+/- 3*standard deviation) of the data.
TypeNameMode
stringseriesin
  Name of the data series the data point belongs to.
floatxcrdin
  X-coordinate of the new data point
floatycrdin
  Y-coordinate of the new data point
$xyplot interval series xcrd ymin ymax ? ycentr ?
Add a vertical error interval to the plot. The interval is drawn from ymin to ymax. If the ycentr argument is given, a symbol is drawn at that position.
TypeNameMode
stringseriesin
  Name of the data series the interval belongs to.
floatxcrdin
  X-coordinate of the interval
floatyminin
  Minimum y-coordinate of the interval.
floatymaxin
  Maximum y-coordinate of the interval.
floatycentrin
  Y-coordinate to draw the symbol at (optional)
$xyplot box-and-whiskers series xcrd ycrd
Draw a box and whiskers in the plot. If the argument xcrd is a list of several values and the argument ycrd is a single value, a horizontal box is drawn with the quartiles determined from the list of values contained in xcrd.
If, instead, the argument ycrd contains a list of several values and the argument xcrd a single value, then a vertical box is drawn and the quartiles are determined from ycrd. (There must be exactly one list of several values. Otherwise an error is reported.)
The option -boxwidth to the dataconfig command determines the width (or height) of the box (default: 10 pixels).
The option -whiskers to the dataconfig command determines whether the whiskers are drawn to the extreme values (value: extremes), to 1.5 times the interquartile range (value: IQR or iqr), or not at all (value: none). If the value is 'IQR' (uppercase), then also extreme values will be shown (from 1.5 to 3 times the IQR as dots, above 3 times IQR as stars). If the value is 'iqr' (lowercase) no extreme values will be shown (default value: IQR).
The option -whiskerwidth to the dataconfig command determines the thickness of the line that draws the whiskers (default: 1 pixel).
The option -mediancolour to the dataconfig command determines the colour of the line used to draw the median within the box (default: same as -colour).
The option -medianwidth to the dataconfig command determines the thickness of the line that draws the median within the box (default: 1 pixel).
TypeNameMode
stringseriesin
  Name of the data series the box-and-whiskers belongs to.
floatxcrdin
  X-coordinate of the box or a list of values.
floatyminin
  Y-coordinate of the box or a list of values.

The box ends at the 1st and 3rd quartile, while the whiskers by default are plotted to span 1.5 IQR (interquartile range) from the 1st and 3rd quartile.
$xyplot vector series xcrd ycrd ucmp vcmp
Draw a vector in the plot. The vector can be given as either cartesian coordinates or as length/angle, where the angle is in degrees and is interpreted according to the mathematical convention or the nautical. (See the vectorconfig subcommand)
TypeNameMode
stringseriesin
  Name of the series the vector belongs to. Determines the appearance and interpretation.
floatxcrdin
  X-coordinate of the point where the arrow appears
floatycrdin
  Y-coordinate of the point where the arrow appears
floatucmpin
  X-component or the length of the vector
floatycentrin
  Y-component or the angle of the vector
$xyplot vectorconfig series -option value ...
] Set the vector drawing options for a particular series
TypeNameMode
stringseriesin
  Name of the series the vector belongs to.
The options can be one of the following:
colour
The colour of the arrow (default: black; synonym: color)
scale value
The scale factor used to convert the length of the arrow into a number of pixels (default: 1.0)
centred onoff
Logical value indicating that the xy-coordinates are to be used as the start of the arrow or as the centre (default: 0; synonym: centered)
type keyword
Interpretation of the vector components. Can be "cartesian" (default), in which case the x- and y-components are expected, "polar" (the angle 0 coincides with the positive x-axis, 90 coincides with the positive y-axis) or "nautical" (0 is "north" and 90 is "east").

$xyplot dot series xcrd ycrd value
Draw a dot in the plot. The size and colour is determined by the value and by the options set for the series it belongs to. (See the dotconfig subcommand)
TypeNameMode
stringseriesin
  Name of the series the dot belongs to. Determines size and colour
floatxcrdin
  X-coordinate of the point where the arrow appears
floatycrdin
  Y-coordinate of the point where the arrow appears
floatvaluein
  Value determining size and colour
$xyplot dotconfig series -option value ...
] Set the dot drawing options for a particular series
TypeNameMode
stringseriesin
  Name of the series the dot belongs to.
The options can be one of the following:
colour
The colour of the dot if no scaling is used or the value exceeds the last limit of the classes.
scale value
The scale factor used to convert the value into the radius of the dot in pixels (default: 1.0)
radius value
The default radius of the dots, used if there is no scaling by value (in pixels; default: 3)
scalebyvalue onoff
Determines whether the dots all have the same size or a size depending on the given value (default: on).
outline onoff
Draw a black circle around the dot or not (default: on)
classes list
Set the limits and the corresponding colours. For instance:
    $xyplot series1 -classes {0 blue 1 green} -colour red

will cause a blue dot to be drawn for values smaller than 0, a green dot for values larger/equal 0 but lower than 1 and a red dot for values larger/equal 1.
3deffect onoff
Show a highlight in the dots, to mimick a 3D effect (default: off)
If there is no list of classes for the particular series, the dots are scaled by the value.
You can combine the colouring by value and the scaling by value by setting a list of classes and setting the scalebyvalue option on.

$xyplot contourlines xcrd ycrd values ? classes ?
Draw contour lines for the values given on the grid. The grid is defined by the xcrd and ycrd arguments. The xcrd argument (resp. ycrd) is expected to be a matrix, implemented as a list of lists which gives the x-coordinates (resp. y-coordinates) of the grid cell corners. The function values are given at these corners. The number of rows in xvec (resp. yvec) is ny and each row contains nx values so that the total number of values in xvec (resp. yvec) is nx * ny. The classes determine which contour lines are drawn. If a value on one of the corners is missing, the contour lines in that cell will not be drawn.
Entries in the legend are drawn via the legendisolines subcommand.
TypeNameMode
listxcrdin
  List of lists, each value is an x-coordinate for a grid cell corner
listycrdin
  List of lists, each value is an y-coordinate for a grid cell corner
listvaluesin
  List of lists, each value is the value at a grid cell corner
listclassesin
  List of class values or a list of lists of two elements (each inner list the class value and the colour to be used). If empty or missing, the classes are determined automatically.
Note: The class values must enclose the whole range of values. Note: The xcrd argument is generally made of nypoints identical rows, while each row of ycrd is made with one single value.
$xyplot contourlinesfunctionvalues xvec yvec valuesmat ? classes ?
Draw contour lines for the values given on the grid. The grid is defined by the xvec and yvec arguments. Here, xvec (resp. yvec) is a list of x-coordinates (resp. y-coordinates). The number of values in xvec (resp. yvec) is the number of points in the x-coordinate (resp. y-coordinate). The function values are given at these corners. The classes determine which contour lines are drawn. If a value on one of the corners is missing, the contour lines in that cell will not be drawn.
Entries in the legend are drawn via the legendisolines subcommand.
TypeNameMode
listxcrdin
  List of x-coordinates in increasing order.
listycrdin
  List y-coordinates in increasing order.
listvaluesmatin
  List of lists, each value is the value at a grid cell corner. The total number of values is valuesmat is nx * ny.
listclassesin
  List of class values or a list of lists of two elements (each inner list the class value and the colour to be used). If empty or missing, the classes are determined automatically.
Note: The class values must enclose the whole range of values.
$xyplot contourfill xcrd ycrd values ? classes ?
Draw filled contours for the values given on the grid. (The use of this method is identical to the "contourlines" method).
Entries in the legend are drawn via the legendshades subcommand.
$xyplot contourbox xcrd ycrd values ? classes ?
Draw the cells as filled quadrangles. The colour is determined from the average of the values on all four corners.
Entries in the legend are drawn via the legendshades subcommand.
$xyplot colorMap colours
Set the colours to be used with the contour methods. The argument is either a predefined colourmap (grey/gray, jet, hot or cool) or a list of colours. When selecting the colours for actually drawing the contours, the given colours will be interpolated (based on the HLS scheme).
TypeNameMode
listcoloursin
  List of colour names or colour values or one of the predefined maps:
  • grey or gray: gray colours from dark to light
  • jet: rainbow colours
  • hot: colours from yellow via red to darkred
  • cool: colours from cyan via blue to magenta
$xyplot legendisolines values classes
Add the contour classes to the legend as coloured lines. The text indicates the values.
TypeNameMode
listvaluesin
  The list of values as used for the actual drawing. This argument is used only if the list of classes is empty.
listvaluesin
  The list of classes as used for the actual drawing.
$xyplot legendshades values classes
Add the contour classes to the legend as coloured rectangles. The text indicates the values.
TypeNameMode
listvaluesin
  The list of values as used for the actual drawing. This argument is used only if the list of classes is empty.
listvaluesin
  The list of classes as used for the actual drawing.
$xyplot grid xcrd ycrd
Draw the grid cells as lines connecting the (valid) grid points.
TypeNameMode
listxcrdin
  List of lists, each value is an x-coordinate for a grid cell corner
listycrdin
  List of lists, each value is an y-coordinate for a grid cell corner

$xyplot xband ymin ymax
Draw a light grey band in the plot, ranging over the full x-axis. This can be used to indicate a "typical" range for the data.
TypeNameMode
floatyminin
  Lower bound for the band
floatymaxin
  Upper bound for the band

$xyplot yband xmin xmax
Draw a light grey band in the plot, ranging over the full y-axis. This can be used to indicate a "typical" range for the data.
TypeNameMode
floatxminin
  Lower bound for the band
floatxmaxin
  Upper bound for the band

$xyplot labeldot x y text orient
Draw a label and a symbol in the plot. The label will appear near the symbol. The label will be drawn in grey, so as not to be too conspicuous.
You can configure the appearance of the symbol by using the data series name "labeldot": $w dataconfig labeldot -colour red -type symbol -symbol dot
TypeNameMode
floatxin
  X-coordinate of the symbol to be drawn
floatyin
  Y-coordinate of the symbol to be drawn
stringtextin
  Text for the label
stringorientin
  Optional orientation (one of w, e, n, s) defining the position of the label with respect to the symbol. It defaults to w (so the label appears left of the symbol).

For polar plots:

$polarplot plot series radius angle
Add a data point to the polar plot.
TypeNameMode
stringseriesin
  Name of the data series the new point belongs to.
floatradiusin
  Radial coordinate of the new point.
floatanglein
  Angular coordinate of the new point (in degrees).

For wind rose diagrams:

$windrose plot data colour
Draw the data contained in the data argument. The data are added to the existing spokes towards the outer circle.
TypeNameMode
listdatain
  List of data (the length should correspond to the number of sectors)
stringcolour
  Colour in which the new segments will be drawn

For 3D plots:

$plot3d plotfunc function
Plot a function defined over two variables x and y. The resolution is determined by the set grid sizes (see the method gridsize for more information).
TypeNameMode
stringfunctionin
  Name of the procedure that calculates the z-value for the given x and y coordinates. The procedure has to accept two float arguments (x is first argument, y is second) and return a floating-point value.

$plot3d plotfuncont function contours
Plot a function defined over two variables x and y using the contour levels in contours to colour the surface. The resolution is determined by the set grid sizes (see the method gridsize for more information).
TypeNameMode
stringfunctionin
  Name of the procedure that calculates the z-value for the given x and y coordinates. The procedure has to accept two float arguments (x is first argument, y is second) and return a floating-point value.
listcontoursin
  List of values in ascending order that represent the contour levels (the boundaries between the colours in the contour map).

$plot3d gridsize nxcells nycells
Set the grid size in the two directions. Together they determine how many polygons will be drawn for a function plot.
TypeNameMode
intnxcellsin
  Number of grid cells in x direction. Has to be an integer number greater than zero.
intnycellsin
  Number of grid cells in y direction. Has to be an integer number greater than zero.

$plot3d plotdata data
Plot a matrix of data.
TypeNameMode
listdatain
  The data to be plotted. The data has to be provided as a nested list with 2 levels. The outer list contains rows, drawn in y-direction, and each row is a list whose elements are drawn in x-direction, for the columns. Example:
    set data {
    {1.0 2.0 3.0}
    {4.0 5.0 6.0}
    }


$plot3d colours fill border
Configure the colours to use for polygon borders and inner area.
TypeNameMode
colorfillin
  The colour to use for filling the polygons.
colorborderin
  The colour to use for the border of the polygons.
$plot3d ribbon yzpairs
Plot a ribbon based on the pairs of yz-coordinates. The colours for the ribbon itself and the edge are taken from the colours option.
TypeNameMode
listyzpairsin
  List of pairs of yz-coordinates

For 3D ribbon plots:

$plot3d plot yzpairs
Plot a ribbon based on the pairs of yz-coordinates. The colours for the ribbon itself and the edge are taken from the colours option.
TypeNameMode
listyzpairsin
  List of pairs of yz-coordinates

For xy plots, stripcharts, histograms and polar plots:

$xyplot dataconfig series -option value ...
Set the value for one or more options regarding the drawing of data of a specific series.
TypeNameMode
stringseriesin
  Name of the data series whose configuration we are changing.

The following options are allowed:
colour c
color c
The colour to be used when drawing the data series.
type enum
The drawing mode chosen for the series. This can be one of line, symbol, or both.
symbol enum
What kind of symbol to draw. The value of this option is ignored when the drawing mode line was chosen. This can be one of plus, cross, circle, up (triangle pointing up), down (triangle pointing down), dot (filled circle), upfilled or downfilled (filled triangles).
radius integer
The size of the radius of the symbol. The total width of the symbol will be 2 times the radius size. The default radius is 4.
width integer
The width of the line (if drawn) or the width of the polygon outline (if -filled).
filled enum
Whether to fill the area above or below the data line or not. Can be one of: no, up or down (SPECIAL EFFECTS)
fillcolour colour
Colour to use when filling the area associated with the data line.
style enum
The style to be used for histograms:
  • filled: Fill the area under the data points with bars (default)
  • spike: Draw vertical lines from the y-axis (lower boundary) to the data point
  • symbol: Draw a symbol at the data point
  • plateau: Draw a horizontal line at the height of the data point
  • stair: Draw a continuous stair-like line connecting the data points

For piecharts and spiral pies:

$pie plot data
Fill a piechart.
TypeNameMode
listdatain
  A list of pairs (labels and values). The values determine the relative size of the circle segments. The labels are drawn beside the circle.
$pie colours colour1 colour2 ...
Set the colours to be used.
TypeNameMode
colorcolour1in
  The first colour.
colorcolour2in
  The second colour, and so on.
$pie explode segment
Explode a segment (that is: move one segment out of the circle). If the segment is indicated as "auto", then you can click on a segment. This will be exploded instead of any previously exploded segment.
TypeNameMode
intsegment
  The segment to be exploded or "auto" if you want to do this interactively.

For radial charts:

$radial plot data colour thickness
Draw a new line in the radial chart
TypeNameMode
listdatain
  A list of data (one for each spoke). The values determine the distance from the centre of the line connecting the spokes.
colorcolourin
  The colour for the line.
intthicknessin
  An optional argument for the thickness of the line.
$pie colours colour1 colour2 ...
Set the colours to be used.
TypeNameMode
colorcolour1in
  The first colour.
colorcolour2in
  The second colour, and so on.

For vertical barcharts:

$barchart plot series ydata colour ? dir ? ? brightness ?
Add a data series to a barchart.
TypeNameMode
stringseriesin
  Name of the series the values belong to.
listydatain
  A list of values, one for each x-axis label.
colorcolourin
  The colour of the bars.
stringdirin
  If given, "top-down" or "bottom-up", to indicate the direction in which the colour changes. (If not given, a uniform colour is used).
stringbrightnessin
  If given, "bright" or "dark" (defaulting to "bright"). The colour will change to respectively white or black, depending on the direction.
$barchart config -option value ...
Set options for drawing the bars.
showvalues boolean
Whether to show the values or not (above the bars)
valuefont newfont
Name of the font to use for the values
valuecolour colour
Colour for the values
valueformat format
Format string to use for formatting the values

For horizontal barcharts:

$barchart plot series xdata colour ? dir ? ? brightness ?
Add a data series to a barchart.
TypeNameMode
stringseriesin
  Name of the series the values belong to.
listxdatain
  A list of values, one for each y-axis label.
colorcolourin
  The colour of the bars.
stringdirin
  If given, "left-right" or "right-left", to indicate the direction in which the colour changes. (If not given, a uniform colour is used).
stringbrightnessin
  If given, "bright" or "dark" (defaulting to "bright"). The colour will change to respectively white or black, depending on the direction.
$barchart config -option value ...
Set options for drawing the bars.
showvalues boolean
Whether to show the values or not (to the right of the bars)
valuefont newfont
Name of the font to use for the values
valuecolour colour
Colour for the values
valueformat format
Format string to use for formatting the values

For 3D barcharts:

$barchart plot label yvalue colour
Add the next bar to the barchart.
TypeNameMode
stringlabelin
  The label to be shown below the column.
floatyvaluein
  The value that determines the height of the column
colorcolourin
  The colour of the column.
$barchart config -option value ...
Set one or more configuration parameters. The following options are supported:
usebackground boolean
Whether to draw walls to the left and to the back of the columns or not
useticklines boolean
Whether to draw ticklines on the walls or not
showvalues boolean
Whether to show the values or not
labelfont newfont
Name of the font to use for labels
labelcolour colour
Colour for the labels
valuefont newfont
Name of the font to use for the values
valuecolour colour
Colour for the values

For 3D ribbon charts:

$ribbon line xypairs colour
Plot the given xy-pairs as a ribbon in the chart
TypeNameMode
listxypairsin
  The pairs of x/y values to be drawn (the series is drawn as a whole)
colorcolourin
  The colour of the ribbon.
$ribbon area xypairs colour
Plot the given xy-pairs as a ribbon with a filled area in front. The effect is that of a box with the data as its upper surface.
TypeNameMode
listxypairsin
  The pairs of x/y values to be drawn (the series is drawn as a whole)
colorcolourin
  The colour of the ribbon/area.
For boxplots:
$boxplot plot series label values
Add a box-and-whisker to the plot. The dataconfig command can be used to customize the box-and-whisker (see the box-and-whiskers command for the xyplot for details).
TypeNameMode
stringseriesin
  Name of the data series the box belongs to
stringlabelin
  The label along the x- or y-axis to which the data belong
listvaluesin
  List of raw values, the extent of the box and the whiskers will be determined from this list.
For timecharts:
$timechart period text time_begin time_end colour
Add a time period to the chart.
TypeNameMode
stringtextin
  The text describing the period.
stringtime_beginin
  Start time of the period.
stringtime_endin
  Stop time of the period.
colorcolourin
  The colour of the bar (defaults to black).

$timechart milestone text time colour
Add a milestone (represented as an point-down triangle) to the chart.
TypeNameMode
stringtextin
  The text describing the milestone.
stringtimein
  Time at which the milestone must be positioned.
colorcolourin
  The colour of the triangle (defaults to black).

$timechart vertline text time
Add a vertical line (to indicate the start of the month for instance) to the chart.
TypeNameMode
stringtextin
  The text appearing at the top (an abbreviation of the date/time for instance).
stringtimein
  Time at which the line must be positioned.
$timechart hscroll scrollbar
Connect a horizontal scrollbar to the chart. See also the section on scrolling.
TypeNameMode
widgetscrollbarin
  The horizontal scrollbar that is to be connected to the chart
$timechart vscroll scrollbar
Connect a vertical scrollbar to the chart. See also the section on scrolling.
TypeNameMode
widgetscrollbarin
  The vertical scrollbar that is to be connected to the chart

For Gantt charts:

$ganttchart task text time_begin time_end completed
Add a task with its period and level of completion to the chart. Returns a list of canvas items that can be used for further manipulations, like connecting two tasks.
TypeNameMode
stringtextin
  The text describing the task.
stringtime_beginin
  Start time of the task.
stringtime_endin
  Stop time of the task.
floatcompletedin
  The percentage of the task that is completed.

$ganttchart milestone text time colour
Add a milestone (represented as an point-down triangle) to the chart.
TypeNameMode
stringtextin
  The text describing the milestone.
stringtimein
  Time at which the milestone must be positioned.
colorcolourin
  The colour of the triangle (defaults to black).

$ganttchart vertline text time
Add a vertical line (to indicate the start of the month for instance) to the chart.
TypeNameMode
stringtextin
  The text appearing at the top (an abbreviation of the date/time for instance).
stringtimein
  Time at which the line must be positioned.

$ganttchart connect from to
Add an arrow that connects the from task with the to task.
TypeNameMode
listfromin
  The list of items returned by the "task" command that represents the task from which the arrow starts.
stringtextin
  The text summarising the tasks
listargsin
  One or more tasks (the lists returned by the "task" command). They are shifted down to make room for the summary.
listtoin
  The list of items returned by the "task" command that represents the task at which the arrow ends.

$ganttchart summary text args
Add a summary item that spans all the tasks listed. The graphical representation is a thick bar running from the leftmost task to the rightmost.
Use this command before connecting the tasks, as the arrow would not be shifted down!
TypeNameMode
stringtextin
  The text summarising the tasks
listargsin
  One or more tasks (the lists returned by the "task" command). They are shifted down to make room for the summary.

$ganttchart color keyword newcolor
Set the colour of a part of the Gantt chart. These colours hold for all items of that type.
TypeNameMode
stringkeywordin
  The keyword indicates which part of the Gantt chart to change:
  • description - the colour of the descriptive text
  • completed - the colour of the filled bar representing the completed part of a task
  • left - the colour for the part that is not yet completed
  • odd - the background colour for the odd entries
  • even - the background colour for the even entries
  • summary - the colour for the summary text
  • summarybar - the colour for the bar for a summary
stringnewcolorin
  The new colour for the chosen items.

$ganttchart font keyword newfont
Set the font of a part of the Gantt chart. These fonts hold for all items of that type.
TypeNameMode
stringkeywordin
  The keyword indicates which part of the Gantt chart to change:
  • description - the font used for descriptive text
  • summary - the font used for summaries
  • scale - the font used for the time scale
stringnewfontin
  The new font for the chosen items.
$ganttchart hscroll scrollbar
Connect a horizontal scrollbar to the chart. See also the section on scrolling.
TypeNameMode
widgetscrollbarin
  The horizontal scrollbar that is to be connected to the chart
$ganttchart vscroll scrollbar
Connect a vertical scrollbar to the chart. See also the section on scrolling.
TypeNameMode
widgetscrollbarin
  The vertical scrollbar that is to be connected to the chart

For isometric plots (to be extended):

$isoplot plot rectangle x1 y1 x2 y2 colour
Plot the outlines of a rectangle.
TypeNameMode
floatx1in
  Minimum x coordinate of the rectangle to be drawn.
floaty1in
  Minimum y coordinate of the rectangle.
floatx2in
  Maximum x coordinate of the rectangle to be drawn.
floaty2in
  Maximum y coordinate of the rectangle.
colorcolourin
  The colour of the rectangle.

$isoplot plot filled-rectangle x1 y1 x2 y2 colour
Plot a rectangle filled with the given colour.
TypeNameMode
floatx1in
  Minimum x coordinate of the rectangle to be drawn.
floaty1in
  Minimum y coordinate of the rectangle.
floatx2in
  Maximum x coordinate of the rectangle to be drawn.
floaty2in
  Maximum y coordinate of the rectangle.
colorcolourin
  The colour of the rectangle.

$isoplot plot circle xc yc radius colour
Plot the outline of a circle.
TypeNameMode
floatxcin
  X coordinate of the circle's centre.
floatycin
  Y coordinate of the circle's centre.
colorcolourin
  The colour of the circle.

$isoplot plot filled-circle xc yc radius colour
Plot a circle filled with the given colour.
TypeNameMode
floatxcin
  X coordinate of the circle's centre.
floatycin
  Y coordinate of the circle's centre.
colorcolourin
  The colour of the circle.

For tables you can use the following subcommands:

$table row items
Draw a single row of items. The appearance of the items can be controlled explicitly via the format command.
TypeNameMode
listitemsin
  List of text items to be drawn, one per column
$table separator
Draw a horizontal line to separate two rows
$table formatcommand procname
Set the procedure that controls the formatting of items. By default items are simply drawn as centered text.
TypeNameMode
stringprocnamein
  Name of the procedure to be used. Its signature is:
proc procname {table widget row column value} {...}

Use the cellconfigure subcommand to set the attributes per cell.
$table cellconfigure args
Set the attributes for the next cell(s) to be drawn.
TypeNameMode
listargsin
  Key-value pairs: -background sets the background colour of the cells, -cell sets the foreground colour, -font sets the text font, -anchor sets the position of the text within the cell and -justify controls the layout of multiline text.
There are a number of public procedures that may be useful in specific situations: Pro memorie.

COORDINATE TRANSFORMATIONS

Besides the commands that deal with the plots and charts directly, there are a number of commands that can be used to convert world coordinates to pixels and vice versa. These include:
::Plotchart::viewPort w pxmin pymin pxmax pymax
Set the viewport for window w. Should be used in cooperation with ::Plotchart::worldCoordinates.
TypeNameMode
widgetwin
  Name of the window (canvas widget) in question.
floatpxminin
  Left-most pixel coordinate.
floatpyminin
  Top-most pixel coordinate (remember: the vertical pixel coordinate starts with 0 at the top!).
floatpxmaxin
  Right-most pixel coordinate.
floatpymaxin
  Bottom-most pixel coordinate.

::Plotchart::worldCoordinates w xmin ymin xmax ymax
Set the extreme world coordinates for window w. The world coordinates need not be in ascending order (i.e. xmin can be larger than xmax, so that a reversal of the x-axis is achieved).
TypeNameMode
widgetwin
  Name of the window (canvas widget) in question.
floatxminin
  X-coordinate to be mapped to left side of viewport.
floatyminin
  Y-coordinate to be mapped to bottom of viewport.
floatxmaxin
  X-coordinate to be mapped to right side of viewport.
floatymaxin
  Y-coordinate to be mapped to top side of viewport.

::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
Set the extreme three-dimensional world coordinates for window w. The world coordinates need not be in ascending order (i.e. xmin can be larger than xmax, so that a reversal of the x-axis is achieved).
TypeNameMode
widgetwin
  Name of the window (canvas widget) in question.
floatxminin
  X-coordinate to be mapped to front side of the 3D viewport.
floatyminin
  Y-coordinate to be mapped to left side of the viewport.
floatzminin
  Z-coordinate to be mapped to bottom of viewport.
floatxmaxin
  X-coordinate to be mapped to back side of viewport.
floatymaxin
  Y-coordinate to be mapped to right side of viewport.
floatzmaxin
  Z-coordinate to be mapped to top side of viewport.

::Plotchart::coordsToPixel w x y
Return a list of pixel coordinates valid for the given window.
TypeNameMode
widgetwin
  Name of the canvas alias (as returned by [\$anyplot canvas]) in question.
floatxin
  X-coordinate to be mapped.
floatyin
  Y-coordinate to be mapped.

::Plotchart::coords3DToPixel w x y z
Return a list of pixel coordinates valid for the given window.
TypeNameMode
widgetwin
  Name of the canvas alias (as returned by [\$anyplot canvas]) in question.
floatxin
  X-coordinate to be mapped.
floatyin
  Y-coordinate to be mapped.
floatyin
  Z-coordinate to be mapped.

::Plotchart::polarCoordinates w radmax
Set the extreme polar coordinates for window w. The angle always runs from 0 to 360 degrees and the radius starts at 0. Hence you only need to give the maximum radius. Note: If the viewport is not square, this procedure will not adjust the extremes, so that would result in an elliptical plot. The creation routine for a polar plot always determines a square viewport.
TypeNameMode
widgetwin
  Name of the canvas alias (as returned by [\$anyplot canvas]) in question.
floatradmaxin
  Maximum radius.

::Plotchart::polarToPixel w rad phi
Wrapper for a call to ::Plotchart::coordsToPixel, which assumes the world coordinates and viewport are set appropriately. Converts polar coordinates to pixel coordinates. Note: To be useful it should be accompanied by a matching ::Plotchart::worldCoordinates procedure. This is automatically taken care of in the creation routine for polar plots.
TypeNameMode
widgetwin
  Name of the canvas alias (as returned by [\$anyplot canvas]) in question.
floatradin
  Radius of the point.
floatphiin
  Angle to the positive x-axis.

::Plotchart::pixelToCoords w x y
Return a list of world coordinates valid for the given window.
TypeNameMode
widgetwin
  Name of the canvas alias (as returned by [\$anyplot canvas]) in question.
floatxin
  X-pixel to be mapped.
floatyin
  Y-pixel to be mapped.
::Plotchart::pixelToIndex w x y
Return the index of the pie segment containing the pixel coordinates (x,y)
TypeNameMode
widgetwin
  Name of the canvas alias (as returned by [\$anyplot canvas]) in question, holding a piechart.
floatxin
  X-pixel to be mapped.
floatyin
  Y-pixel to be mapped.

Furthermore there is a routine to determine "pretty" numbers for use with an axis:

::Plotchart::determineScale xmin xmax inverted
Determine "pretty" numbers from the given range and return a list containing the minimum, maximum and stepsize that can be used for a (linear) axis.
TypeNameMode
floatxminin
  Rough minimum value for the scaling
floatxmaxin
  Rough maximum value for the scaling.
booleaninvertedin
  Optional argument: if 1, then the returned list produces an inverted axis. Defaults to 0 (the axis will be from minimum to maximum)
::Plotchart::determineScaleFromList values inverted
Determine "pretty" numbers from the given list of values and return a list containing the minimum, maximum and stepsize that can be used for a (linear) axis.
TypeNameMode
floatvaluesin
  List of values that will be examined. May contain missing values (empty strings)
booleaninvertedin
  Optional argument: if 1, then the returned list produces an inverted axis. Defaults to 0 (the axis will be from minimum to maximum)

MISSING VALUES

Often data that need to be plotted contain gaps - in a series of measurement data, they can occur because the equipment failed, a sample was not collected correctly or for many other reasons. The Plotchart handles these gaps by assuming that one or both coordinates of such data points are an empty string:
    #
    # Create the plot with its x- and y-axes
    #
    set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]

    foreach {x y} {0.0 32.0 10.0 {} 25.0 60.0 78.0 11.0 } {
        $s plot series1 $x $y
    }

The effect varies according to the type of plot:

OTHER OUTPUT FORMATS

Besides output to the canvas on screen, the module is capable, via canvas postscript, of producing PostScript files. One may wonder whether it is possible to extend this set of output formats and the answer is "yes". This section tries to sum up the aspects of using this module for another sort of output.

One way you can create output files in a different format, is by examining the contents of the canvas after everything has been drawn and render that contents in the right form. This is probably the easiest way, as it involves nothing more than the re-creation of all the elements in the plot that are already there.

The drawback of that method is that you need to have a display, which is not always the case if you run a CGI server or something like that.

An alternative is to emulate the canvas command. For this to work, you need to know which canvas subcommands are used and what for. Obviously, the create subcommand is used to create the lines, texts and other items. But also the raise and lower subcommands are used, because with these the module can influence the drawing order - important to simulate a clipping rectangle around the axes. (The routine DrawMask is responsible for this - if the output format supports proper clipping areas, then a redefinition of this routine might just solve this).

Furthermore, the module uses the cget subcommand to find out the sizes of the canvas. A more mundane aspect of this is that the module currently assumes that the text is 14 pixels high and that 80 pixels in width suffice for the axis' labels. No "hook" is provided to customise this.

In summary:

SPECIAL EFFECTS

As an example of some special effects you can achieve, here is the code for a plot where the area below the data line varies in colour:
canvas .c  -background white -width 400 -height 200
pack .c -fill both

set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]

$s background gradient green top-down

$s dataconfig series1 -filled up -fillcolour white

$s plot series1  0.0 20.0
$s plot series1 10.0 20.0
$s plot series1 30.0 50.0
$s plot series1 35.0 45.0
$s plot series1 45.0 25.0
$s plot series1 75.0 55.0
$s plot series1 100.0 55.0

$s plaintext 30.0 60.0 "Peak" south

The trick is to fill the background with a colour that changes from green at the top to white at the bottom. Then the area above the data line is filled with a white polygon. Thus the green shading varies with the height of the line.

ROOM FOR IMPROVEMENT

In this version there are a lot of things that still need to be implemented:

RESIZING

Plotchart has not been designed to create plots and charts that keep track of the data that are put in. This means that if an application needs to allow the user to resize the window holding the plot or chart, it must take care to redraw the complete plot.

The code below is a simple example of how to do that:

package require Plotchart

grid [canvas .c -background white] -sticky news
grid columnconfigure . 0 -weight 1
grid rowconfigure . 0 -weight 1

bind .c <Configure> {doResize}

proc doPlot {} {
    #
    # Clean up the contents (see also the note below!)
    #
    .c delete all

    #
    # (Re)draw the bar chart
    #
    set p [::Plotchart::createBarchart .c {x y z} {0 100 10} 3]
    $p plot R {10 30 40} red
    $p plot G {30 40 60} green
}

proc doResize {} {
    global redo

    #
    # To avoid redrawing the plot many times during resizing,
    # cancel the callback, until the last one is left.
    #
    if { [info exists redo] } {
        after cancel $redo
    }

    set redo [after 50 doPlot]
}
Please note: The code above will work fine for barcharts and many other types of plots, but as Plotchart keeps some private information for xy plots, more is needed in these cases. This actually requires a command "destroyPlot" to take care of such details. A next version of Plotchart may have that.

Alternatively, you can use the xyplot package which is built on top of Plotchart. This package supports zooming in and zooming out, as well as resizing the plot as a whole. Here is a small demonstration program:

# xyplot_demo.tcl --
#     Demonstration of the xyplot package
#

package require xyplot

set xydata1 {}
set xydata2 {}
set xydata3 {}
set xydata4 {}
for { set i 0 } { $i < 1024 } { incr i } {
    lappend xydata1 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2))}]
    lappend xydata2 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6))}]
    lappend xydata3 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6) + 0.0625 * sin($i/256.0*3.1415*10))}]
    lappend xydata4 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6) + 0.0625 * sin($i/256.0*3.1415*10) + 0.015625 * sin($i/256.0*3.1415*14))}]
}

set xyp [xyplot .xyp -xformat "%5.0f" -yformat "%5.0f" -title "XY plot testing" -background gray90]
pack $xyp -fill both -expand true

set s1 [$xyp add_data sf1 $xydata1 -legend "Serie 1 data" -color red]
set s2 [$xyp add_data sf2 $xydata2 -legend "Serie 2 data" -color green]
set s3 [$xyp add_data sf3 $xydata3 -legend "Serie 3 data" -color blue]
set s4 [$xyp add_data sf4 $xydata4 -legend "Serie 4 data" -color orange]

set xyp2 [xyplot .xyp2 -xticks 8 -yticks 4 -yformat %.2f -xformat %.0f]
pack $xyp2 -fill both -expand true

set s1 [$xyp2 add_data sf1 $xydata1]
set s2 [$xyp2 add_data sf2 $xydata2]
set s3 [$xyp2 add_data sf3 $xydata3]
set s4 [$xyp2 add_data sf4 $xydata4]

Zooming in is done by selecting a rectangle with the left mouse button pressed. Zooming out is done by pressing the right mouse button. If you resize the window, the canvases inside are resized too. If you zoom in, you can scroll the plot via the scrollbars that are automatically attached.

ZOOMING IN

As the Plotchart package does not keep track of the data itself, rescaling an existing plot - for instance when zooming in - would have to be done by redefining the plot and redrawing the data. However, the canvas widget offers a way out by scaling and moving items, so that zooming in becomes a bit simpler.

Whether zooming is indeed useful, depends on the type of plot. Currently it is defined for XY-plots only. The method is called "rescale" and simply redraws the axes and scales and moves the data items so that they conform to the new axes. The drawback is that any symbols are scaled by the same amount. The rescale method works best for plots that only have lines, not symbols.

The method works very simply:

   $p rescale {newxmin newxmax newxstep} {newymin newymax newystep}

CONFIGURATION OPTIONS

The commands plotconfig and plotstyle can be used to set all manner of options. The syntax is:
::Plotchart::plotconfig charttype component property value
Set a new value for the property of a component in a particular chart or plot type or query its current value. Changed properties only have effect for the consecutive plots, not for the ones already created. Each argument is optional.
Note: The plotstyle command offers a more flexible way to control the configuration options.
TypeNameMode
stringcharttypein
  The type of chart or plot (see the configuration type that is mentioned for each create command). If not given or empty, a list of chart types is returned. If it is given, the properties for that particular type are used.
stringcomponentin
  The component of the plot/chart: leftaxis, rightaxis, background, margin and so on. If not given or empty, a list of components is returned. If it is given, the properties for that particular component will be set for that particular type of chart.
stringpropertyin
  The property of the component of the plot/chart: textcolor, thickness of the axis line, etc. If not given or empty, a list of properties is returned. If it is given, that particular property for that particular component will be set for that particular type of chart.
stringvaluein
  The new value for the property. If empty, the current value is returned. If the value is "default", the default value will be restored.
Note, that in some cases an empty value is useful. Use "none" in this case - it can be useful for colours and for formats.
::Plotchart::plotstyle subcmd style args
Manipulate the style in which subsequent plots will be drawn. The default style is "default", but you can define and load any number of other styles.
TypeNameMode
stringsubcmdin
  The subcommand to be executed:
  • configure - this subcommand allows you to set the options per chart type. It takes the same options as the plotconfig command.
  • current - return the current style
  • load - make the given style the active style for subsequent plots and charts
  • names - return the list of currently defined styles
stringstylein
  The name of the plot style to manipulate
listargsin
  The new options for the style - see the plotconfig command for details
Below is a detailed list of the components and properties: See the examples in plotdemos7.tcl for its use.

SCROLLING FOR TIMECHARTS AND GANTT CHARTS

For two types of plots automatic scrolling management has been implemented: timecharts and Gantt charts. The subcommands hscroll and vscroll associate (existing) scrollbars to the plot, in much the same way as for text and canvas widgets.

Once the association is made, the scrollbars are automatically updated if:

For instance:
package require Plotchart

canvas .c -width 400 -height 200
scrollbar .y -orient vertical
scrollbar .x -orient horizontal

grid .c .y -sticky news
grid .x    -sticky news

source plotchart.tcl

set s [::Plotchart::createTimechart .c "1 january 2004"  "31 december 2004" 4]

$s period "Spring" "1 march 2004" "1 june 2004" green
$s period "Summer" "1 june 2004" "1 september 2004" yellow
$s vertline "1 jan" "1 january 2004"
$s vertline "1 apr" "1 april 2004"
$s vertline "1 jul" "1 july 2004"
$s vertline "1 oct" "1 october 2004"
$s vertline "1 jan" "1 january 2005"
$s vertline "1 apr" "1 april 2005"
$s vertline "1 jul" "1 july 2005"
$s milestone "Longest day" "21 july 2004"
$s milestone "Longest day 2" "21 july 2004"
$s milestone "Longest day 3" "21 july 2004"
$s milestone "Longest day 4" "21 july 2004"
$s milestone "Longest day 5" "21 july 2004"
$s milestone "Longest day 6" "21 july 2004"
$s title "Seasons (northern hemisphere)"

$s vscroll .y
$s hscroll .x

The original extent of the chart is from 1 january 2004 to 31 december 2004. But because of the addition of vertical lines in 2005 and more items than was specified at the creation of the chart, both the horizontal and the vertical scrollbar will be enabled.

SPECIALISED PLOTS

Most of the plot and chart types described above have a fairly general use and you simply prepares the data to be plotted yourself. This section describes several plot types that are more specialised, in the sense that they have specific purposes and you pass raw data that are then processed in the plotting routines.

Currently there are the following types:

Most of the general methods for XY-plots work for these plots as well, but their creation and the methods to plot the data are very specific.
::Plotchart::createTargetDiagram w limits scale
Create a new target diagram with circles indicating specific limits. The x-axis represents the unbiased "root-mean-square difference" (typically varying between -1 and 1) and the y-axis represents the normalised bias.
Data points closer to the origin represent better results than data points further away.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listlimitsin
  List of radii for the circles that represent the limits (for instance: 0.5 and 0.7)
doublescalein
  Scale for the axes - defaults to 1, but if the model results are a poor fit, then that may be too small a value. Both axes are scaled in the same way.

$target plot series xvalues yvalues
The plot method takes two series of data of the same length, the first one representing the model results, the second one represent the measurements or, more general, the data that need to be reproduced.
TypeNameMode
stringseriesin
  Name of the series (it will be plotted as a symbol that is configured via the $target dataconfig command (see the XY-plot equivalent for an explanation)
listxvaluesin
  List of model results (missing values are represented as empty strings)
listyvaluesin
  List of measured values (missing values are represented as empty strings; only if both the x and the y values are given, is the pair used in the computations)
::Plotchart::createPerformanceProfile w max
Create a diagram to show the performance of various numerical methods (or solvers). The idea is to first run these methods on a set of problems and measure their performance. The smaller the number the better. Then these methods are compared via a so-called performance profile: the data are scaled and ordered, such that the best method ends up highest.
Because of the nature of the plot all data must be given at once.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
floatmaxin
  Maximum value for the x-axis (the x-axis is the scaled performance of the series).
$performance plot series_and_data_pairs
Plot the data for each given method. The data are identified by the series name and the appearance is controlled via prior dataconfig subcommand.
TypeNameMode
listseries_and_data_pairsin
  List of series names and data. All data must be given at once.
The command plotmethod can be used to add new methods for a particular plot or chart type. It is intended to help you develop specialised graphical displays.
::Plotchart::plotmethod charttype methodname plotproc
Adds a new method for the given plot or chart type. The method is implemented by the command or procedure given in the plotproc argument. The procedure will be called with two extra arguments, the name of the created plot and the canvas widget that contains (see the example below).
TypeNameMode
stringcharttypein
  The type of plot or chart that the new method should be added to.
stringmethodnamein
  Name of the method to be used.
stringplotprocin
  Name of the command or procedure that implements the method.

Here is a trivial example of how to use this:

#
# The custom method "doodle" always adds the text "DOODLE"
# to the plot
#
proc doodle {p w x y} {
    $p plaintext $x $y "DOODLE"
}
::Plotchart::plotmethod xyplot doodle doodle

#
# Use it
pack [canvas .c]

set p [::Plotchart::createXYPlot .c {0 100 10} {0 20 5}]

$p doodle 40 10

TABLE CHARTS

To show what you can do with table charts, here is a simple example that plots a number of random data. The colours depend on the range that the data belong to. For this the procedure setColor is used.
package require Plotchart

pack [canvas .c -bg white -height 300] -fill both -expand yes

::Plotchart::plotconfig table frame outerwidth 3
::Plotchart::plotconfig table frame color red

set t [::Plotchart::createTableChart .c {"Column 1" "Column 2" "Column 3"} 80]


proc setColor {table widget row col value} {
    $table cellconfigure -background white -color black
    if { $value < 2.0 } {
        $table cellconfigure -background red -color white
    }
    if { $value > 6.0 } {
        $table cellconfigure -background green
    }

    return [format "%6.3f" $value]
}

# Command must already exist ...
$t formatcommand setColor

$t title "Demonstration of table charts"
$t separator

for {set i 0} {$i < 9} {incr i} {
    set row {}

    for {set j 0} {$j < 3} {incr j} {
        lappend row [expr {10.0 * rand()}]
    }

    if { $i == 3 } {
        $t separator
    }

    $t row $row
}

CONTROL DISPLAYS

TODO

ARRANGING MULTIPLE PLOTS IN A CANVAS

The command plotpack allows you to copy the contents of a plot into another canvas widget. This canvas widget does not act as a composite plot, but it can be saved as a PostScript file for instance: Note: the command simply takes a snapshot of the plots/charts as they are at that moment.
::Plotchart::plotpack w dir args
Copy the contents of the plots/charts into another widget, in a manner similar to the pack geometry manager.
TypeNameMode
widgetwin
  The name of the canvas widget to copy the plots/charts into
stringdirin
  The direction of the arrangement - top, left, bottom or right
listargsin
  List of plots/charts to be copied.
For example:
    set p1 [createXYPlot ...]
    set p2 [createBarchart ...]

    ... fill the plots ...

    toplevel .t
    pack [canvas .t.c2 -width ...]

    #
    # Copy the two plots above each other in the new canvas
    #
    plotpack .t.c2 top $p1 $p2

A different method is to use the -box and -axesbox options when creating the plot. These control the area in the canvas where the plot or chart will be drawn.

The -box option takes as its value a list of four numbers:

Specifying the width and height makes it easier to reposition the area with respect to other plots.

The -axesbox option is meant to make aligning the axes of a plot with those of other plots easier. The option takes a list of six arguments:

With this option the area the axes occupy is first determined and the complete area is derived from the margins.

For example:

    set p2 [::Plotchart::createXYPlot .c {0 10 1} {-5 5 2.5} -axesbox [list $p1 ne 0 0 200 200]]

will create a second plot whose left axis coincides with the right axis of plot "\$p1" and the top of the axis is at the same heigt as well - because the axes are positioned at a point 0 pixels to the left and 0 pixels below the north-east corner.

INTERACTIVE USE

Plotchart has several features for interactive use (cf. NOTES ON TAGS): If you require different forms of interaction, not covered by Plotchart itself, you can use the tags on the various canvas elements to define other bindings.

The bindplot and bindlast are defined as follows:

$anyplot bindplot event command args
Register a command that will be run whenever the given event occurs in the plot.
TypeNameMode
stringevent
  The event that you want to bind the command to
stringcommand
  Name of the command/procedure that you want to run. The following arguments are prefixed: the x- and y-coordinates of the point in the plot (the world coordinates!), so that the procedure has the signature:
    cmd $xworld $yworld $string1 $string2 $string3

assuming the argument "command" is: {cmd A B C}
$anyplot bindlast series event command
Register a command that will be run when the event occurs within the neighbourhood of the last point added to the given series. (You can use directly after inserting a data point. All such commands will remain active).
TypeNameMode
stringevent
  The event that you want to bind the command to
listcommand
  Name of the command/procedure that you want to run. The following arguments are prefixed: the x- and y-coordinates of the point in the plot (the world coordinates!), so that the procedure has the signature:
    cmd $xworld $yworld $string1 $string2 $string3

assuming the argument "command" is: {cmd A B C}
Here is an example - show the values of the data points in an annotation (from the sample code in plotdemos12.tcl):
#
# Procedure for showing an annotation
#
proc showAnnotation {xcoord ycoord plot w} {

    $plot balloon $xcoord $ycoord "Data point: [format "%.3f, %.3f" $xcoord $ycoord]" north

    after 2000 [list removeAnnotation $w]
}

#
# Procedure for erase an annotation
#
proc removeAnnotation {w} {

    # Use the tags to remove all annotations
    $w delete BalloonText
    $w delete BalloonFrame
}

#
# Create a simple plot and a label
#
pack [canvas .c -bg white] [label .l -textvariable coords]

set p [::Plotchart::createXYPlot .c {0 1000 200} {0 10 1}]

$p dataconfig series1 -type both -symbol cross

foreach x {1 2 5 10 20 50 100 200 500 1000} {
    $p plot series1 $x [expr {log($x)}]

    #
    # Show the annotation for each data point
    #
    $p bindlast series1 <Enter> [list showAnnotation $p %W]
}

NOTES ON TAGS

The implementation of Plotchart relies heavily on the canvas's ability to identify graphical objects by tags and to change the drawing order of the objects. This section documents the tags that are used.

(Note: the tags are not always used consistently - see the notes appearing with the various tags. This section describes the current state.)

General graphical objects:

XY-plots (all types of axes): Items such as labelled dots only have the "data" tag.

Piecharts and spiral pies:

Barcharts:

Barcharts use the same tags as xy-plots (but for gradient-filled bars the data_seriesname is not used).

Histograms and isometric plots:

Currently the only tag used is "data".

Time-charts:

As these plots are scrollable, several tags are used specific to the scrolling: vertscroll, horizscroll, below, lowest, above, timeline, tline. Each item also has a tag of the form "item_number", where "number" is to be replaced by the actual sequence number of the item.

Gantt charts:

In addition to the tags described for the time-charts, the following tags are used: description, completed, summary and summarybar.

Radial charts and polar plots:

Currently the radial lines indicating the grid have no tags. The graphical objects associated with data only have the "data" tag.

Windroses:

Only the tag data_number is currently used ("number" should be replaced by the sequence number of the data, starting at 0.

Contour and isoline plots:

No tags are used.

3D plots and 3D ribbon plots:

No tags are used for the data objects, only for the axes.

Charts decorated with 3D effects:

The following tags are used to identify various types of graphical objects: platform, background, d, u, ticklines.

The text associated with the bars has no tags. The ribbon lines and areas have no tags either.

Tables:

Tags used are: frame, cellbg and celltext In addition: To implement multiple plots and charts in a single canvas, all items also get as a tag the plot/chart they belong to. This enables Plotchart to manipulate only those items.

TODO - SOME PRIVATE NOTES

I have the following wishlist:

KEYWORDS

graphical presentation, plotting, charts, xy-plots, bar charts, strip charts, polar plots, isometric plots, pie charts, time charts, 3D surfaces, 3D bars, coordinates, coordinate transformations, tables