NAME¶
Plotchart - Simple plotting and charting package
SYNOPSIS¶
package require
Tcl ?8.5?
package require
Tk ?8.5?
package require
Plotchart ?2.1.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_or_plot yaxis
::Plotchart::createTableChart w columns ?widths?
$anyplot title
text position
$anyplot subtitle
text
$anyplot canvas
$anyplot saveplot
filename args
$anyplot xtext
text
$anyplot ytext
text
$anyplot vtext
text
$anyplot xsubtext
text
$anyplot ysubtext
text
$anyplot vsubtext
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
$anyplot deletedata
$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:
- •
- XY-plots like the one shown above with any number of data series.
- •
- Stripcharts, a kind of XY-plots where the horizontal axis is adjusted
automatically. The result is a kind of sliding window on the data
series.
- •
- Polar plots, where the coordinates are polar instead of cartesian.
- •
- Histograms, for plotting statistical information.
- •
- Isometric plots, where the scale of the coordinates in the two directions
is always the same, i.e. a circle in world coordinates appears as a circle
on the screen.
You can zoom in and out, as well as pan with these plots ( Note: this
works best if no axes are drawn, the zooming and panning routines do not
distinguish the axes), using the mouse buttons with the control key and
the arrow keys with the control key.
- •
- Piecharts, with automatic scaling to indicate the proportions.
- •
- Barcharts, with either vertical or horizontal bars, stacked bars or bars
side by side.
- •
- Timecharts, where bars indicate a time period and milestones or other
important moments in time are represented by triangles.
- •
- 3D plots (both for displaying surfaces and 3D bars)
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).
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list xaxis (in)
- 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.
- list yaxis (in)
- 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.
- list args (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list xaxis (in)
- 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.
- list yaxis (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list timeaxis (in)
- 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.
- list xaxis (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list xaxis (in)
- 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.
- list yaxis (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list xaxis (in)
- A 2-element list containing minimum and maximum for the x-axis, in this
order. Note that an inverted logarithmic axis is not
supported.
- list yaxis (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list xaxis (in)
- A 2-element list containing minimum and maximum for the x-axis, in this
order. Note that an inverted logarithmic axis is not
supported.
- list yaxis (in)
- 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).
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list radius_data (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the diagram
- list radius_data (in)
- A 2-element list, the first element is the maximum radius, the second is
the step to be used for the circles.
- int sectors
- 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).
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list xaxis (in)
- A 2-element list containing minimum, and maximum for the x-axis, in this
order.
- list yaxis (in)
- A 2-element list containing minimum, and maximum for the y-axis, in this
order.
- float|noaxes stepsize (in)
- 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).
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list xaxis (in)
- A 3-element list containing minimum, maximum and stepsize for the x-axis,
in this order.
- list yaxis (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list xaxis (in)
- A 3-element list containing minimum, maximum and stepsize for the x-axis,
in this order.
- list yaxis (in)
- A 3-element list containing minimum, maximum and stepsize for the y-axis,
in this order.
- list zaxis (in)
- 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).
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list yaxis (in)
- A 3-element list containing minimum, maximum and stepsize for the y-axis,
in this order.
- list zaxis (in)
- 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).
- widget w (in)
- 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.
- widget w (in)
- 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).
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list names (in)
- Names for the spokes.
- float scale (in)
- Scale value to determine the position of the data along the spokes.
- string style (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list xlabels (in)
- List of labels for the x-axis. Its length also determines the number of
bars that will be plotted per series.
- list yaxis (in)
- A 3-element list containing minimum, maximum and stepsize for the y-axis,
in this order.
- int|stacked noseries (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list xaxis (in)
- A 3-element list containing minimum, maximum and stepsize for the x-axis,
in this order.
- list ylabels (in)
- List of labels for the y-axis. Its length also determines the number of
bars that will be plotted per series.
- int|stacked noseries (in)
- 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.)
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list yaxis (in)
- A 3-element list containing minimum, maximum and stepsize for the y-axis,
in this order.
- int nobars (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- widget w (in)
- Names of the series, plotted as labels along the x-axis
- list yaxis (in)
- A 3-element list containing minimum, maximum and stepsize for the y-axis
(drawn horizontally!), in this order.
- list zaxis (in)
- A 3-element list containing minimum, maximum and stepsize for the z-axis
(drawn vertically), in this order.
- int nobars (in)
- 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).
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list xdata (in)
- 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.
- list ydata (in)
- 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.
- string orientation (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- string time_begin (in)
- The start time given in a form that is recognised by the clock scan
command (e.g. "1 january 2004").
- string time_end (in)
- The end time given in a form that is recognised by the clock scan
command (e.g. "1 january 2004").
- arguments args (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- string time_begin (in)
- The start time given in a form that is recognised by the clock scan
command (e.g. "1 january 2004").
- string time_end (in)
- The end time given in a form that is recognised by the clock scan
command (e.g. "1 january 2004").
- arguments args (in)
- 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_or_plot yaxis
- Create a plot command that will use a right axis instead of the left axis
(configuration type: inherited from the existing plot). The canvas widget
must already contain an ordinary plot, as the horizontal axis and other
properties are reused. Preferably use the plot command, as with multiple
plots in a canvas (also when redefining an existing plot!), the wrong
geometry might be used.
To plot data using the right axis, use this new command, to plot data using
the left axis, use the original plot command.
- widget w_or_plot (in)
- Name of the existing canvas widget to hold the plot or preferably
the plot command for the plot with the left axis.
- list yaxis (in)
- 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)
- widget w (in)
- Name of the canvas widget to hold the table.
- list columns (in)
- The headers of the columns in the table. The number of elements determines
the number of columns.
- list widths (in)
- 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.
- string text (in)
- The text of the title to be drawn.
- string position (in)
- 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 subtitle text
- Specify the subtitle of the whole chart.
- string text (in)
- The text of the subtitle to be drawn.
- $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.
- string filename (in)
- Contain the path name of the file to write the plot to.
- list args (in)
- 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.
- string text (in)
- 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.
- string text (in)
- 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.
- string text (in)
- Text to drawn to the y-axis
- $anyplot xsubtext text
- Specify the subtext of the (horizontal) x-axis, for those plots that have
a straight x-axis. This text is drawn below the primary text.
Since this involves positioning the primary text and setting margins, you
need to set the option "usesubtext" for the bottom axis via the
plotstyle command. The relevant options are: usesubtext, subtextcolor and
subtextfont.
- string text (in)
- The secondary text of the x-axis label to be drawn.
- $anyplot ysubtext text
- Specify the subtext of the (vertical) y-axis, for those plots that have a
straight y-axis. This text is drawn below the primary text, for both axes
on the left and the right.
Since this involves positioning the primary text and setting margins, you
need to set the option "usesubtext" for the left or right axis
via the plotstyle command. The relevant options are: usesubtext,
subtextcolor and subtextfont.
- string text (in)
- The secondary text of the y-axis label to be drawn.
- $anyplot vsubtext text
- Specify the subtext of the (vertical) y-axis, for those plots that have a
straight y-axis. This text is drawn to the right of the primary
text, for both axes on the left and the right.
Since this involves positioning the primary text and setting margins, you
need to set the option "usesubtext" for the left or right axis
via the plotstyle command. The relevant options are: usevsubtext,
vsubtextcolor and vsubtextfont. (Note the "v" to distinguish
this option from the text at the top of a vertical axis that is drawn via
$anyplot ytext or $anyplot ysubtext.)
- string text (in)
- The secondary (vertical) text of the y-axis label to be drawn.
- $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
- string part
- 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.
- string colour_or_image
- Colour for that part or the name of the image if "part" is
"image"
- string dir
- The direction of the gradient. One of: top-down, bottom-up, left-right or
right-left.
- string brightness
- 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
- string colour
- Colour of the lines. Specifying an empty colour ("") removes
them again. Defaults to "black"
- string dash
- 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
- string colour
- Colour of the lines. Specifying an empty colour ("") removes
them again Defaults to "black"
- string dash
- 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.)
- string series
- Name of the data series. This determines the colour of the line and the
symbol (if any) that will be drawn.
- string text
- Text to be drawn next to the line/symbol.
- integer spacing
- 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.
- string series
- 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.
- float x
- X-coordinate of the point that the arrow of the balloon will point
to.
- float y
- Y-coordinate of the point that the arrow of the balloon will point
to.
- string text
- Text to be drawn in the balloon.
- string dir
- 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.
- float x
- X-coordinate of the text position
- float y
- Y-coordinate of the text position
- string text
- Text to be drawn.
- string dir
- 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.
- string itemtype (in)
- Name of a standard canvas item or "circle", "dot" or
"cross"
- string series (in)
- The data series it belongs to, used for setting the default drawing
options
- list args (in)
- List of coordinates and drawing options
- $anyplot deletedata
- Remove the lines, symbols and other graphical object associated with the
actual data from the plot.
Note: Currently implemented for xy-plots only
Note: The existing options for data series and the legend entry are
kept as they were.
Note: Currently there are side effects if the canvas contains more
than one plot.
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.
- string series (in)
- Name of the data series the new point belongs to.
- float xcrd (in)
- 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).
- float ycrd (in)
- 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.
- string series (in)
- Name of the data series the new point belongs to.
- float xlist (in)
- List of X-coordinates for the data series.
- float ycrd (in)
- List of Y-coordinates for the data series.
- int every (in)
- 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.
- string series (in)
- Name of the data series the trend line belongs to.
- float xcrd (in)
- X-coordinate of the new data point
- float ycrd (in)
- 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.
- string series (in)
- Name of the data series the data point belongs to.
- float xcrd (in)
- X-coordinate of the new data point
- float ycrd (in)
- 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.
- string series (in)
- Name of the data series the interval belongs to.
- float xcrd (in)
- X-coordinate of the interval
- float ymin (in)
- Minimum y-coordinate of the interval.
- float ymax (in)
- Maximum y-coordinate of the interval.
- float ycentr (in)
- 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).
- string series (in)
- Name of the data series the box-and-whiskers belongs to.
- float xcrd (in)
- X-coordinate of the box or a list of values.
- float ymin (in)
- 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)
- string series (in)
- Name of the series the vector belongs to. Determines the appearance and
interpretation.
- float xcrd (in)
- X-coordinate of the point where the arrow appears
- float ycrd (in)
- Y-coordinate of the point where the arrow appears
- float ucmp (in)
- X-component or the length of the vector
- float ycentr (in)
- Y-component or the angle of the vector
- $xyplot vectorconfig series -option value
...
- ] Set the vector drawing options for a particular series
- string series (in)
- 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)
- string series (in)
- Name of the series the dot belongs to. Determines size and colour
- float xcrd (in)
- X-coordinate of the point where the arrow appears
- float ycrd (in)
- Y-coordinate of the point where the arrow appears
- float value (in)
- Value determining size and colour
- $xyplot dotconfig series -option value
...
- ] Set the dot drawing options for a particular series
- string series (in)
- 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.
- list xcrd (in)
- List of lists, each value is an x-coordinate for a grid cell corner
- list ycrd (in)
- List of lists, each value is an y-coordinate for a grid cell corner
- list values (in)
- List of lists, each value is the value at a grid cell corner
- list classes (in)
- 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.
- list xcrd (in)
- List of x-coordinates in increasing order.
- list ycrd (in)
- List y-coordinates in increasing order.
- list valuesmat (in)
- List of lists, each value is the value at a grid cell corner. The total
number of values is valuesmat is nx * ny.
- list classes (in)
- 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).
- list colours (in)
- 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.
- list values (in)
- The list of values as used for the actual drawing. This argument is used
only if the list of classes is empty.
- list values (in)
- 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.
- list values (in)
- The list of values as used for the actual drawing. This argument is used
only if the list of classes is empty.
- list values (in)
- 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.
- list xcrd (in)
- List of lists, each value is an x-coordinate for a grid cell corner
- list ycrd (in)
- 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.
- float ymin (in)
- Lower bound for the band
- float ymax (in)
- 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.
- float xmin (in)
- Lower bound for the band
- float xmax (in)
- 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
- float x (in)
- X-coordinate of the symbol to be drawn
- float y (in)
- Y-coordinate of the symbol to be drawn
- string text (in)
- Text for the label
- string orient (in)
- 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.
- string series (in)
- Name of the data series the new point belongs to.
- float radius (in)
- Radial coordinate of the new point.
- float angle (in)
- 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.
- list data (in)
- List of data (the length should correspond to the number of sectors)
- string colour
- 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).
- string function (in)
- 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).
- string function (in)
- 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.
- list contours (in)
- 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.
- int nxcells (in)
- Number of grid cells in x direction. Has to be an integer number greater
than zero.
- int nycells (in)
- Number of grid cells in y direction. Has to be an integer number greater
than zero.
- $plot3d plotdata data
- Plot a matrix of data.
- list data (in)
- 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.
- color fill (in)
- The colour to use for filling the polygons.
- color border (in)
- 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.
- list yzpairs (in)
- 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.
- list yzpairs (in)
- 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.
- string series (in)
- 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.
- list data (in)
- 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.
- color colour1 (in)
- The first colour.
- color colour2 (in)
- 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.
- int segment
- 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
- list data (in)
- A list of data (one for each spoke). The values determine the distance
from the centre of the line connecting the spokes.
- color colour (in)
- The colour for the line.
- int thickness (in)
- An optional argument for the thickness of the line.
- $pie colours colour1 colour2 ...
- Set the colours to be used.
- color colour1 (in)
- The first colour.
- color colour2 (in)
- The second colour, and so on.
For
vertical barcharts:
- $barchart plot series ydata colour ?dir?
?brightness?
- Add a data series to a barchart.
- string series (in)
- Name of the series the values belong to.
- list ydata (in)
- A list of values, one for each x-axis label.
- color colour (in)
- The colour of the bars.
- string dir (in)
- If given, "top-down" or "bottom-up", to indicate the
direction in which the colour changes. (If not given, a uniform colour is
used).
- string brightness (in)
- 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.
- string series (in)
- Name of the series the values belong to.
- list xdata (in)
- A list of values, one for each y-axis label.
- color colour (in)
- The colour of the bars.
- string dir (in)
- If given, "left-right" or "right-left", to indicate
the direction in which the colour changes. (If not given, a uniform colour
is used).
- string brightness (in)
- 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.
- string label (in)
- The label to be shown below the column.
- float yvalue (in)
- The value that determines the height of the column
- color colour (in)
- 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
- list xypairs (in)
- The pairs of x/y values to be drawn (the series is drawn as a whole)
- color colour (in)
- 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.
- list xypairs (in)
- The pairs of x/y values to be drawn (the series is drawn as a whole)
- color colour (in)
- 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).
- string series (in)
- Name of the data series the box belongs to
- string label (in)
- The label along the x- or y-axis to which the data belong
- list values (in)
- 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.
- string text (in)
- The text describing the period.
- string time_begin (in)
- Start time of the period.
- string time_end (in)
- Stop time of the period.
- color colour (in)
- 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.
- string text (in)
- The text describing the milestone.
- string time (in)
- Time at which the milestone must be positioned.
- color colour (in)
- 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.
- string text (in)
- The text appearing at the top (an abbreviation of the date/time for
instance).
- string time (in)
- Time at which the line must be positioned.
- $timechart hscroll scrollbar
- Connect a horizontal scrollbar to the chart. See also the section on
scrolling.
- widget scrollbar (in)
- 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.
- widget scrollbar (in)
- 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.
- string text (in)
- The text describing the task.
- string time_begin (in)
- Start time of the task.
- string time_end (in)
- Stop time of the task.
- float completed (in)
- 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.
- string text (in)
- The text describing the milestone.
- string time (in)
- Time at which the milestone must be positioned.
- color colour (in)
- 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.
- string text (in)
- The text appearing at the top (an abbreviation of the date/time for
instance).
- string time (in)
- Time at which the line must be positioned.
- $ganttchart connect from to
- Add an arrow that connects the from task with the to
task.
- list from (in)
- The list of items returned by the "task" command that represents
the task from which the arrow starts.
- string text (in)
- The text summarising the tasks
- list args (in)
- One or more tasks (the lists returned by the "task" command).
They are shifted down to make room for the summary.
- list to (in)
- 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!
- string text (in)
- The text summarising the tasks
- list args (in)
- 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.
- string keyword (in)
- 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
- string newcolor (in)
- 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.
- string keyword (in)
- 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
- string newfont (in)
- The new font for the chosen items.
- $ganttchart hscroll scrollbar
- Connect a horizontal scrollbar to the chart. See also the section on
scrolling.
- widget scrollbar (in)
- 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.
- widget scrollbar (in)
- 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.
- float x1 (in)
- Minimum x coordinate of the rectangle to be drawn.
- float y1 (in)
- Minimum y coordinate of the rectangle.
- float x2 (in)
- Maximum x coordinate of the rectangle to be drawn.
- float y2 (in)
- Maximum y coordinate of the rectangle.
- color colour (in)
- The colour of the rectangle.
- $isoplot plot filled-rectangle x1 y1 x2
y2 colour
- Plot a rectangle filled with the given colour.
- float x1 (in)
- Minimum x coordinate of the rectangle to be drawn.
- float y1 (in)
- Minimum y coordinate of the rectangle.
- float x2 (in)
- Maximum x coordinate of the rectangle to be drawn.
- float y2 (in)
- Maximum y coordinate of the rectangle.
- color colour (in)
- The colour of the rectangle.
- $isoplot plot circle xc yc radius
colour
- Plot the outline of a circle.
- float xc (in)
- X coordinate of the circle's centre.
- float yc (in)
- Y coordinate of the circle's centre.
- color colour (in)
- The colour of the circle.
- $isoplot plot filled-circle xc yc radius
colour
- Plot a circle filled with the given colour.
- float xc (in)
- X coordinate of the circle's centre.
- float yc (in)
- Y coordinate of the circle's centre.
- color colour (in)
- 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.
- list items (in)
- 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.
- string procname (in)
- 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.
- list args (in)
- 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.
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.
- widget w (in)
- Name of the window (canvas widget) in question.
- float pxmin (in)
- Left-most pixel coordinate.
- float pymin (in)
- Top-most pixel coordinate (remember: the vertical pixel coordinate starts
with 0 at the top!).
- float pxmax (in)
- Right-most pixel coordinate.
- float pymax (in)
- 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).
- widget w (in)
- Name of the window (canvas widget) in question.
- float xmin (in)
- X-coordinate to be mapped to left side of viewport.
- float ymin (in)
- Y-coordinate to be mapped to bottom of viewport.
- float xmax (in)
- X-coordinate to be mapped to right side of viewport.
- float ymax (in)
- 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).
- widget w (in)
- Name of the window (canvas widget) in question.
- float xmin (in)
- X-coordinate to be mapped to front side of the 3D viewport.
- float ymin (in)
- Y-coordinate to be mapped to left side of the viewport.
- float zmin (in)
- Z-coordinate to be mapped to bottom of viewport.
- float xmax (in)
- X-coordinate to be mapped to back side of viewport.
- float ymax (in)
- Y-coordinate to be mapped to right side of viewport.
- float zmax (in)
- 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.
- widget w (in)
- Name of the canvas alias (as returned by [\$anyplot canvas]) in
question.
- float x (in)
- X-coordinate to be mapped.
- float y (in)
- Y-coordinate to be mapped.
- ::Plotchart::coords3DToPixel w x y
z
- Return a list of pixel coordinates valid for the given window.
- widget w (in)
- Name of the canvas alias (as returned by [\$anyplot canvas]) in
question.
- float x (in)
- X-coordinate to be mapped.
- float y (in)
- Y-coordinate to be mapped.
- float y (in)
- 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.
- widget w (in)
- Name of the canvas alias (as returned by [\$anyplot canvas]) in
question.
- float radmax (in)
- 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.
- widget w (in)
- Name of the canvas alias (as returned by [\$anyplot canvas]) in
question.
- float rad (in)
- Radius of the point.
- float phi (in)
- Angle to the positive x-axis.
- ::Plotchart::pixelToCoords w x y
- Return a list of world coordinates valid for the given window.
- widget w (in)
- Name of the canvas alias (as returned by [\$anyplot canvas]) in
question.
- float x (in)
- X-pixel to be mapped.
- float y (in)
- Y-pixel to be mapped.
- ::Plotchart::pixelToIndex w x y
- Return the index of the pie segment containing the pixel coordinates
(x,y)
- widget w (in)
- Name of the canvas alias (as returned by [\$anyplot canvas]) in question,
holding a piechart.
- float x (in)
- X-pixel to be mapped.
- float y (in)
- 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.
- float xmin (in)
- Rough minimum value for the scaling
- float xmax (in)
- Rough maximum value for the scaling.
- boolean inverted (in)
- 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.
- float values (in)
- List of values that will be examined. May contain missing values (empty
strings)
- boolean inverted (in)
- 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:
- •
- For xy-plots, radial plots and strip charts the missing data point causes
a gap in the line through the points.
- •
- For barchats, missing values are treated as if a value of zero was
given.
- •
- For time charts and Gantt charts missing values cause errors - there is no
use for them there.
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:
- •
- Emulate the create subcommand to create all the items in the
correct format
- •
- Emulate the cget subcommand for the options -width and -height to
allow the correct calculation of the rectangle's position and size
- •
- Solve the problem of raising and lowering the items so that
they are properly clipped, for instance by redefining the routine
DrawMask.
- •
- Take care of the currently fixed text size properties
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:
- •
- More robust handling of incorrect calls (right now the procedures may fail
when called incorrectly):
- •
- The axis drawing routines can not handle inverse axes right now.
- •
- If the user provides an invalid date/time string, the routines simply
throw an error.
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.
- string charttype (in)
- 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.
- string component (in)
- 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.
- string property (in)
- 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.
- string value (in)
- 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.
- string subcmd (in)
- 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
- string style (in)
- The name of the plot style to manipulate
- list args (in)
- The new options for the style - see the plotconfig command for
details
Below is a detailed list of the components and properties:
- •
- Axes come in a wide variety:
- •
- leftaxis, rightaxis, topaxis, bottomaxis for the plots with a rectangular
shape.
- •
- xaxis, yaxis and zaxis are used for the 3D plots
- •
- axis, this represents the radial and tangential axes of a polar plot
- All axes have the following properties:
- •
- color - the colour of the line and the tickmarks
- •
- thickness - the width of the line of the axis itself, not the
tickmarks
- •
- ticklength - the length of the tickmarks in pixels. A positive value is
outward, a negative value is inward.
- •
- font - the font for the labels and the text at the axis
- •
- format - the format for rendering the (numerical) labels. For the time
axis it is the format for a date and time.
- •
- textcolor - the colour for the labels and the text.
- •
- labeloffset - space (in pixels) between the tickmark and the actual
label
- •
- minorticks - number of minor tickmarks between the major tickmarks
- •
- shownumbers - show the numbers/labels or not.
- •
- showaxle - show the axis line or not.
- •
- The margin is important for the layout. Currently only the
rectangular plots allow the margins to be set: left, right, top and
bottom. The values are in pixels.
- •
- The text component is meant for any text appearing via the
plaintext subcommand. The properties are: textcolor, font and anchor
(positioning of the text relative to the given coordinates).
- •
- The background has two properties: outercolor, the colour outside
of the actual plot, and innercolor, the colour inside the plot. (Note:
only "outercolor" has now been implemented).
- •
- The mask has one property only: draw. If set to 1, the default,
white rectangles are drawn to mimick the effects of clipping - excess data
are made invisible this way. Otherwise these rectangles are not drawn.
This is useful to control the layout more tightly, for instance with
multiple plots in one canvas.
- •
- The title component has the same properties as the text
component (but it is independent of that component). It also has a
background property: If not set (or set to the empty string) this
is the same as the outercolor property of the background component,
otherwise it is a separate colour.
- •
- The legend has three properties: background, border and position.
See the legend subcommand for the meaning.
- •
- The bar components is used for all barchart-like plots and has
three properties: barwidth (relative width of the bars in relation
to the items along the axis), innermargin (the relative width of
the gaps between bars or groups of bars) and the outline
colour.
- •
- The labels component is used to describe the appearance of the
labels of piecharts and "spiral" piecharts. The properties
are:
- •
- textcolor - colour of the label text
- •
- font - font to be used for the label text
- •
- placement - out of the circle or in the circle
- •
- sorted - the data are sorted in ascending order first
- •
- shownumbers - the labels are combined with the numbers according to the
format
- •
- format - the format to be used (defaults to: "%s (%g)") if the
numbers are to shown. The format command gets the label first, then the
number)
- •
- formatright - if given, the format to be used for labels and numbers
appearing to the right of the pie. The format command gets the number
first, then the label. (Defaults to "")
- •
- The slice component has properties to control the appearance of the
sections in the pie diagram:
- •
- outline - the colour of the line around the slices (default: black)
- •
- outlinewidth - width of the line around the slices (default: 1 pixel)
- •
- startangle - the angle w.r.t. positive x-axis where the first slice
starts
- •
- direction - the direction in which to draw the slices (default: +, that is
clockwise)
- •
- The table charts use the general components title and margin
and further more the specific components header, oddrow,
evenrow, cell and frame:
- •
- header, oddrow and evenrow have the properties:
background, font, color, height and
anchor with obvious meanings.
- •
- The cell component defines in addition leftspace,
rightspace and topspace for fine-grained control of the
spacing inside the cell. These are not set via the cellconfigure
subcommand however.
- •
- Finally the frame component uses color, outerwidth
(for the width of the line surrounding the whole table) and
innerwidth (for the width of lines separating columns and
rows).
See the examples in plotdemos7.tcl for its use.
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:
- •
- You add an item with a period wider than the current one.
- •
- You add a vertical line for a time beyond the current bounds.
- •
- You add an extra item beyond the number that was used to create the
chart.
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:
- •
- Target diagrams are used to assess the capacity of numerical models to
reproduce measurement data. They are described in detail in:
Jason K. Joliff et al.
Summary diagrams for coupled hydrodynamic-ecosystem model skill assessment
Journal of Marine Systems 76 (2009) 64-82
DOI: 10.1016/j.jmarsys.2008.05.014
- •
- Performance profiles are used for comparing the performance of numerical
methods or implementations thereof with each other. For more
information:
Desmond Higham and Nicholas Higham
Matlab Guide
SIAM, 2005, Philadephia
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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- list limits (in)
- List of radii for the circles that represent the limits (for instance: 0.5
and 0.7)
- double scale (in)
- 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.
- string series (in)
- 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)
- list xvalues (in)
- List of model results (missing values are represented as empty
strings)
- list yvalues (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the plot.
- float max (in)
- 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.
- list series_and_data_pairs (in)
- 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).
- string charttype (in)
- The type of plot or chart that the new method should be added to.
- string methodname (in)
- Name of the method to be used.
- string plotproc (in)
- 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.
- widget w (in)
- The name of the canvas widget to copy the plots/charts into
- string dir (in)
- The direction of the arrangement - top, left, bottom or right
- list args (in)
- 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:
- •
- X-coordinate of the upper-left corner of the area that will contain the
plot or chart (simply a canvas coordinate)
- •
- Y-coordinate of the upper-left corner
- •
- Width of the area
- •
- Height of the area
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:
- •
- Identification of the plot with respect to which it should be positioned
(the command returned by the creation command).
- •
- The anchor position that should be used (n, nw, ...)
- •
- X-coordinate of the upper-left corner of the area that will contain the
plot or chart. This coordinates is taken relative to the anchor
position
- •
- Y-coordinate of the upper-left corner
- •
- Width of the axis area
- •
- Height of the axis area
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):
- •
- The legend can be moved around by pressing mouse button 1 in the legend's
box and keeping it down.
- •
- You can use the bindplot and bindlast commands to define
actions that are to be taken when the user clicks on an element of the
plot or chart. (see below, see also the sample code in
plotdemos12.tcl)
- •
- Piecharts can show an "exploded" segment that you can
select with mouse button 1.
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.
- string event
- The event that you want to bind the command to
- string command
- 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).
- string event
- The event that you want to bind the command to
- list command
- 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]
}
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:
- •
- mask - Used to manipulate the opaque rectangles that ensure data
outside the viewport are not shown.
- •
- topmask, horizmask, vertmask - specialised tags, used for
scrollable plots.
- •
- title - Used for title strings.
- •
- BalloonText, BalloonFrame - Used to manipulate balloon text.
- •
- PlainText - Used to manipulate ordinary text without any
decoration.
- •
- background - Tag used for gradient and image backgrounds (and for
gradient-filled bars).
- •
- xaxis, yaxis - Tags used for all objects related to horizontal or
vertical axes. (also: both for numerical axes and axes with labels as in
barcharts). Note, however, that the text along the axes has no
particular tag.
- •
- raxis - Tag used for all objects related to a right
axis.
- •
- taxis - Tag used for all objects related to a time
axis.
- •
- axis3d - Tag used for 3D axes
- •
- xtickline, ytickline - Tags used for ticklines.
- •
- legend, legengb, legendobj - Tags used for the legend. The latter
is used to manipulate the legend as a whole.
- •
- legend_series - Tag used to control the appearance of the legend
entry ("series" should be replaced by the series name).
- •
- object - used as standard tag for all objects drawn with the
::Plotchart::drawobject procedure. Tags given at object creation
time are added to this tag.
XY-plots (all types of axes):
- •
- data - The general tag to identify graphical objects associated
with data. data_seriesname - The tag specific to a data series
("seriesname" should be replaced). band - The horizontal
or vertical band drawn with the xband otr yband subcommands have this tag
by the actual name). xtext - The text labelling the xaxis.
ytext - The text labelling hte yaxis horizontically. vtext -
The text labelling the yaxis vertically.
Items such as labelled dots only have the "data" tag.
Piecharts and spiral pies:
- •
- segment_segmentnumber - The tag identifying the segment, the string
"segmentnumber" should be replaced by the actual number. This
tag is used to explode the segments.
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:
- •
- Isometric plots - allow new items to be implemented easily.
- •
- A general 3D viewer - emphasis on geometry, not a ray-tracer.
- •
- Several improvements for boxplots:
- •
- Height of the box scales with the logarithm of the number of points
- •
- Marker line to indicate a "current" value
- •
- Box drawn from quantiles
KEYWORDS¶
3D bars, 3D surfaces, bar charts, charts, coordinate transformations,
coordinates, graphical presentation, isometric plots, pie charts, plotting,
polar plots, strip charts, tables, time charts, xy-plots
COPYRIGHT¶
Copyright (c) 2011 Arjen Markus <arjenmarkus@users.sourceforge.net>