|
|
This manual page is for Mac OS X version 10.6.3If you are running a different version of Mac OS X, view the documentation locally:
Reading manual pagesManual pages are intended as a quick reference for people who already understand a technology.
|
Plotchart(n) Plotchart Plotchart(n)
____________________________________________________________________________________________________________
NAME
Plotchart - Simple plotting and charting package
SYNOPSIS
package require Tcl ?8.4?
package require Tk ?8.4?
package require Plotchart ?1.5?
::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 xlabels yaxis noseries
::Plotchart::create3DBarchart w yaxis nobars
::Plotchart::create3DRibbonChart w names yaxis zaxis
::Plotchart::createTimechart w time_begin time_end noitems
::Plotchart::createGanttchart w time_begin time_end noitems ?text_width?
::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 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
$timechart period text time_begin time_end colour
$timechart milestone text time colour
$timechart vertline text time
$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
$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 com-pletely completely
pletely 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 step-size stepsize
size (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: maxi-mum, maximum,
mum, 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 xlabels yaxis 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. Oth-erwise Otherwise
erwise 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 yaxis (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 hori-zontally!), horizontally!),
zontally!), in this order.
list zaxis (in)
A 3-element list containing minimum, maximum and stepsize for the z-axis (drawn verti-cally), vertically),
cally), in this order.
int nobars (in)
The number of bars that will be plotted.
::Plotchart::createTimechart w time_begin time_end noitems
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 jan-uary january
uary 2004").
int noitems (in)
Expected/maximum number of items. This determines the vertical spacing.
::Plotchart::createGanttchart w time_begin time_end noitems ?text_width?
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 jan-uary january
uary 2004").
int noitems (in)
Expected/maximum number of items. This determines the vertical spacing.
int text_width
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.
::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 com-mand: command:
mand:
$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 success-fully successfully
fully grab it, it is raised first. On some systems, for instance Linux with KDE, rais-ing raising
ing 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 bot-tom-right. bottom-right.
tom-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, xaxis,
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 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 auto-matically. automatically.
matically.
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 grid-size gridsize
size 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 tri-angles). triangles).
angles).
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 cir-cle circle
cle 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 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.
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.
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.
COORDINATE TRANSFORMATIONS
Besides the commands that deal with the plots and charts directly, there are a number of commands
that can be used to convert world coordinates to pixels and vice versa. These include:
::Plotchart::viewPort w pxmin pymin pxmax pymax
Set the viewport for window w. Should be used in cooperation with ::Plotchart::worldCoordi-nates. ::Plotchart::worldCoordinates.
nates.
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, max-imum maximum
imum 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.
OTHER OUTPUT FORMATS
Besides output to the canvas on screen, the module is capable, via canvas postscript, of producing
PostScript files. One may wonder whether it is possible to extend this set of output formats and the
answer is "yes". This section tries to sum up the aspects of using this module for another sort of
output.
One way you can create output files in a different format, is by examining the contents of the canvas
after everything has been drawn and render that contents in the right form. This is probably the eas-iest easiest
iest 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 sub-commands subcommands
commands 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 rou-tine routine
tine 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 pix-els pixels
els 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 calcula-tion calculation
tion 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 incor-rectly): incorrectly):
rectly):
• 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.
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 par-ticular particular
ticular 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 neg-ative negative
ative 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 proper-ties properties
ties are: textcolor, font and anchor (positioning of the text relative to the given coordi-nates). coordinates).
nates).
• 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.
ARRANGING MULTIPLE PLOTS IN A CANVAS
The command plotpack allows you to copy the contents of a plot into another canvas widget. This can-vas canvas
vas 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
TODO - SOME PRIVATE NOTES
I have the following wishlist:
• Isometric plots - allow new items to be implemented easily.
• Add support for histograms where the independent axis is numerical.
• A general 3D viewer - emphasis on geometry, not a ray-tracer.
KEYWORDS
3D bars, 3D surfaces, bar charts, charts, coordinate transformations, coordinates, graphical presen-tation, presentation,
tation, isometric plots, pie charts, plotting, polar plots, strip charts, time charts, xy-plots
COPYRIGHT
Copyright (c) 2007 Arjen Markus <arjenmarkus@users.sourceforge.net>
plotchart 1.5 Plotchart(n)
|
The way to report a problem with this manual page depends on the type of problem: