1Plotchart(n) Plotchart Plotchart(n)
2______________________________________________________________________________
6
8 Plotchart - Simple plotting and charting package
9
11 package require Tcl ?8.4?
12 package require Tk ?8.4?
14 package require Plotchart ?1.6?
16 ::Plotchart::createXYPlot w xaxis yaxis
18 ::Plotchart::createStripchart w xaxis yaxis
20 ::Plotchart::createTXPlot w timeaxis xaxis
22 ::Plotchart::createXLogYPlot w xaxis yaxis
24 ::Plotchart::createPolarPlot w radius_data
26 ::Plotchart::createIsometricPlot w xaxis yaxis stepsize
28 ::Plotchart::createHistogram w xaxis yaxis
30 ::Plotchart::create3DPlot w xaxis yaxis zaxis
32 ::Plotchart::createPiechart w
34 ::Plotchart::createRadialchart w names scale style
36 ::Plotchart::createBarchart w xlabels yaxis noseries
38 ::Plotchart::createHorizontalBarchart w ylabels xaxis noseries
40 ::Plotchart::create3DBarchart w yaxis nobars
42 ::Plotchart::create3DRibbonChart w names yaxis zaxis
44 ::Plotchart::createBoxplot w xaxis ylabels
46 ::Plotchart::createTimechart w time_begin time_end args
48 ::Plotchart::createGanttchart w time_begin time_end args
50 ::Plotchart::createRightAxis w yaxis
52 $anyplot title text
54 $anyplot saveplot filename args
56 $anyplot xtext text
58 $anyplot ytext text
60 $anyplot xconfig -option value ...
62 $anyplot yconfig -option value ...
64 $anyplot background part colour_or_image dir
66 $anyplot xticklines colour
68 $anyplot yticklines colour
70 $anyplot legendconfig -option value ...
72 $anyplot legend series text
74 $anyplot balloon x y text dir
76 $anyplot balloonconfig args
78 $xyplot plot series xcrd ycrd
80 $xyplot trend series xcrd ycrd
82 $xyplot rchart series xcrd ycrd
84 $xyplot interval series xcrd ymin ymax ?ycentr?
86 $xyplot box-and-whiskers series xcrd ycrd
88 $xyplot vector series xcrd ycrd ucmp vcmp
90 $xyplot vectorconfig series -option value ...
92 $xyplot dot series xcrd ycrd value
94 $xyplot dotconfig series -option value ...
96 $xyplot contourlines xcrd ycrd values ?classes?
98 $xyplot contourfill xcrd ycrd values ?classes?
100 $xyplot contourbox xcrd ycrd values ?classes?
102 $xyplot colorMap colours
104 $xyplot grid xcrd ycrd
106 $polarplot plot series radius angle
108 $plot3d plotfunc function
110 $plot3d plotfuncont function contours
112 $plot3d gridsize nxcells nycells
114 $plot3d plotdata data
116 $plot3d colours fill border
118 $xyplot dataconfig series -option value ...
120 $pie plot data
122 $pie colours colour1 colour2 ...
124 $radial plot data colour thickness
126 $pie colours colour1 colour2 ...
128 $barchart plot series ydata colour
130 $barchart plot series xdata colour
132 $barchart plot label yvalue colour
134 $barchart config -option value ...
136 $ribbon line xypairs colour
138 $ribbon area xypairs colour
140 $boxplot plot label values
142 $timechart period text time_begin time_end colour
144 $timechart milestone text time colour
146 $timechart vertline text time
148 $timechart hscroll scrollbar
150 $timechart vscroll scrollbar
152 $ganttchart task text time_begin time_end completed
154 $ganttchart milestone text time colour
156 $ganttchart vertline text time
158 $ganttchart connect from to
160 $ganttchart summary text args
162 $ganttchart color keyword newcolor
164 $ganttchart font keyword newfont
166 $ganttchart hscroll scrollbar
168 $ganttchart vscroll scrollbar
170 $isoplot plot rectangle x1 y1 x2 y2 colour
172 $isoplot plot filled-rectangle x1 y1 x2 y2 colour
174 $isoplot plot circle xc yc radius colour
176 $isoplot plot filled-circle xc yc radius colour
178 ::Plotchart::viewPort w pxmin pymin pxmax pymax
180 ::Plotchart::worldCoordinates w xmin ymin xmax ymax
182 ::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
184 ::Plotchart::coordsToPixel w x y
186 ::Plotchart::coords3DToPixel w x y z
188 ::Plotchart::polarCoordinates w radmax
190 ::Plotchart::polarToPixel w rad phi
192 ::Plotchart::pixelToCoords w x y
194 ::Plotchart::pixelToIndex w x y
196 ::Plotchart::determineScale xmin xmax inverted
198 ::Plotchart::plotconfig charttype component property value
200 ::Plotchart::plotpack w dir args
202______________________________________________________________________________
204
206 Plotchart is a Tcl-only package that focuses on the easy creation of
207 xy-plots, barcharts and other common types of graphical presentations.
208 The emphasis is on ease of use, rather than flexibility. The procedures
209 that create a plot use the entire canvas window, making the layout of
210 the plot completely automatic.
211 This results in the creation of an xy-plot in, say, ten lines of code:
213 package require Plotchart
215 canvas .c -background white -width 400 -height 200
217 pack .c -fill both
218 #
220 # Create the plot with its x- and y-axes
221 #
222 set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]
223 foreach {x y} {0.0 32.0 10.0 50.0 25.0 60.0 78.0 11.0 } {
225 $s plot series1 $x $y
226 }
227 $s title "Data series"
229 A drawback of the package might be that it does not do any data manage‐
232 ment. So if the canvas that holds the plot is to be resized, the whole
233 plot must be redrawn. The advantage, though, is that it offers a num‐
234 ber of plot and chart types:
235 · XY-plots like the one shown above with any number of data
237 series.
238 · Stripcharts, a kind of XY-plots where the horizontal axis is
240 adjusted automatically. The result is a kind of sliding window
241 on the data series.
242 · Polar plots, where the coordinates are polar instead of carte‐
244 sian.
245 · Histograms, for plotting statistical information.
247 · Isometric plots, where the scale of the coordinates in the two
249 directions is always the same, i.e. a circle in world coordi‐
250 nates appears as a circle on the screen.
251 You can zoom in and out, as well as pan with these plots (Note:
253 this works best if no axes are drawn, the zooming and panning
254 routines do not distinguish the axes), using the mouse buttons
255 with the control key and the arrow keys with the control key.
256 · Piecharts, with automatic scaling to indicate the proportions.
258 · Barcharts, with either vertical or horizontal bars, stacked bars
260 or bars side by side.
261 · Timecharts, where bars indicate a time period and milestones or
263 other important moments in time are represented by triangles.
264 · 3D plots (both for displaying surfaces and 3D bars)
266 With version 1.5 a new command has been introduced: plotconfig, which
268 can be used to configure the plot options for particular types of plots
269 and charts (cf. CONFIGURATION OPTIONS)
270
272 You create the plot or chart with one single command and then fill the
273 plot with data:
274 ::Plotchart::createXYPlot w xaxis yaxis
276 Create a new xy-plot (configuration type: xyplot).
277 widget w (in)
279 Name of the existing canvas widget to hold the plot.
280 list xaxis (in)
282 A 3-element list containing minimum, maximum and stepsize
283 for the x-axis, in this order. For an inverted axis,
284 where the maximum appears on the left-hand side, use:
285 maximum, minimum and a negative stepsize.
286 list yaxis (in)
288 A 3-element list containing minimum, maximum and stepsize
289 for the y-axis, in this order. For an inverted axis,
290 where the maximum appears at the bottom, use: maximum,
291 minimum and a negative stepsize.
292 ::Plotchart::createStripchart w xaxis yaxis
295 Create a new strip chart (configuration type: stripchart). The
296 only difference to a regular XY plot is that the x-axis will be
297 automatically adjusted when the x-coordinate of a new point
298 exceeds the maximum.
299 widget w (in)
301 Name of the existing canvas widget to hold the plot.
302 list xaxis (in)
304 A 3-element list containing minimum, maximum and stepsize
305 for the x-axis, in this order. Note that an inverted x-
306 axis is not supported for this type of plot.
307 list yaxis (in)
309 A 3-element list containing minimum, maximum and stepsize
310 for the y-axis, in this order. For an inverted axis,
311 where the maximum appears at the bottom, use: maximum,
312 minimum and a negative stepsize.
313 ::Plotchart::createTXPlot w timeaxis xaxis
316 Create a new time-x-plot (configuration type: txplot). The hori‐
317 zontal axis represents the date/time of the data and the verti‐
318 cal axis the values themselves.
319 widget w (in)
321 Name of the existing canvas widget to hold the plot.
322 list timeaxis (in)
324 A 3-element list containing the minimum and maximum
325 date/time to be shown and the stepsize (in days) for the
326 time-axis, in this order. Note that an inverted time-
327 axis is not supported.
328 list xaxis (in)
330 A 3-element list containing minimum, maximum and stepsize
331 for the vertical axis, in this order. For an inverted
332 axis, where the maximum appears at the bottom, use: maxi‐
333 mum, minimum and a negative stepsize.
334 ::Plotchart::createXLogYPlot w xaxis yaxis
337 Create a new xy-plot where the y-axis has a logarithmic scale
338 (configuration type: xlogyplot).
339 The data should be given as for a linear scale, as the logarith‐
341 mic transformation is taken of internally.
342 widget w (in)
344 Name of the existing canvas widget to hold the plot.
345 list xaxis (in)
347 A 3-element list containing minimum, maximum and stepsize
348 for the x-axis, in this order. For an inverted axis,
349 where the maximum appears on the left-hand side, use:
350 maximum, minimum and a negative stepsize.
351 list yaxis (in)
353 A 2-element list containing minimum and maximum for the
354 y-axis, in this order. Note that an inverted logarithmic
355 axis is not supported.
356 ::Plotchart::createPolarPlot w radius_data
359 Create a new polar plot (configuration type: polarplot).
360 widget w (in)
362 Name of the existing canvas widget to hold the plot.
363 list radius_data (in)
365 A 2-element list containing maximum radius and stepsize
366 for the radial axis, in this order.
367 ::Plotchart::createIsometricPlot w xaxis yaxis stepsize
370 Create a new isometric plot, where the vertical and the horizon‐
371 tal coordinates are scaled so that a circle will truly appear as
372 a circle (configuration type: isometric).
373 widget w (in)
375 Name of the existing canvas widget to hold the plot.
376 list xaxis (in)
378 A 2-element list containing minimum, and maximum for the
379 x-axis, in this order.
380 list yaxis (in)
382 A 2-element list containing minimum, and maximum for the
383 y-axis, in this order.
384 float|noaxes stepsize (in)
386 Either the stepsize used by both axes or the keyword
387 noaxes to signal the plot that it should use the full
388 area of the widget, to not draw any of the axes.
389 ::Plotchart::createHistogram w xaxis yaxis
392 Create a new histogram (configuration type: histogram).
393 widget w (in)
395 Name of the existing canvas widget to hold the plot.
396 list xaxis (in)
398 A 3-element list containing minimum, maximum and stepsize
399 for the x-axis, in this order.
400 list yaxis (in)
402 A 3-element list containing minimum, maximum and stepsize
403 for the y-axis, in this order.
404 ::Plotchart::create3DPlot w xaxis yaxis zaxis
407 Create a new 3D plot.
408 widget w (in)
410 Name of the existing canvas widget to hold the plot.
411 list xaxis (in)
413 A 3-element list containing minimum, maximum and stepsize
414 for the x-axis, in this order.
415 list yaxis (in)
417 A 3-element list containing minimum, maximum and stepsize
418 for the y-axis, in this order.
419 list zaxis (in)
421 A 3-element list containing minimum, maximum and stepsize
422 for the z-axis, in this order.
423 ::Plotchart::createPiechart w
426 Create a new piechart (configuration type: piechart).
427 widget w (in)
429 Name of the existing canvas widget to hold the plot.
430 ::Plotchart::createRadialchart w names scale style
433 Create a new radial chart (the data are drawn as a line connect‐
434 ing the spokes of the diagram) (configuration type: radi‐
435 alchart).
436 widget w (in)
438 Name of the existing canvas widget to hold the plot.
439 list names (in)
441 Names for the spokes.
442 float scale (in)
444 Scale value to determine the position of the data along
445 the spokes.
446 float style (in)
448 Style of the chart (optional). One of:
449 · lines - the default: draw the data as independent
451 polylines.
452 · cumulative - draw the data as polylines where the
454 data are accumulated.
455 · filled - draw the data as filled polygons where
457 the data are accumulated
458 ::Plotchart::createBarchart w xlabels yaxis noseries
461 Create a new barchart with vertical bars (configuration type:
462 vertbars). The horizontal axis will display the labels contained
463 in the argument xlabels. The number of series given by noseries
464 determines both the width of the bars, and the way the series
465 will be drawn.
466 If the keyword stacked was specified the series will be drawn
468 stacked on top of each other. Otherwise each series that is
469 drawn will be drawn shifted to the right.
470 The number of series determines the width of the bars, so that
472 there is space of that number of bars. If you use a floating-
473 point number, like 2.2, instead of an integer, like 2, a small
474 gap between the sets of bars will be drawn - the width depends
475 on the fractional part.
476 widget w (in)
478 Name of the existing canvas widget to hold the plot.
479 list xlabels (in)
481 List of labels for the x-axis. Its length also determines
482 the number of bars that will be plotted per series.
483 list yaxis (in)
485 A 3-element list containing minimum, maximum and stepsize
486 for the y-axis, in this order.
487 int|stacked noseries (in)
489 The number of data series that will be plotted. This has
490 to be an integer number greater than zero (if stacked is
491 not used).
492 ::Plotchart::createHorizontalBarchart w ylabels xaxis noseries
495 Create a new barchart with horizontal bars (configuration type:
496 horizbars). The vertical axis will display the labels contained
497 in the argument ylabels. The number of series given by noseries
498 determines both the width of the bars, and the way the series
499 will be drawn.
500 If the keyword stacked was specified the series will be drawn
502 stacked from left to right. Otherwise each series that is drawn
503 will be drawn shifted upward.
504 widget w (in)
506 Name of the existing canvas widget to hold the plot.
507 list ylabels (in)
509 List of labels for the y-axis. Its length also determines
510 the number of bars that will be plotted per series.
511 list xaxis (in)
513 A 3-element list containing minimum, maximum and stepsize
514 for the x-axis, in this order.
515 int|stacked noseries (in)
517 The number of data series that will be plotted. This has
518 to be an integer number greater than zero (if stacked is
519 not used).
520 ::Plotchart::create3DBarchart w yaxis nobars
523 Create a new barchart with 3D vertical bars (configuration type:
524 3dbars). The horizontal axis will display the labels per bar.
525 The number of bars given by nobars determines the position and
526 the width of the bars. The colours can be varied per bar. (This
527 type of chart was inspired by the Wiki page on 3D bars by
528 Richard Suchenwirth.)
529 widget w (in)
531 Name of the existing canvas widget to hold the plot.
532 list yaxis (in)
534 A 3-element list containing minimum, maximum and stepsize
535 for the y-axis, in this order.
536 int nobars (in)
538 The number of bars that will be plotted.
539 ::Plotchart::create3DRibbonChart w names yaxis zaxis
542 Create a new "ribbon chart" (configuration type: 3dribbon). This
543 is a chart where the data series are represented as ribbons in a
544 three-dimensional axis system. Along the x-axis (which is "into"
545 the screen) the names are plotted, each representing a single
546 series. The first plot command draws the furthest series, the
547 second draws the series in front of that and so on.
548 widget w (in)
550 Name of the existing canvas widget to hold the plot.
551 widget w (in)
553 Names of the series, plotted as labels along the x-axis
554 list yaxis (in)
556 A 3-element list containing minimum, maximum and stepsize
557 for the y-axis (drawn horizontally!), in this order.
558 list zaxis (in)
560 A 3-element list containing minimum, maximum and stepsize
561 for the z-axis (drawn vertically), in this order.
562 int nobars (in)
564 The number of bars that will be plotted.
565 ::Plotchart::createBoxplot w xaxis ylabels
568 Create a new boxplot with horizontal boxes (box-and-whiskers).
569 The y-axis is drawn with labels. The boxes are drawn based on
570 the raw data (see the plot subcommand for this type of plot).
571 widget w (in)
573 Name of the existing canvas widget to hold the plot.
574 list xaxis (in)
576 A 3-element list containing minimum, maximum and stepsize
577 for the y-axis, in this order.
578 list ylabels (in)
580 List of labels for the y-axis. Its length also determines
581 the number of boxes that can be plotted. The labels are
582 also used in the plot subcommand.
583 ::Plotchart::createTimechart w time_begin time_end args
586 Create a new timechart (configuration type: timechart). The
587 time axis (= x-axis) goes from time_begin to time_end, and the
588 vertical spacing is determined by the number of items to plot.
589 widget w (in)
591 Name of the existing canvas widget to hold the plot.
592 string time_begin (in)
594 The start time given in a form that is recognised by the
595 clock scan command (e.g. "1 january 2004").
596 string time_end (in)
598 The end time given in a form that is recognised by the
599 clock scan command (e.g. "1 january 2004").
600 arguments args (in)
602 The remaining arguments can be:
603 · The expected/maximum number of items. This deter‐
605 mines the vertical spacing. (If given, it must be
606 the first argument after "time_end"
607 · The keyword -barheight and the number of pixels
609 per bar. This is an alternative method to deter‐
610 mine the vertical spacing.
611 · The keyword -ylabelwidth and the number of pixels
613 to reserve for the labels at the y-axis.
614 ::Plotchart::createGanttchart w time_begin time_end args
616 Create a new Gantt chart (configuration type: ganttchart). The
617 time axis (= x-axis) goes from time_begin to time_end, and the
618 vertical spacing is determined by the number of items to plot.
619 Via the specific commands you can then add tasks and connections
620 between the tasks.
621 widget w (in)
623 Name of the existing canvas widget to hold the plot.
624 string time_begin (in)
626 The start time given in a form that is recognised by the
627 clock scan command (e.g. "1 january 2004").
628 string time_end (in)
630 The end time given in a form that is recognised by the
631 clock scan command (e.g. "1 january 2004").
632 arguments args (in)
634 The remaining arguments can be:
635 · The expected/maximum number of items. This deter‐
637 mines the vertical spacing. (If given this way, it
638 must be the first argument after "time_end")
639 · The expected/maximum width of the descriptive text
641 (roughly in characters, for the actual space
642 reserved for the text, it is assumed that a char‐
643 acter is about ten pixels wide). Defaults to 20.
644 (If given this way, it must be the second argument
645 after "time_end").
646 · The keyword -barheight and the number of pixels
648 per bar. This is an alternative method to deter‐
649 mine the vertical spacing.
650 · The keyword -ylabelwidth and the number of pixels
652 to reserve for the labels at the y-axis.
653 ::Plotchart::createRightAxis w yaxis
655 Create a plot command that will use a right axis instead of the
656 left axis (configuration type: inherited from the existing
657 plot). The widget (w) must already contain an ordinary plot, as
658 the horizontal axis and other properties are reused. To plot
659 data using the right axis, use this new command, to plot data
660 using the left axis, use the original plot command.
661 widget w (in)
663 Name of the existing canvas widget to hold the plot.
664 list yaxis (in)
666 A 3-element list containing minimum, maximum and stepsize
667 for the y-axis, in this order.
668
671 Each of the creation commands explained in the last section returns the
672 name of a new object command that can be used to manipulate the plot or
673 chart. The subcommands available to a chart command depend on the type
674 of the chart.
675 General subcommands for all types of charts. $anyplot is the command
677 returned by the creation command:
678 $anyplot title text
680 Specify the title of the whole chart.
681 string text (in)
683 The text of the title to be drawn.
684 $anyplot saveplot filename args
687 Draws the plot into a file, using PostScript.
688 string filename (in)
690 Contain the path name of the file to write the plot to.
691 list args (in)
693 Optionally you can specify the option -format "some pic‐
694 ture format" to store the plot in a different file than a
695 PostScript file. This, however, relies on the Img package
696 to do the actual job.
697 Note: Because the window holding the plot must be fully
699 visible before Img can successfully grab it, it is raised
700 first. On some systems, for instance Linux with KDE,
701 raising a window is not done automatically, but instead
702 you need to click on the window in the task bar. Similar
703 things happen on Windows XP.
704 There seems to be something wrong under some circum‐
706 stances, so instead of waiting for the visibility of the
707 window, the procedure simply waits two seconds. It is not
708 ideal, but it seems to work better.
709 $anyplot xtext text
712 Specify the title of the (horizontal) x-axis, for those plots
713 that have a straight x-axis.
714 string text (in)
716 The text of the x-axis label to be drawn.
717 $anyplot ytext text
720 Specify the title of the (horizontal) y-axis, for those plots
721 that have a straight y-axis.
722 string text (in)
724 The text of the y-axis label to be drawn.
725 $anyplot xconfig -option value ...
728 Set one or more configuration parameters for the x-axis. The
729 following options are supported:
730 format fmt
732 The format for the numbers along the axis.
733 ticklength length
735 The length of the tickmarks (in pixels).
736 ticklines boolean
738 Whether to draw ticklines (true) or not (false).
739 scale scale_data
741 New scale data for the axis, i.e. a 3-element list con‐
742 taining minimum, maximum and stepsize for the axis, in
743 this order.
744 Beware: Setting this option will clear all data from the
746 plot.
747 $anyplot yconfig -option value ...
750 Set one or more configuration parameters for the y-axis. This
751 method accepts the same options and values as the method xcon‐
752 fig.
753 $anyplot background part colour_or_image dir
755 Set the background of a part of the plot
756 string part
758 Which part of the plot: "axes" for the axes area and
759 "plot" for the inner part. The interpretation depends on
760 the type of plot. Two further possibilities are:
761 · image, in which case a predefined image is loaded
763 into the background of the plot.
764 · gradient, in which case the background is coloured
766 in different shades of the given colour. The "dir"
767 argument specifies the direction in which the
768 colour gets whiter.
769 string colour_or_image
771 Colour for that part or the name of the image if "part"
772 is "image"
773 string dir
775 The direction of the gradient. One of: top-down, bottom-
776 up, left-right or right-left.
777 $anyplot xticklines colour
780 Draw vertical ticklines at each tick location
781 string colour
783 Colour of the lines. Specifying an empty colour ("")
784 removes them again. Defaults to "black"
785 $anyplot yticklines colour
788 Draw horizontal ticklines at each tick location
789 string colour
791 Colour of the lines. Specifying an empty colour ("")
792 removes them again Defaults to "black"
793 $anyplot legendconfig -option value ...
796 Set one or more options for the legend. The legend is drawn as a
797 rectangle with text and graphics inside.
798 background colour
800 Set the colour of the background (the default colour is
801 white). Set to the empty string for a transparant leg‐
802 end.
803 border colour
805 Set the colour of the border (the default colour is
806 white). Set to the empty string if you do not want a bor‐
807 der.
808 canvas c
810 Draw the legend in a different canvas widget. This gives
811 you the freedom to position the legend outside the actual
812 plot.
813 position corner
815 Set the position of the legend. May be one of: top-left,
816 top-right, bottom-left or bottom-right. (Default value is
817 top-right.)
818 $anyplot legend series text
821 Add an entry to the legend. The series determines which graphi‐
822 cal symbol is to be used. (As a side effect the legend is actu‐
823 ally drawn.)
824 string series
826 Name of the data series. This determines the colour of
827 the line and the symbol (if any) that will be drawn.
828 string text
830 Text to be drawn next to the line/symbol.
831 $anyplot balloon x y text dir
834 Add balloon text to the plot (except for 3D plots). The arrow
835 will point to the given x- and y-coordinates. For xy-graphs and
836 such, the coordinates are directly related to the axes; for ver‐
837 tical barcharts the x-coordinate is measured as the number of
838 bars minus 1 and similar for horizontal barcharts.
839 float x
841 X-coordinate of the point that the arrow of the balloon
842 will point to.
843 float y
845 Y-coordinate of the point that the arrow of the balloon
846 will point to.
847 string text
849 Text to be drawn in the balloon.
850 string dir
852 Direction of the arrow, one of: north, north-east, east,
853 south-east, south, south-west, west or north-west.
854 $anyplot balloonconfig args
857 Configure the balloon text for the plot. The new settings will
858 be used for the next balloon text.
859 font fontname
861 Font to be used for the text
862 justify left|center|right
864 Way to justify multiline text
865 textcolour colour
867 Colour for the text (synonym: textcolor)
868 background colour
870 Background colour for the balloon
871 outline colour
873 Colour of the outline of the balloon
874 margin value
876 Margin around the text (in pixels)
877 rimwidth value
879 Width of the outline of the balloon (in pixels)
880 arrowsize value
882 Length factor for the arrow (in pixels)
883 Note: The commands xconfig and yconfig are currently implemented only
886 for XY-plots and only the option -format has any effect.
887 For xy plots, stripcharts, histograms and time-x-plots:
889 $xyplot plot series xcrd ycrd
891 Add a data point to the plot.
892 string series (in)
894 Name of the data series the new point belongs to.
895 float xcrd (in)
897 X-coordinate of the new point. (For time-x plots this
898 must be valid date/time that can be read with the clock
899 scan command).
900 float ycrd (in)
902 Y-coordinate of the new point.
903 Note on histograms:
905 For histograms the x-coordinate that is given is interpreted to be the
907 x-coordinate of the right side of the bar. The first bar starts at the
908 y-axis on the left. To completely fill the range of the x-axis, you
909 should draw a bar at the maximum x-coordinate.
910 For xy plots:
912 $xyplot trend series xcrd ycrd
914 Draw or update a trend line using the data given sofar.
915 string series (in)
917 Name of the data series the trend line belongs to.
918 float xcrd (in)
920 X-coordinate of the new data point
921 float ycrd (in)
923 Y-coordinate of the new data point
924 $xyplot rchart series xcrd ycrd
926 Draw data in the same way as the plot method, but with two lines
927 added that indicate the expected range (+/- 3*standard devia‐
928 tion) of the data.
929 string series (in)
931 Name of the data series the data point belongs to.
932 float xcrd (in)
934 X-coordinate of the new data point
935 float ycrd (in)
937 Y-coordinate of the new data point
938 $xyplot interval series xcrd ymin ymax ?ycentr?
940 Add a vertical error interval to the plot. The interval is drawn
941 from ymin to ymax. If the ycentr argument is given, a symbol is
942 drawn at that position.
943 string series (in)
945 Name of the data series the interval belongs to.
946 float xcrd (in)
948 X-coordinate of the interval
949 float ymin (in)
951 Minimum y-coordinate of the interval.
952 float ymax (in)
954 Maximum y-coordinate of the interval.
955 float ycentr (in)
957 Y-coordinate to draw the symbol at (optional)
958 $xyplot box-and-whiskers series xcrd ycrd
960 Draw a box and whiskers in the plot. If the argument xcrd is a
961 list of several values and the argument ycrd is a single value,
962 a horizontal box is drawn with the quartiles determined from the
963 list of values contained in xcrd.
964 If, instead, the argument ycrd contains a list of several values
966 and the argument xcrd a single value, then a vertical box is
967 drawn and the quartiles are determined from ycrd. (There must be
968 exactly one list of several values. Otherwise an error is
969 reported.)
970 The option -boxwidth (default: 10 pixels) determines the width
972 (or height) of the box.
973 string series (in)
975 Name of the data series the box-and-whiskers belongs to.
976 float xcrd (in)
978 X-coordinate of the box or a list of values.
979 float ymin (in)
981 Y-coordinate of the box or a list of values.
982 $xyplot vector series xcrd ycrd ucmp vcmp
984 Draw a vector in the plot. The vector can be given as either
985 cartesian coordinates or as length/angle, where the angle is in
986 degrees and is interpreted according to the mathematical conven‐
987 tion or the nautical. (See the vectorconfig subcommand)
988 string series (in)
990 Name of the series the vector belongs to. Determines the
991 appearance and interpretation.
992 float xcrd (in)
994 X-coordinate of the point where the arrow appears
995 float ycrd (in)
997 Y-coordinate of the point where the arrow appears
998 float ucmp (in)
1000 X-component or the length of the vector
1001 float ycentr (in)
1003 Y-component or the angle of the vector
1004 $xyplot vectorconfig series -option value ...
1006 ] Set the vector drawing options for a particular series
1007 string series (in)
1009 Name of the series the vector belongs to.
1010 The options can be one of the following:
1012 colour The colour of the arrow (default: black; synonym: color)
1014 scale value
1016 The scale factor used to convert the length of the arrow
1017 into a number of pixels (default: 1.0)
1018 centred onoff
1020 Logical value indicating that the xy-coordinates are to
1021 be used as the start of the arrow or as the centre
1022 (default: 0; synonym: centered)
1023 type keyword
1025 Interpretation of the vector components. Can be "carte‐
1026 sian" (default), in which case the x- and y-components
1027 are expected, "polar" (the angle 0 coincides with the
1028 positive x-axis, 90 coincides with the positive y-axis)
1029 or "nautical" (0 is "north" and 90 is "east").
1030 $xyplot dot series xcrd ycrd value
1033 Draw a dot in the plot. The size and colour is determined by the
1034 value and by the options set for the series it belongs to. (See
1035 the dotconfig subcommand)
1036 string series (in)
1038 Name of the series the dot belongs to. Determines size
1039 and colour
1040 float xcrd (in)
1042 X-coordinate of the point where the arrow appears
1043 float ycrd (in)
1045 Y-coordinate of the point where the arrow appears
1046 float value (in)
1048 Value determining size and colour
1049 $xyplot dotconfig series -option value ...
1051 ] Set the dot drawing options for a particular series
1052 string series (in)
1054 Name of the series the dot belongs to.
1055 The options can be one of the following:
1057 colour The colour of the dot if no scaling is used or the value
1059 exceeds the last limit of the classes.
1060 scale value
1062 The scale factor used to convert the value into the
1063 radius of the dot in pixels (default: 1.0)
1064 radius value
1066 The default radius of the dots, used if there is no scal‐
1067 ing by value (in pixels; default: 3)
1068 scalebyvalue onoff
1070 Determines whether the dots all have the same size or a
1071 size depending on the given value (default: on).
1072 outline onoff
1074 Draw a black circle around the dot or not (default: on)
1075 classes list
1077 Set the limits and the corresponding colours. For
1078 instance:
1079 $xyplot series1 -classes {0 blue 1 green} -colour red
1082 will cause a blue dot to be drawn for values smaller than
1085 0, a green dot for values larger/equal 0 but lower than 1
1086 and a red dot for values larger/equal 1.
1087 If there is no list of classes for the particular series,
1089 the dots are scaled by the value.
1090 You can combine the colouring by value and the scaling by
1092 value by setting a list of classes and setting the scale‐
1093 byvalue option on.
1094 $xyplot contourlines xcrd ycrd values ?classes?
1097 Draw contour lines for the values given on the grid. The grid is
1098 defined by the xcrd and ycrd arguments (they give the x- and y-
1099 coordinates of the grid cell corners). The values are given at
1100 these corners. The classes determine which contour lines are
1101 drawn. If a value on one of the corners is missing, the contour
1102 lines in that cell will not be drawn.
1103 list xcrd (in)
1105 List of lists, each value is an x-coordinate for a grid
1106 cell corner
1107 list ycrd (in)
1109 List of lists, each value is an y-coordinate for a grid
1110 cell corner
1111 list values (in)
1113 List of lists, each value is the value at a grid cell
1114 corner
1115 list classes (in)
1117 List of class values or a list of lists of two elements
1118 (each inner list the class value and the colour to be
1119 used). If empty or missing, the classes are determined
1120 automatically.
1121 Note: The class values must enclose the whole range of
1123 values.
1124 $xyplot contourfill xcrd ycrd values ?classes?
1127 Draw filled contours for the values given on the grid. (The use
1128 of this method is identical to the "contourlines" method).
1129 $xyplot contourbox xcrd ycrd values ?classes?
1131 Draw the cells as filled quadrangles. The colour is determined
1132 from the average of the values on all four corners.
1133 $xyplot colorMap colours
1135 Set the colours to be used with the contour methods. The argu‐
1136 ment is either a predefined colourmap (grey/gray, jet, hot or
1137 cool) or a list of colours. When selecting the colours for actu‐
1138 ally drawing the contours, the given colours will be interpo‐
1139 lated (based on the HLS scheme).
1140 list colours (in)
1142 List of colour names or colour values or one of the pre‐
1143 defined maps:
1144 · grey or gray: gray colours from dark to light
1146 · jet: rainbow colours
1148 · hot: colours from yellow via red to darkred
1150 · cool: colours from cyan via blue to magenta
1152 $xyplot grid xcrd ycrd
1154 Draw the grid cells as lines connecting the (valid) grid points.
1155 list xcrd (in)
1157 List of lists, each value is an x-coordinate for a grid
1158 cell corner
1159 list ycrd (in)
1161 List of lists, each value is an y-coordinate for a grid
1162 cell corner
1163 For polar plots:
1165 $polarplot plot series radius angle
1167 Add a data point to the polar plot.
1168 string series (in)
1170 Name of the data series the new point belongs to.
1171 float radius (in)
1173 Radial coordinate of the new point.
1174 float angle (in)
1176 Angular coordinate of the new point (in degrees).
1177 For 3D plots:
1179 $plot3d plotfunc function
1181 Plot a function defined over two variables x and y. The resolu‐
1182 tion is determined by the set grid sizes (see the method grid‐
1183 size for more information).
1184 string function (in)
1186 Name of the procedure that calculates the z-value for the
1187 given x and y coordinates. The procedure has to accept
1188 two float arguments (x is first argument, y is second)
1189 and return a floating-point value.
1190 $plot3d plotfuncont function contours
1193 Plot a function defined over two variables x and y using the
1194 contour levels in contours to colour the surface. The resolu‐
1195 tion is determined by the set grid sizes (see the method grid‐
1196 size for more information).
1197 string function (in)
1199 Name of the procedure that calculates the z-value for the
1200 given x and y coordinates. The procedure has to accept
1201 two float arguments (x is first argument, y is second)
1202 and return a floating-point value.
1203 list contours (in)
1205 List of values in ascending order that represent the con‐
1206 tour levels (the boundaries between the colours in the
1207 contour map).
1208 $plot3d gridsize nxcells nycells
1211 Set the grid size in the two directions. Together they determine
1212 how many polygons will be drawn for a function plot.
1213 int nxcells (in)
1215 Number of grid cells in x direction. Has to be an integer
1216 number greater than zero.
1217 int nycells (in)
1219 Number of grid cells in y direction. Has to be an integer
1220 number greater than zero.
1221 $plot3d plotdata data
1224 Plot a matrix of data.
1225 list data (in)
1227 The data to be plotted. The data has to be provided as a
1228 nested list with 2 levels. The outer list contains rows,
1229 drawn in y-direction, and each row is a list whose ele‐
1230 ments are drawn in x-direction, for the columns. Example:
1231 set data {
1235 {1.0 2.0 3.0}
1236 {4.0 5.0 6.0}
1237 }
1238 $plot3d colours fill border
1242 Configure the colours to use for polygon borders and inner area.
1243 color fill (in)
1245 The colour to use for filling the polygons.
1246 color border (in)
1248 The colour to use for the border of the polygons.
1249 For xy plots, stripcharts and polar plots:
1251 $xyplot dataconfig series -option value ...
1253 Set the value for one or more options regarding the drawing of
1254 data of a specific series.
1255 string series (in)
1257 Name of the data series whose configuration we are chang‐
1258 ing.
1259 The following options are allowed:
1261 colour c
1263 color c
1265 The colour to be used when drawing the data series.
1266 type enum
1268 The drawing mode chosen for the series. This can be one
1269 of line, symbol, or both.
1270 symbol enum
1272 What kind of symbol to draw. The value of this option is
1273 ignored when the drawing mode line was chosen. This can
1274 be one of plus, cross, circle, up (triangle pointing up),
1275 down (triangle pointing down), dot (filled circle),
1276 upfilled or downfilled (filled triangles).
1277 filled enum
1279 Whether to fill the area above or below the data line or
1280 not. Can be one of: no, up or down (SPECIAL EFFECTS)
1281 fillcolour colour
1283 Colour to use when filling the area associated with the
1284 data line.
1285 For piecharts:
1287 $pie plot data
1289 Fill a piechart.
1290 list data (in)
1292 A list of pairs (labels and values). The values determine
1293 the relative size of the circle segments. The labels are
1294 drawn beside the circle.
1295 $pie colours colour1 colour2 ...
1297 Set the colours to be used.
1298 color colour1 (in)
1300 The first colour.
1301 color colour2 (in)
1303 The second colour, and so on.
1304 For radial charts:
1306 $radial plot data colour thickness
1308 Draw a new line in the radial chart
1309 list data (in)
1311 A list of data (one for each spoke). The values determine
1312 the distance from the centre of the line connecting the
1313 spokes.
1314 color colour (in)
1316 The colour for the line.
1317 int thickness (in)
1319 An optional argument for the thickness of the line.
1320 $pie colours colour1 colour2 ...
1322 Set the colours to be used.
1323 color colour1 (in)
1325 The first colour.
1326 color colour2 (in)
1328 The second colour, and so on.
1329 For vertical barcharts:
1331 $barchart plot series ydata colour
1333 Add a data series to a barchart.
1334 string series (in)
1336 Name of the series the values belong to.
1337 list ydata (in)
1339 A list of values, one for each x-axis label.
1340 color colour (in)
1342 The colour of the bars.
1343 For horizontal barcharts:
1345 $barchart plot series xdata colour
1347 Add a data series to a barchart.
1348 string series (in)
1350 Name of the series the values belong to.
1351 list xdata (in)
1353 A list of values, one for each y-axis label.
1354 color colour (in)
1356 The colour of the bars.
1357 For 3D barcharts:
1359 $barchart plot label yvalue colour
1361 Add the next bar to the barchart.
1362 string label (in)
1364 The label to be shown below the column.
1365 float yvalue (in)
1367 The value that determines the height of the column
1368 color colour (in)
1370 The colour of the column.
1371 $barchart config -option value ...
1373 Set one or more configuration parameters. The following options
1374 are supported:
1375 usebackground boolean
1377 Whether to draw walls to the left and to the back of the
1378 columns or not
1379 useticklines boolean
1381 Whether to draw ticklines on the walls or not
1382 showvalues boolean
1384 Whether to show the values or not
1385 labelfont newfont
1387 Name of the font to use for labels
1388 labelcolour colour
1390 Colour for the labels
1391 valuefont newfont
1393 Name of the font to use for the values
1394 valuecolour colour
1396 Colour for the values
1397 For 3D ribbon charts:
1399 $ribbon line xypairs colour
1401 Plot the given xy-pairs as a ribbon in the chart
1402 list xypairs (in)
1404 The pairs of x/y values to be drawn (the series is drawn
1405 as a whole)
1406 color colour (in)
1408 The colour of the ribbon.
1409 $ribbon area xypairs colour
1411 Plot the given xy-pairs as a ribbon with a filled area in front.
1412 The effect is that of a box with the data as its upper surface.
1413 list xypairs (in)
1415 The pairs of x/y values to be drawn (the series is drawn
1416 as a whole)
1417 color colour (in)
1419 The colour of the ribbon/area.
1420 For boxplots:
1422 $boxplot plot label values
1424 Add a box-and-whisker to the plot.
1425 string label (in)
1427 The label along the y-axis to which the data belong
1428 list values (in)
1430 List of raw values, the extent of the box and the
1431 whiskers will be determined from this list.
1432 For timecharts:
1434 $timechart period text time_begin time_end colour
1436 Add a time period to the chart.
1437 string text (in)
1439 The text describing the period.
1440 string time_begin (in)
1442 Start time of the period.
1443 string time_end (in)
1445 Stop time of the period.
1446 color colour (in)
1448 The colour of the bar (defaults to black).
1449 $timechart milestone text time colour
1452 Add a milestone (represented as an point-down triangle) to the
1453 chart.
1454 string text (in)
1456 The text describing the milestone.
1457 string time (in)
1459 Time at which the milestone must be positioned.
1460 color colour (in)
1462 The colour of the triangle (defaults to black).
1463 $timechart vertline text time
1466 Add a vertical line (to indicate the start of the month for
1467 instance) to the chart.
1468 string text (in)
1470 The text appearing at the top (an abbreviation of the
1471 date/time for instance).
1472 string time (in)
1474 Time at which the line must be positioned.
1475 $timechart hscroll scrollbar
1477 Connect a horizontal scrollbar to the chart. See also the sec‐
1478 tion on scrolling.
1479 widget scrollbar (in)
1481 The horizontal scrollbar that is to be connected to the
1482 chart
1483 $timechart vscroll scrollbar
1485 Connect a vertical scrollbar to the chart. See also the section
1486 on scrolling.
1487 widget scrollbar (in)
1489 The vertical scrollbar that is to be connected to the
1490 chart
1491 For Gantt charts:
1493 $ganttchart task text time_begin time_end completed
1495 Add a task with its period and level of completion to the chart.
1496 Returns a list of canvas items that can be used for further
1497 manipulations, like connecting two tasks.
1498 string text (in)
1500 The text describing the task.
1501 string time_begin (in)
1503 Start time of the task.
1504 string time_end (in)
1506 Stop time of the task.
1507 float completed (in)
1509 The percentage of the task that is completed.
1510 $ganttchart milestone text time colour
1513 Add a milestone (represented as an point-down triangle) to the
1514 chart.
1515 string text (in)
1517 The text describing the milestone.
1518 string time (in)
1520 Time at which the milestone must be positioned.
1521 color colour (in)
1523 The colour of the triangle (defaults to black).
1524 $ganttchart vertline text time
1527 Add a vertical line (to indicate the start of the month for
1528 instance) to the chart.
1529 string text (in)
1531 The text appearing at the top (an abbreviation of the
1532 date/time for instance).
1533 string time (in)
1535 Time at which the line must be positioned.
1536 $ganttchart connect from to
1539 Add an arrow that connects the from task with the to task.
1540 list from (in)
1542 The list of items returned by the "task" command that
1543 represents the task from which the arrow starts.
1544 string text (in)
1546 The text summarising the tasks
1547 list args (in)
1549 One or more tasks (the lists returned by the "task" com‐
1550 mand). They are shifted down to make room for the sum‐
1551 mary.
1552 list to (in)
1554 The list of items returned by the "task" command that
1555 represents the task at which the arrow ends.
1556 $ganttchart summary text args
1559 Add a summary item that spans all the tasks listed. The graphi‐
1560 cal representation is a thick bar running from the leftmost task
1561 to the rightmost.
1562 Use this command before connecting the tasks, as the arrow would
1564 not be shifted down!
1565 string text (in)
1567 The text summarising the tasks
1568 list args (in)
1570 One or more tasks (the lists returned by the "task" com‐
1571 mand). They are shifted down to make room for the sum‐
1572 mary.
1573 $ganttchart color keyword newcolor
1576 Set the colour of a part of the Gantt chart. These colours hold
1577 for all items of that type.
1578 string keyword (in)
1580 The keyword indicates which part of the Gantt chart to
1581 change:
1582 · description - the colour of the descriptive text
1584 · completed - the colour of the filled bar repre‐
1586 senting the completed part of a task
1587 · left - the colour for the part that is not yet
1589 completed
1590 · odd - the background colour for the odd entries
1592 · even - the background colour for the even entries
1594 · summary - the colour for the summary text
1596 · summarybar - the colour for the bar for a summary
1598 string newcolor (in)
1600 The new colour for the chosen items.
1601 $ganttchart font keyword newfont
1604 Set the font of a part of the Gantt chart. These fonts hold for
1605 all items of that type.
1606 string keyword (in)
1608 The keyword indicates which part of the Gantt chart to
1609 change:
1610 · description - the font used for descriptive text
1612 · summary - the font used for summaries
1614 · scale - the font used for the time scale
1616 string newfont (in)
1618 The new font for the chosen items.
1619 $ganttchart hscroll scrollbar
1621 Connect a horizontal scrollbar to the chart. See also the sec‐
1622 tion on scrolling.
1623 widget scrollbar (in)
1625 The horizontal scrollbar that is to be connected to the
1626 chart
1627 $ganttchart vscroll scrollbar
1629 Connect a vertical scrollbar to the chart. See also the section
1630 on scrolling.
1631 widget scrollbar (in)
1633 The vertical scrollbar that is to be connected to the
1634 chart
1635 For isometric plots (to be extended):
1637 $isoplot plot rectangle x1 y1 x2 y2 colour
1639 Plot the outlines of a rectangle.
1640 float x1 (in)
1642 Minimum x coordinate of the rectangle to be drawn.
1643 float y1 (in)
1645 Minimum y coordinate of the rectangle.
1646 float x2 (in)
1648 Maximum x coordinate of the rectangle to be drawn.
1649 float y2 (in)
1651 Maximum y coordinate of the rectangle.
1652 color colour (in)
1654 The colour of the rectangle.
1655 $isoplot plot filled-rectangle x1 y1 x2 y2 colour
1658 Plot a rectangle filled with the given colour.
1659 float x1 (in)
1661 Minimum x coordinate of the rectangle to be drawn.
1662 float y1 (in)
1664 Minimum y coordinate of the rectangle.
1665 float x2 (in)
1667 Maximum x coordinate of the rectangle to be drawn.
1668 float y2 (in)
1670 Maximum y coordinate of the rectangle.
1671 color colour (in)
1673 The colour of the rectangle.
1674 $isoplot plot circle xc yc radius colour
1677 Plot the outline of a circle.
1678 float xc (in)
1680 X coordinate of the circle's centre.
1681 float yc (in)
1683 Y coordinate of the circle's centre.
1684 color colour (in)
1686 The colour of the circle.
1687 $isoplot plot filled-circle xc yc radius colour
1690 Plot a circle filled with the given colour.
1691 float xc (in)
1693 X coordinate of the circle's centre.
1694 float yc (in)
1696 Y coordinate of the circle's centre.
1697 color colour (in)
1699 The colour of the circle.
1700 There are a number of public procedures that may be useful in specific
1702 situations: Pro memorie.
1703
1705 Besides the commands that deal with the plots and charts directly,
1706 there are a number of commands that can be used to convert world coor‐
1707 dinates to pixels and vice versa. These include:
1708 ::Plotchart::viewPort w pxmin pymin pxmax pymax
1710 Set the viewport for window w. Should be used in cooperation
1711 with ::Plotchart::worldCoordinates.
1712 widget w (in)
1714 Name of the window (canvas widget) in question.
1715 float pxmin (in)
1717 Left-most pixel coordinate.
1718 float pymin (in)
1720 Top-most pixel coordinate (remember: the vertical pixel
1721 coordinate starts with 0 at the top!).
1722 float pxmax (in)
1724 Right-most pixel coordinate.
1725 float pymax (in)
1727 Bottom-most pixel coordinate.
1728 ::Plotchart::worldCoordinates w xmin ymin xmax ymax
1731 Set the extreme world coordinates for window w. The world coor‐
1732 dinates need not be in ascending order (i.e. xmin can be larger
1733 than xmax, so that a reversal of the x-axis is achieved).
1734 widget w (in)
1736 Name of the window (canvas widget) in question.
1737 float xmin (in)
1739 X-coordinate to be mapped to left side of viewport.
1740 float ymin (in)
1742 Y-coordinate to be mapped to bottom of viewport.
1743 float xmax (in)
1745 X-coordinate to be mapped to right side of viewport.
1746 float ymax (in)
1748 Y-coordinate to be mapped to top side of viewport.
1749 ::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
1752 Set the extreme three-dimensional world coordinates for window
1753 w. The world coordinates need not be in ascending order (i.e.
1754 xmin can be larger than xmax, so that a reversal of the x-axis
1755 is achieved).
1756 widget w (in)
1758 Name of the window (canvas widget) in question.
1759 float xmin (in)
1761 X-coordinate to be mapped to front side of the 3D view‐
1762 port.
1763 float ymin (in)
1765 Y-coordinate to be mapped to left side of the viewport.
1766 float zmin (in)
1768 Z-coordinate to be mapped to bottom of viewport.
1769 float xmax (in)
1771 X-coordinate to be mapped to back side of viewport.
1772 float ymax (in)
1774 Y-coordinate to be mapped to right side of viewport.
1775 float zmax (in)
1777 Z-coordinate to be mapped to top side of viewport.
1778 ::Plotchart::coordsToPixel w x y
1781 Return a list of pixel coordinates valid for the given window.
1782 widget w (in)
1784 Name of the window (canvas widget) in question.
1785 float x (in)
1787 X-coordinate to be mapped.
1788 float y (in)
1790 Y-coordinate to be mapped.
1791 ::Plotchart::coords3DToPixel w x y z
1794 Return a list of pixel coordinates valid for the given window.
1795 widget w (in)
1797 Name of the window (canvas widget) in question.
1798 float x (in)
1800 X-coordinate to be mapped.
1801 float y (in)
1803 Y-coordinate to be mapped.
1804 float y (in)
1806 Z-coordinate to be mapped.
1807 ::Plotchart::polarCoordinates w radmax
1810 Set the extreme polar coordinates for window w. The angle always
1811 runs from 0 to 360 degrees and the radius starts at 0. Hence you
1812 only need to give the maximum radius. Note: If the viewport is
1813 not square, this procedure will not adjust the extremes, so that
1814 would result in an elliptical plot. The creation routine for a
1815 polar plot always determines a square viewport.
1816 widget w (in)
1818 Name of the window (canvas widget) in question.
1819 float radmax (in)
1821 Maximum radius.
1822 ::Plotchart::polarToPixel w rad phi
1825 Wrapper for a call to ::Plotchart::coordsToPixel, which assumes
1826 the world coordinates and viewport are set appropriately. Con‐
1827 verts polar coordinates to pixel coordinates. Note: To be use‐
1828 ful it should be accompanied by a matching ::Plotchart::worldCo‐
1829 ordinates procedure. This is automatically taken care of in the
1830 creation routine for polar plots.
1831 widget w (in)
1833 Name of the window (canvas widget) in question.
1834 float rad (in)
1836 Radius of the point.
1837 float phi (in)
1839 Angle to the positive x-axis.
1840 ::Plotchart::pixelToCoords w x y
1843 Return a list of world coordinates valid for the given window.
1844 widget w (in)
1846 Name of the window (canvas widget) in question.
1847 float x (in)
1849 X-pixel to be mapped.
1850 float y (in)
1852 Y-pixel to be mapped.
1853 ::Plotchart::pixelToIndex w x y
1855 Return the index of the pie segment containing the pixel coordi‐
1856 nates (x,y)
1857 widget w (in)
1859 Name of the window (canvas widget) in question, holding a
1860 piechart.
1861 float x (in)
1863 X-pixel to be mapped.
1864 float y (in)
1866 Y-pixel to be mapped.
1867 Furthermore there is a routine to determine "pretty" numbers for use
1869 with an axis:
1870 ::Plotchart::determineScale xmin xmax inverted
1872 Determine "pretty" numbers from the given range and return a
1873 list containing the minimum, maximum and stepsize that can be
1874 used for a (linear) axis.
1875 float xmin (in)
1877 Rough minimum value for the scaling
1878 float xmax (in)
1880 Rough maximum value for the scaling.
1881 boolean inverted (in)
1883 Optional argument: if 1, then the returned list produces
1884 an inverted axis. Defaults to 0 (the axis will be from
1885 minimum to maximum)
1886
1888 Often data that need to be plotted contain gaps - in a series of mea‐
1889 surement data, they can occur because the equipment failed, a sample
1890 was not collected correctly or for many other reasons. The Plotchart
1891 handles these gaps by assuming that one or both coordinates of such
1892 data points are an empty string:
1893 #
1896 # Create the plot with its x- and y-axes
1897 #
1898 set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]
1899 foreach {x y} {0.0 32.0 10.0 {} 25.0 60.0 78.0 11.0 } {
1901 $s plot series1 $x $y
1902 }
1903 The effect varies according to the type of plot:
1905 · For xy-plots, radial plots and strip charts the missing data
1907 point causes a gap in the line through the points.
1908 · For barchats, missing values are treated as if a value of zero
1910 was given.
1911 · For time charts and Gantt charts missing values cause errors -
1913 there is no use for them there.
1914
1916 Besides output to the canvas on screen, the module is capable, via can‐
1917 vas postscript, of producing PostScript files. One may wonder whether
1918 it is possible to extend this set of output formats and the answer is
1919 "yes". This section tries to sum up the aspects of using this module
1920 for another sort of output.
1921 One way you can create output files in a different format, is by exam‐
1923 ining the contents of the canvas after everything has been drawn and
1924 render that contents in the right form. This is probably the easiest
1925 way, as it involves nothing more than the re-creation of all the ele‐
1926 ments in the plot that are already there.
1927 The drawback of that method is that you need to have a display, which
1929 is not always the case if you run a CGI server or something like that.
1930 An alternative is to emulate the canvas command. For this to work, you
1932 need to know which canvas subcommands are used and what for. Obviously,
1933 the create subcommand is used to create the lines, texts and other
1934 items. But also the raise and lower subcommands are used, because with
1935 these the module can influence the drawing order - important to simu‐
1936 late a clipping rectangle around the axes. (The routine DrawMask is
1937 responsible for this - if the output format supports proper clipping
1938 areas, then a redefinition of this routine might just solve this).
1939 Furthermore, the module uses the cget subcommand to find out the sizes
1941 of the canvas. A more mundane aspect of this is that the module cur‐
1942 rently assumes that the text is 14 pixels high and that 80 pixels in
1943 width suffice for the axis' labels. No "hook" is provided to customise
1944 this.
1945 In summary:
1947 · Emulate the create subcommand to create all the items in the
1949 correct format
1950 · Emulate the cget subcommand for the options -width and -height
1952 to allow the correct calculation of the rectangle's position and
1953 size
1954 · Solve the problem of raising and lowering the items so that they
1956 are properly clipped, for instance by redefining the routine
1957 DrawMask.
1958 · Take care of the currently fixed text size properties
1960
1962 As an example of some special effects you can achieve, here is the code
1963 for a plot where the area below the data line varies in colour:
1964 canvas .c -background white -width 400 -height 200
1967 pack .c -fill both
1968 set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]
1970 $s background gradient green top-down
1972 $s dataconfig series1 -filled up -fillcolour white
1974 $s plot series1 0.0 20.0
1976 $s plot series1 10.0 20.0
1977 $s plot series1 30.0 50.0
1978 $s plot series1 35.0 45.0
1979 $s plot series1 45.0 25.0
1980 $s plot series1 75.0 55.0
1981 $s plot series1 100.0 55.0
1982 $s plaintext 30.0 60.0 "Peak" south
1984 The trick is to fill the background with a colour that changes from
1986 green at the top to white at the bottom. Then the area above the data
1987 line is filled with a white polygon. Thus the green shading varies with
1988 the height of the line.
1989
1991 In this version there are a lot of things that still need to be imple‐
1992 mented:
1993 · More robust handling of incorrect calls (right now the proce‐
1995 dures may fail when called incorrectly):
1996 · The axis drawing routines can not handle inverse axes
1998 right now.
1999 · If the user provides an invalid date/time string, the
2001 routines simply throw an error.
2002
2004 Plotchart has not been designed to create plots and charts that keep
2005 track of the data that are put in. This means that if an application
2006 needs to allow the user to resize the window holding the plot or chart,
2007 it must take care to redraw the complete plot.
2008 The code below is a simple example of how to do that:
2010 package require Plotchart
2013 grid [canvas .c -background white] -sticky news
2015 grid columnconfigure . 0 -weight 1
2016 grid rowconfigure . 0 -weight 1
2017 bind .c <Configure> {doResize}
2019 proc doPlot {} {
2021 #
2022 # Clean up the contents (see also the note below!)
2023 #
2024 .c delete all
2025 #
2027 # (Re)draw the bar chart
2028 #
2029 set p [::Plotchart::createBarchart .c {x y z} {0 100 10} 3]
2030 $p plot R {10 30 40} red
2031 $p plot G {30 40 60} green
2032 }
2033 proc doResize {} {
2035 global redo
2036 #
2038 # To avoid redrawing the plot many times during resizing,
2039 # cancel the callback, until the last one is left.
2040 #
2041 if { [info exists redo] } {
2042 after cancel $redo
2043 }
2044 set redo [after 50 doPlot]
2046 }
2047 Please note: The code above will work fine for barcharts and many other
2048 types of plots, but as Plotchart keeps some private information for xy
2049 plots, more is needed in these cases. This actually requires a command
2050 "destroyPlot" to take care of such details. A next version of Plotchart
2051 will have that.
2052
2054 As the Plotchart package does not keep track of the data itself,
2055 rescaling an existing plot - for instance when zooming in - would have
2056 to be done by redefining the plot and redrawing the data. However, the
2057 canvas widget offers a way out by scaling and moving items, so that
2058 zooming in becomes a bit simpler.
2059 Whether zooming is indeed useful, depends on the type of plot. Cur‐
2061 rently it is defined for XY-plots only. The method is called "rescale"
2062 and simply redraws the axes and scales and moves the data items so that
2063 they conform to the new axes. The drawback is that any symbols are
2064 scaled by the same amount. The rescale method works best for plots that
2065 only have lines, not symbols.
2066 The method works very simply:
2068 $p rescale {newxmin newxmax newxstep} {newymin newymax newystep}
2071
2074 The command plotconfig can be used to set all manner of options. The
2075 syntax is:
2076 ::Plotchart::plotconfig charttype component property value
2078 Set a new value for the property of a component in a particular
2079 chart or plot type or query its current value. Each argument is
2080 optional.
2081 string charttype (in)
2083 The type of chart or plot (see the configuration type
2084 that is mentioned for each create command). If not given
2085 or empty, a list of chart types is returned. If it is
2086 given, the properties for that particular type are used.
2087 string component (in)
2089 The component of the plot/chart: leftaxis, rightaxis,
2090 background, margin and so on. If not given or empty, a
2091 list of components is returned. If it is given, the prop‐
2092 erties for that particular component will be set for that
2093 particular type of chart.
2094 string property (in)
2096 The property of the component of the plot/chart: text‐
2097 color, thickness of the axis line, etc. If not given or
2098 empty, a list of properties is returned. If it is given,
2099 that particular property for that particular component
2100 will be set for that particular type of chart.
2101 string value (in)
2103 The new value for the property. If empty, the current
2104 value is returned. If the value is "default", the
2105 default value will be restored.
2106 Note, that in some cases an empty value is useful. Use
2108 "none" in this case - it can be useful for colours and
2109 for formats.
2110 Below is a more detailed list of the components and properties:
2112 · Axes come in a wide variety:
2114 · leftaxis, rightaxis, topaxis, bottomaxis for the plots
2116 with a rectangular shape.
2117 · xaxis, yaxis and zaxis are used for the 3D plots
2119 · axis, this represents the radial and tangential axes of a
2121 polar plot
2122 All axes have the following properties:
2124 · color - the colour of the line and the tickmarks
2126 · thickness - the width of the line of the axis itself, not
2128 the tickmarks
2129 · ticklength - the length of the tickmarks in pixels. A
2131 positive value is outward, a negative value is inward.
2132 · font - the font for the labels and the text at the axis
2134 · format - the format for rendering the (numerical) labels.
2136 For the time axis it is the format for a date and time.
2137 · textcolor - the colour for the labels and the text.
2139 · The margin is important for the layout. Currently only the rec‐
2141 tangular plots allow the margins to be set: left, right, top and
2142 bottom. The values are in pixels.
2143 · The text component is meant for any text appearing via the
2145 plaintext subcommand. The properties are: textcolor, font and
2146 anchor (positioning of the text relative to the given coordi‐
2147 nates).
2148 · The background has two properties: outercolor, the colour out‐
2150 side of the actual plot, and innercolor, the colour inside the
2151 plot. (Note: only "outercolor" has now been implemented).
2152 · The legend has three properties: background, border and posi‐
2154 tion. See the legend subcommand for the meaning.
2155 See the examples in plotdemos7.tcl for it use.
2157
2159 For two types of plots automatic scrolling management has been imple‐
2160 mented: timecharts and Gantt charts. The subcommands hscroll and
2161 vscroll associate (existing) scrollbars to the plot, in much the same
2162 way as for text and canvas widgets.
2163 Once the association is made, the scrollbars are automatically updated
2165 if:
2166 · You add an item with a period wider than the current one.
2168 · You add a vertical line for a time beyond the current bounds.
2170 · You add an extra item beyond the number that was used to create
2172 the chart.
2173 For instance:
2175 package require Plotchart
2178 canvas .c -width 400 -height 200
2180 scrollbar .y -orient vertical
2181 scrollbar .x -orient horizontal
2182 grid .c .y -sticky news
2184 grid .x -sticky news
2185 source plotchart.tcl
2187 set s [::Plotchart::createTimechart .c "1 january 2004" "31 december 2004" 4]
2189 $s period "Spring" "1 march 2004" "1 june 2004" green
2191 $s period "Summer" "1 june 2004" "1 september 2004" yellow
2192 $s vertline "1 jan" "1 january 2004"
2193 $s vertline "1 apr" "1 april 2004"
2194 $s vertline "1 jul" "1 july 2004"
2195 $s vertline "1 oct" "1 october 2004"
2196 $s vertline "1 jan" "1 january 2005"
2197 $s vertline "1 apr" "1 april 2005"
2198 $s vertline "1 jul" "1 july 2005"
2199 $s milestone "Longest day" "21 july 2004"
2200 $s milestone "Longest day 2" "21 july 2004"
2201 $s milestone "Longest day 3" "21 july 2004"
2202 $s milestone "Longest day 4" "21 july 2004"
2203 $s milestone "Longest day 5" "21 july 2004"
2204 $s milestone "Longest day 6" "21 july 2004"
2205 $s title "Seasons (northern hemisphere)"
2206 $s vscroll .y
2208 $s hscroll .x
2209 The original extent of the chart is from 1 january 2004 to 31 december
2211 2004. But because of the addition of vertical lines in 2005 and more
2212 items than was specified at the creation of the chart, both the hori‐
2213 zontal and the vertical scrollbar will be enabled.
2214
2216 The command plotpack allows you to copy the contents of a plot into
2217 another canvas widget. This canvas widget does not act as a composite
2218 plot, but it can be saved as a PostScript file for instance: Note: the
2219 command simply takes a snapshot of the plots/charts as they are at that
2220 moment.
2221 ::Plotchart::plotpack w dir args
2223 Copy the contents of the plots/charts into another widget, in a
2224 manner similar to the pack geometry manager.
2225 widget w (in)
2227 The name of the canvas widget to copy the plots/charts
2228 into
2229 string dir (in)
2231 The direction of the arrangement - top, left, bottom or
2232 right
2233 list args (in)
2235 List of plots/charts to be copied.
2236 For example:
2238 set p1 [createXYPlot ...]
2241 set p2 [createBarchart ...]
2242 ... fill the plots ...
2244 toplevel .t
2246 pack [canvas .t.c2 -width ...]
2247 #
2249 # Copy the two plots above each other in the new canvas
2250 #
2251 plotpack .t.c2 top $p1 $p2
2252
2255 P.M.
2256
2258 I have the following wishlist:
2259 · Isometric plots - allow new items to be implemented easily.
2261 · A general 3D viewer - emphasis on geometry, not a ray-tracer.
2263 · Several improvements for boxplots:
2265 · Height of the box scales with the logarithm of the number
2267 of points
2268 · Marker line to indicate a "current" value
2270 · Box drawn from quantiles
2272
2274 3D bars, 3D surfaces, bar charts, charts, coordinate transformations,
2275 coordinates, graphical presentation, isometric plots, pie charts, plot‐
2276 ting, polar plots, strip charts, time charts, xy-plots
2277
2279 Copyright (c) 2007 Arjen Markus <arjenmarkus@users.sourceforge.net>
2280plotchart 1.6 Plotchart(n)