NAME¶
Plotchart - Simple plotting and charting package
SYNOPSIS¶
package require
Tcl ?8.4?
package require
Tk ?8.4?
package require
Plotchart ?1.6?
::Plotchart::createXYPlot w xaxis yaxis
::Plotchart::createStripchart w xaxis yaxis
::Plotchart::createTXPlot w timeaxis xaxis
::Plotchart::createXLogYPlot w xaxis yaxis
::Plotchart::createPolarPlot w radius_data
::Plotchart::createIsometricPlot w xaxis yaxis
stepsize
::Plotchart::createHistogram w xaxis yaxis
::Plotchart::create3DPlot w xaxis yaxis zaxis
::Plotchart::createPiechart w
::Plotchart::createRadialchart w names scale
style
::Plotchart::createBarchart w xlabels yaxis
noseries
::Plotchart::createHorizontalBarchart w ylabels
xaxis noseries
::Plotchart::create3DBarchart w yaxis nobars
::Plotchart::create3DRibbonChart w names yaxis
zaxis
::Plotchart::createBoxplot w xaxis ylabels
::Plotchart::createTimechart w time_begin time_end
args
::Plotchart::createGanttchart w time_begin time_end
args
::Plotchart::createRightAxis w yaxis
$anyplot title
text
$anyplot saveplot
filename args
$anyplot xtext
text
$anyplot ytext
text
$anyplot xconfig
-option value ...
$anyplot yconfig
-option value ...
$anyplot background
part colour_or_image dir
$anyplot xticklines
colour
$anyplot yticklines
colour
$anyplot legendconfig
-option value ...
$anyplot legend
series text
$anyplot balloon
x y text dir
$anyplot balloonconfig
args
$xyplot plot
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 contourfill
xcrd ycrd values ?classes?
$xyplot contourbox
xcrd ycrd values ?classes?
$xyplot colorMap
colours
$xyplot grid
xcrd ycrd
$polarplot plot
series radius angle
$plot3d plotfunc
function
$plot3d plotfuncont
function contours
$plot3d gridsize
nxcells nycells
$plot3d plotdata
data
$plot3d colours
fill border
$xyplot dataconfig
series -option value ...
$pie plot
data
$pie colours
colour1 colour2 ...
$radial plot
data colour thickness
$pie colours
colour1 colour2 ...
$barchart plot
series ydata colour
$barchart plot
series xdata colour
$barchart plot
label yvalue colour
$barchart config
-option value ...
$ribbon line
xypairs colour
$ribbon area
xypairs colour
$boxplot plot
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
::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::plotconfig charttype component property
value
::Plotchart::plotpack w dir args
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)
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
- 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.
- ::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::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::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::createPiechart w
- Create a new piechart (configuration type: piechart).
- 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.
- float 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
ylabels xaxis 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 ylabels (in)
- List of labels for the y-axis. Its length also determines
the number of bars that will be plotted per series.
- list xaxis (in)
- A 3-element list containing minimum, maximum and stepsize
for the x-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::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 xaxis
ylabels
- Create a new boxplot with horizontal boxes
(box-and-whiskers). The 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 xaxis (in)
- A 3-element list containing minimum, maximum and stepsize
for the y-axis, in this order.
- list ylabels (in)
- List of labels for the y-axis. Its length also determines
the number of boxes that can be plotted. The labels are also used in the
plot subcommand.
- ::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
yaxis
- Create a plot command that will use a right axis instead of
the left axis (configuration type: inherited from the existing plot). The
widget (w) must already contain an ordinary plot, as the horizontal axis
and other properties are reused. To plot data using the right axis, use
this new command, to plot data using the left axis, use the
original plot command.
- 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.
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
- Specify the title of the whole chart.
- string text (in)
- The text of the title to be drawn.
- $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)
- 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 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
- 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.
- $anyplot xticklines colour
- Draw vertical ticklines at each tick location
- string colour
- Colour of the lines. Specifying an empty colour
("") removes them again. Defaults to "black"
- $anyplot yticklines colour
- Draw horizontal ticklines at each tick location
- string colour
- Colour of the lines. Specifying an empty colour
("") removes them again Defaults to "black"
- $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 white).
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.
- 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 legend series text
- 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.
- $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)
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.
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. 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
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 (default: 10 pixels) determines the width (or height)
of the box.
- 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.
- $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.
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 (they give the x- and
y-coordinates of the grid cell corners). The 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.
- 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.
- $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).
- $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.
- $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 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
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
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.
For
xy plots,
stripcharts 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).
- 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.
For
piecharts:
- $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.
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
- 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.
For
horizontal barcharts:
- $barchart plot series xdata
colour
- 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.
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 label values
- Add a box-and-whisker to the plot.
- string label (in)
- The label along the 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.
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 window (canvas widget) 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 window (canvas widget) 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 window (canvas widget) 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 window (canvas widget) 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 window (canvas widget) 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 window (canvas widget) 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)
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 will have that.
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 command plotconfig 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. Each argument is
optional.
- 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.
Below is a more 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.
- •
- 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 legend has three properties: background, border
and position. See the legend subcommand for the meaning.
See the examples in plotdemos7.tcl for it 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.
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
P.M.
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, time charts, xy-plots
COPYRIGHT¶
Copyright (c) 2007 Arjen Markus <arjenmarkus@users.sourceforge.net>