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:
1011 colour The colour of the arrow (default: black; synonym: color)
1013 scale value
1015 The scale factor used to convert the length of the arrow
1016 into a number of pixels (default: 1.0)
1017 centred onoff
1019 Logical value indicating that the xy-coordinates are to
1020 be used as the start of the arrow or as the centre
1021 (default: 0; synonym: centered)
1022 type keyword
1024 Interpretation of the vector components. Can be "carte‐
1025 sian" (default), in which case the x- and y-components
1026 are expected, "polar" (the angle 0 coincides with the
1027 positive x-axis, 90 coincides with the positive y-axis)
1028 or "nautical" (0 is "north" and 90 is "east").
1029 $xyplot dot series xcrd ycrd value
1032 Draw a dot in the plot. The size and colour is determined by the
1033 value and by the options set for the series it belongs to. (See
1034 the dotconfig subcommand)
1035 string series (in)
1037 Name of the series the dot belongs to. Determines size
1038 and colour
1039 float xcrd (in)
1041 X-coordinate of the point where the arrow appears
1042 float ycrd (in)
1044 Y-coordinate of the point where the arrow appears
1045 float value (in)
1047 Value determining size and colour
1048 $xyplot dotconfig series -option value ...
1050 ] Set the dot drawing options for a particular series
1051 string series (in)
1053 Name of the series the dot belongs to.
1054 The options can be one of the following:
1055 colour The colour of the dot if no scaling is used or the value
1057 exceeds the last limit of the classes.
1058 scale value
1060 The scale factor used to convert the value into the
1061 radius of the dot in pixels (default: 1.0)
1062 radius value
1064 The default radius of the dots, used if there is no scal‐
1065 ing by value (in pixels; default: 3)
1066 scalebyvalue onoff
1068 Determines whether the dots all have the same size or a
1069 size depending on the given value (default: on).
1070 outline onoff
1072 Draw a black circle around the dot or not (default: on)
1073 classes list
1075 Set the limits and the corresponding colours. For
1076 instance:
1077 $xyplot series1 -classes {0 blue 1 green} -colour red
1079 will cause a blue dot to be drawn for values smaller than
1081 0, a green dot for values larger/equal 0 but lower than 1
1082 and a red dot for values larger/equal 1.
1083 If there is no list of classes for the particular series,
1085 the dots are scaled by the value.
1086 You can combine the colouring by value and the scaling by
1088 value by setting a list of classes and setting the scale‐
1089 byvalue option on.
1090 $xyplot contourlines xcrd ycrd values ?classes?
1093 Draw contour lines for the values given on the grid. The grid is
1094 defined by the xcrd and ycrd arguments (they give the x- and y-
1095 coordinates of the grid cell corners). The values are given at
1096 these corners. The classes determine which contour lines are
1097 drawn. If a value on one of the corners is missing, the contour
1098 lines in that cell will not be drawn.
1099 list xcrd (in)
1101 List of lists, each value is an x-coordinate for a grid
1102 cell corner
1103 list ycrd (in)
1105 List of lists, each value is an y-coordinate for a grid
1106 cell corner
1107 list values (in)
1109 List of lists, each value is the value at a grid cell
1110 corner
1111 list classes (in)
1113 List of class values or a list of lists of two elements
1114 (each inner list the class value and the colour to be
1115 used). If empty or missing, the classes are determined
1116 automatically.
1117 Note: The class values must enclose the whole range of
1119 values.
1120 $xyplot contourfill xcrd ycrd values ?classes?
1123 Draw filled contours for the values given on the grid. (The use
1124 of this method is identical to the "contourlines" method).
1125 $xyplot contourbox xcrd ycrd values ?classes?
1127 Draw the cells as filled quadrangles. The colour is determined
1128 from the average of the values on all four corners.
1129 $xyplot colorMap colours
1131 Set the colours to be used with the contour methods. The argu‐
1132 ment is either a predefined colourmap (grey/gray, jet, hot or
1133 cool) or a list of colours. When selecting the colours for actu‐
1134 ally drawing the contours, the given colours will be interpo‐
1135 lated (based on the HLS scheme).
1136 list colours (in)
1138 List of colour names or colour values or one of the pre‐
1139 defined maps:
1140 · grey or gray: gray colours from dark to light
1142 · jet: rainbow colours
1144 · hot: colours from yellow via red to darkred
1146 · cool: colours from cyan via blue to magenta
1148 $xyplot grid xcrd ycrd
1150 Draw the grid cells as lines connecting the (valid) grid points.
1151 list xcrd (in)
1153 List of lists, each value is an x-coordinate for a grid
1154 cell corner
1155 list ycrd (in)
1157 List of lists, each value is an y-coordinate for a grid
1158 cell corner
1159 For polar plots:
1161 $polarplot plot series radius angle
1163 Add a data point to the polar plot.
1164 string series (in)
1166 Name of the data series the new point belongs to.
1167 float radius (in)
1169 Radial coordinate of the new point.
1170 float angle (in)
1172 Angular coordinate of the new point (in degrees).
1173 For 3D plots:
1175 $plot3d plotfunc function
1177 Plot a function defined over two variables x and y. The resolu‐
1178 tion is determined by the set grid sizes (see the method grid‐
1179 size for more information).
1180 string function (in)
1182 Name of the procedure that calculates the z-value for the
1183 given x and y coordinates. The procedure has to accept
1184 two float arguments (x is first argument, y is second)
1185 and return a floating-point value.
1186 $plot3d plotfuncont function contours
1189 Plot a function defined over two variables x and y using the
1190 contour levels in contours to colour the surface. The resolu‐
1191 tion is determined by the set grid sizes (see the method grid‐
1192 size for more information).
1193 string function (in)
1195 Name of the procedure that calculates the z-value for the
1196 given x and y coordinates. The procedure has to accept
1197 two float arguments (x is first argument, y is second)
1198 and return a floating-point value.
1199 list contours (in)
1201 List of values in ascending order that represent the con‐
1202 tour levels (the boundaries between the colours in the
1203 contour map).
1204 $plot3d gridsize nxcells nycells
1207 Set the grid size in the two directions. Together they determine
1208 how many polygons will be drawn for a function plot.
1209 int nxcells (in)
1211 Number of grid cells in x direction. Has to be an integer
1212 number greater than zero.
1213 int nycells (in)
1215 Number of grid cells in y direction. Has to be an integer
1216 number greater than zero.
1217 $plot3d plotdata data
1220 Plot a matrix of data.
1221 list data (in)
1223 The data to be plotted. The data has to be provided as a
1224 nested list with 2 levels. The outer list contains rows,
1225 drawn in y-direction, and each row is a list whose ele‐
1226 ments are drawn in x-direction, for the columns. Example:
1227 set data {
1230 {1.0 2.0 3.0}
1231 {4.0 5.0 6.0}
1232 }
1233 $plot3d colours fill border
1237 Configure the colours to use for polygon borders and inner area.
1238 color fill (in)
1240 The colour to use for filling the polygons.
1241 color border (in)
1243 The colour to use for the border of the polygons.
1244 For xy plots, stripcharts and polar plots:
1246 $xyplot dataconfig series -option value ...
1248 Set the value for one or more options regarding the drawing of
1249 data of a specific series.
1250 string series (in)
1252 Name of the data series whose configuration we are chang‐
1253 ing.
1254 The following options are allowed:
1256 colour c
1258 color c
1260 The colour to be used when drawing the data series.
1261 type enum
1263 The drawing mode chosen for the series. This can be one
1264 of line, symbol, or both.
1265 symbol enum
1267 What kind of symbol to draw. The value of this option is
1268 ignored when the drawing mode line was chosen. This can
1269 be one of plus, cross, circle, up (triangle pointing up),
1270 down (triangle pointing down), dot (filled circle),
1271 upfilled or downfilled (filled triangles).
1272 filled enum
1274 Whether to fill the area above or below the data line or
1275 not. Can be one of: no, up or down (SPECIAL EFFECTS)
1276 fillcolour colour
1278 Colour to use when filling the area associated with the
1279 data line.
1280 For piecharts:
1282 $pie plot data
1284 Fill a piechart.
1285 list data (in)
1287 A list of pairs (labels and values). The values determine
1288 the relative size of the circle segments. The labels are
1289 drawn beside the circle.
1290 $pie colours colour1 colour2 ...
1292 Set the colours to be used.
1293 color colour1 (in)
1295 The first colour.
1296 color colour2 (in)
1298 The second colour, and so on.
1299 For radial charts:
1301 $radial plot data colour thickness
1303 Draw a new line in the radial chart
1304 list data (in)
1306 A list of data (one for each spoke). The values determine
1307 the distance from the centre of the line connecting the
1308 spokes.
1309 color colour (in)
1311 The colour for the line.
1312 int thickness (in)
1314 An optional argument for the thickness of the line.
1315 $pie colours colour1 colour2 ...
1317 Set the colours to be used.
1318 color colour1 (in)
1320 The first colour.
1321 color colour2 (in)
1323 The second colour, and so on.
1324 For vertical barcharts:
1326 $barchart plot series ydata colour
1328 Add a data series to a barchart.
1329 string series (in)
1331 Name of the series the values belong to.
1332 list ydata (in)
1334 A list of values, one for each x-axis label.
1335 color colour (in)
1337 The colour of the bars.
1338 For horizontal barcharts:
1340 $barchart plot series xdata colour
1342 Add a data series to a barchart.
1343 string series (in)
1345 Name of the series the values belong to.
1346 list xdata (in)
1348 A list of values, one for each y-axis label.
1349 color colour (in)
1351 The colour of the bars.
1352 For 3D barcharts:
1354 $barchart plot label yvalue colour
1356 Add the next bar to the barchart.
1357 string label (in)
1359 The label to be shown below the column.
1360 float yvalue (in)
1362 The value that determines the height of the column
1363 color colour (in)
1365 The colour of the column.
1366 $barchart config -option value ...
1368 Set one or more configuration parameters. The following options
1369 are supported:
1370 usebackground boolean
1372 Whether to draw walls to the left and to the back of the
1373 columns or not
1374 useticklines boolean
1376 Whether to draw ticklines on the walls or not
1377 showvalues boolean
1379 Whether to show the values or not
1380 labelfont newfont
1382 Name of the font to use for labels
1383 labelcolour colour
1385 Colour for the labels
1386 valuefont newfont
1388 Name of the font to use for the values
1389 valuecolour colour
1391 Colour for the values
1392 For 3D ribbon charts:
1394 $ribbon line xypairs colour
1396 Plot the given xy-pairs as a ribbon in the chart
1397 list xypairs (in)
1399 The pairs of x/y values to be drawn (the series is drawn
1400 as a whole)
1401 color colour (in)
1403 The colour of the ribbon.
1404 $ribbon area xypairs colour
1406 Plot the given xy-pairs as a ribbon with a filled area in front.
1407 The effect is that of a box with the data as its upper surface.
1408 list xypairs (in)
1410 The pairs of x/y values to be drawn (the series is drawn
1411 as a whole)
1412 color colour (in)
1414 The colour of the ribbon/area.
1415 For boxplots:
1417 $boxplot plot label values
1419 Add a box-and-whisker to the plot.
1420 string label (in)
1422 The label along the y-axis to which the data belong
1423 list values (in)
1425 List of raw values, the extent of the box and the
1426 whiskers will be determined from this list.
1427 For timecharts:
1429 $timechart period text time_begin time_end colour
1431 Add a time period to the chart.
1432 string text (in)
1434 The text describing the period.
1435 string time_begin (in)
1437 Start time of the period.
1438 string time_end (in)
1440 Stop time of the period.
1441 color colour (in)
1443 The colour of the bar (defaults to black).
1444 $timechart milestone text time colour
1447 Add a milestone (represented as an point-down triangle) to the
1448 chart.
1449 string text (in)
1451 The text describing the milestone.
1452 string time (in)
1454 Time at which the milestone must be positioned.
1455 color colour (in)
1457 The colour of the triangle (defaults to black).
1458 $timechart vertline text time
1461 Add a vertical line (to indicate the start of the month for
1462 instance) to the chart.
1463 string text (in)
1465 The text appearing at the top (an abbreviation of the
1466 date/time for instance).
1467 string time (in)
1469 Time at which the line must be positioned.
1470 $timechart hscroll scrollbar
1472 Connect a horizontal scrollbar to the chart. See also the sec‐
1473 tion on scrolling.
1474 widget scrollbar (in)
1476 The horizontal scrollbar that is to be connected to the
1477 chart
1478 $timechart vscroll scrollbar
1480 Connect a vertical scrollbar to the chart. See also the section
1481 on scrolling.
1482 widget scrollbar (in)
1484 The vertical scrollbar that is to be connected to the
1485 chart
1486 For Gantt charts:
1488 $ganttchart task text time_begin time_end completed
1490 Add a task with its period and level of completion to the chart.
1491 Returns a list of canvas items that can be used for further
1492 manipulations, like connecting two tasks.
1493 string text (in)
1495 The text describing the task.
1496 string time_begin (in)
1498 Start time of the task.
1499 string time_end (in)
1501 Stop time of the task.
1502 float completed (in)
1504 The percentage of the task that is completed.
1505 $ganttchart milestone text time colour
1508 Add a milestone (represented as an point-down triangle) to the
1509 chart.
1510 string text (in)
1512 The text describing the milestone.
1513 string time (in)
1515 Time at which the milestone must be positioned.
1516 color colour (in)
1518 The colour of the triangle (defaults to black).
1519 $ganttchart vertline text time
1522 Add a vertical line (to indicate the start of the month for
1523 instance) to the chart.
1524 string text (in)
1526 The text appearing at the top (an abbreviation of the
1527 date/time for instance).
1528 string time (in)
1530 Time at which the line must be positioned.
1531 $ganttchart connect from to
1534 Add an arrow that connects the from task with the to task.
1535 list from (in)
1537 The list of items returned by the "task" command that
1538 represents the task from which the arrow starts.
1539 string text (in)
1541 The text summarising the tasks
1542 list args (in)
1544 One or more tasks (the lists returned by the "task" com‐
1545 mand). They are shifted down to make room for the sum‐
1546 mary.
1547 list to (in)
1549 The list of items returned by the "task" command that
1550 represents the task at which the arrow ends.
1551 $ganttchart summary text args
1554 Add a summary item that spans all the tasks listed. The graphi‐
1555 cal representation is a thick bar running from the leftmost task
1556 to the rightmost.
1557 Use this command before connecting the tasks, as the arrow would
1559 not be shifted down!
1560 string text (in)
1562 The text summarising the tasks
1563 list args (in)
1565 One or more tasks (the lists returned by the "task" com‐
1566 mand). They are shifted down to make room for the sum‐
1567 mary.
1568 $ganttchart color keyword newcolor
1571 Set the colour of a part of the Gantt chart. These colours hold
1572 for all items of that type.
1573 string keyword (in)
1575 The keyword indicates which part of the Gantt chart to
1576 change:
1577 · description - the colour of the descriptive text
1579 · completed - the colour of the filled bar repre‐
1581 senting the completed part of a task
1582 · left - the colour for the part that is not yet
1584 completed
1585 · odd - the background colour for the odd entries
1587 · even - the background colour for the even entries
1589 · summary - the colour for the summary text
1591 · summarybar - the colour for the bar for a summary
1593 string newcolor (in)
1595 The new colour for the chosen items.
1596 $ganttchart font keyword newfont
1599 Set the font of a part of the Gantt chart. These fonts hold for
1600 all items of that type.
1601 string keyword (in)
1603 The keyword indicates which part of the Gantt chart to
1604 change:
1605 · description - the font used for descriptive text
1607 · summary - the font used for summaries
1609 · scale - the font used for the time scale
1611 string newfont (in)
1613 The new font for the chosen items.
1614 $ganttchart hscroll scrollbar
1616 Connect a horizontal scrollbar to the chart. See also the sec‐
1617 tion on scrolling.
1618 widget scrollbar (in)
1620 The horizontal scrollbar that is to be connected to the
1621 chart
1622 $ganttchart vscroll scrollbar
1624 Connect a vertical scrollbar to the chart. See also the section
1625 on scrolling.
1626 widget scrollbar (in)
1628 The vertical scrollbar that is to be connected to the
1629 chart
1630 For isometric plots (to be extended):
1632 $isoplot plot rectangle x1 y1 x2 y2 colour
1634 Plot the outlines of a rectangle.
1635 float x1 (in)
1637 Minimum x coordinate of the rectangle to be drawn.
1638 float y1 (in)
1640 Minimum y coordinate of the rectangle.
1641 float x2 (in)
1643 Maximum x coordinate of the rectangle to be drawn.
1644 float y2 (in)
1646 Maximum y coordinate of the rectangle.
1647 color colour (in)
1649 The colour of the rectangle.
1650 $isoplot plot filled-rectangle x1 y1 x2 y2 colour
1653 Plot a rectangle filled with the given colour.
1654 float x1 (in)
1656 Minimum x coordinate of the rectangle to be drawn.
1657 float y1 (in)
1659 Minimum y coordinate of the rectangle.
1660 float x2 (in)
1662 Maximum x coordinate of the rectangle to be drawn.
1663 float y2 (in)
1665 Maximum y coordinate of the rectangle.
1666 color colour (in)
1668 The colour of the rectangle.
1669 $isoplot plot circle xc yc radius colour
1672 Plot the outline of a circle.
1673 float xc (in)
1675 X coordinate of the circle's centre.
1676 float yc (in)
1678 Y coordinate of the circle's centre.
1679 color colour (in)
1681 The colour of the circle.
1682 $isoplot plot filled-circle xc yc radius colour
1685 Plot a circle filled with the given colour.
1686 float xc (in)
1688 X coordinate of the circle's centre.
1689 float yc (in)
1691 Y coordinate of the circle's centre.
1692 color colour (in)
1694 The colour of the circle.
1695 There are a number of public procedures that may be useful in specific
1697 situations: Pro memorie.
1698
1700 Besides the commands that deal with the plots and charts directly,
1701 there are a number of commands that can be used to convert world coor‐
1702 dinates to pixels and vice versa. These include:
1703 ::Plotchart::viewPort w pxmin pymin pxmax pymax
1705 Set the viewport for window w. Should be used in cooperation
1706 with ::Plotchart::worldCoordinates.
1707 widget w (in)
1709 Name of the window (canvas widget) in question.
1710 float pxmin (in)
1712 Left-most pixel coordinate.
1713 float pymin (in)
1715 Top-most pixel coordinate (remember: the vertical pixel
1716 coordinate starts with 0 at the top!).
1717 float pxmax (in)
1719 Right-most pixel coordinate.
1720 float pymax (in)
1722 Bottom-most pixel coordinate.
1723 ::Plotchart::worldCoordinates w xmin ymin xmax ymax
1726 Set the extreme world coordinates for window w. The world coor‐
1727 dinates need not be in ascending order (i.e. xmin can be larger
1728 than xmax, so that a reversal of the x-axis is achieved).
1729 widget w (in)
1731 Name of the window (canvas widget) in question.
1732 float xmin (in)
1734 X-coordinate to be mapped to left side of viewport.
1735 float ymin (in)
1737 Y-coordinate to be mapped to bottom of viewport.
1738 float xmax (in)
1740 X-coordinate to be mapped to right side of viewport.
1741 float ymax (in)
1743 Y-coordinate to be mapped to top side of viewport.
1744 ::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
1747 Set the extreme three-dimensional world coordinates for window
1748 w. The world coordinates need not be in ascending order (i.e.
1749 xmin can be larger than xmax, so that a reversal of the x-axis
1750 is achieved).
1751 widget w (in)
1753 Name of the window (canvas widget) in question.
1754 float xmin (in)
1756 X-coordinate to be mapped to front side of the 3D view‐
1757 port.
1758 float ymin (in)
1760 Y-coordinate to be mapped to left side of the viewport.
1761 float zmin (in)
1763 Z-coordinate to be mapped to bottom of viewport.
1764 float xmax (in)
1766 X-coordinate to be mapped to back side of viewport.
1767 float ymax (in)
1769 Y-coordinate to be mapped to right side of viewport.
1770 float zmax (in)
1772 Z-coordinate to be mapped to top side of viewport.
1773 ::Plotchart::coordsToPixel w x y
1776 Return a list of pixel coordinates valid for the given window.
1777 widget w (in)
1779 Name of the window (canvas widget) in question.
1780 float x (in)
1782 X-coordinate to be mapped.
1783 float y (in)
1785 Y-coordinate to be mapped.
1786 ::Plotchart::coords3DToPixel w x y z
1789 Return a list of pixel coordinates valid for the given window.
1790 widget w (in)
1792 Name of the window (canvas widget) in question.
1793 float x (in)
1795 X-coordinate to be mapped.
1796 float y (in)
1798 Y-coordinate to be mapped.
1799 float y (in)
1801 Z-coordinate to be mapped.
1802 ::Plotchart::polarCoordinates w radmax
1805 Set the extreme polar coordinates for window w. The angle always
1806 runs from 0 to 360 degrees and the radius starts at 0. Hence you
1807 only need to give the maximum radius. Note: If the viewport is
1808 not square, this procedure will not adjust the extremes, so that
1809 would result in an elliptical plot. The creation routine for a
1810 polar plot always determines a square viewport.
1811 widget w (in)
1813 Name of the window (canvas widget) in question.
1814 float radmax (in)
1816 Maximum radius.
1817 ::Plotchart::polarToPixel w rad phi
1820 Wrapper for a call to ::Plotchart::coordsToPixel, which assumes
1821 the world coordinates and viewport are set appropriately. Con‐
1822 verts polar coordinates to pixel coordinates. Note: To be use‐
1823 ful it should be accompanied by a matching ::Plotchart::worldCo‐
1824 ordinates procedure. This is automatically taken care of in the
1825 creation routine for polar plots.
1826 widget w (in)
1828 Name of the window (canvas widget) in question.
1829 float rad (in)
1831 Radius of the point.
1832 float phi (in)
1834 Angle to the positive x-axis.
1835 ::Plotchart::pixelToCoords w x y
1838 Return a list of world coordinates valid for the given window.
1839 widget w (in)
1841 Name of the window (canvas widget) in question.
1842 float x (in)
1844 X-pixel to be mapped.
1845 float y (in)
1847 Y-pixel to be mapped.
1848 ::Plotchart::pixelToIndex w x y
1850 Return the index of the pie segment containing the pixel coordi‐
1851 nates (x,y)
1852 widget w (in)
1854 Name of the window (canvas widget) in question, holding a
1855 piechart.
1856 float x (in)
1858 X-pixel to be mapped.
1859 float y (in)
1861 Y-pixel to be mapped.
1862 Furthermore there is a routine to determine "pretty" numbers for use
1864 with an axis:
1865 ::Plotchart::determineScale xmin xmax inverted
1867 Determine "pretty" numbers from the given range and return a
1868 list containing the minimum, maximum and stepsize that can be
1869 used for a (linear) axis.
1870 float xmin (in)
1872 Rough minimum value for the scaling
1873 float xmax (in)
1875 Rough maximum value for the scaling.
1876 boolean inverted (in)
1878 Optional argument: if 1, then the returned list produces
1879 an inverted axis. Defaults to 0 (the axis will be from
1880 minimum to maximum)
1881
1883 Often data that need to be plotted contain gaps - in a series of mea‐
1884 surement data, they can occur because the equipment failed, a sample
1885 was not collected correctly or for many other reasons. The Plotchart
1886 handles these gaps by assuming that one or both coordinates of such
1887 data points are an empty string:
1888 #
1890 # Create the plot with its x- and y-axes
1891 #
1892 set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]
1893 foreach {x y} {0.0 32.0 10.0 {} 25.0 60.0 78.0 11.0 } {
1895 $s plot series1 $x $y
1896 }
1897 The effect varies according to the type of plot:
1899 · For xy-plots, radial plots and strip charts the missing data
1901 point causes a gap in the line through the points.
1902 · For barchats, missing values are treated as if a value of zero
1904 was given.
1905 · For time charts and Gantt charts missing values cause errors -
1907 there is no use for them there.
1908
1910 Besides output to the canvas on screen, the module is capable, via can‐
1911 vas postscript, of producing PostScript files. One may wonder whether
1912 it is possible to extend this set of output formats and the answer is
1913 "yes". This section tries to sum up the aspects of using this module
1914 for another sort of output.
1915 One way you can create output files in a different format, is by exam‐
1917 ining the contents of the canvas after everything has been drawn and
1918 render that contents in the right form. This is probably the easiest
1919 way, as it involves nothing more than the re-creation of all the ele‐
1920 ments in the plot that are already there.
1921 The drawback of that method is that you need to have a display, which
1923 is not always the case if you run a CGI server or something like that.
1924 An alternative is to emulate the canvas command. For this to work, you
1926 need to know which canvas subcommands are used and what for. Obviously,
1927 the create subcommand is used to create the lines, texts and other
1928 items. But also the raise and lower subcommands are used, because with
1929 these the module can influence the drawing order - important to simu‐
1930 late a clipping rectangle around the axes. (The routine DrawMask is
1931 responsible for this - if the output format supports proper clipping
1932 areas, then a redefinition of this routine might just solve this).
1933 Furthermore, the module uses the cget subcommand to find out the sizes
1935 of the canvas. A more mundane aspect of this is that the module cur‐
1936 rently assumes that the text is 14 pixels high and that 80 pixels in
1937 width suffice for the axis' labels. No "hook" is provided to customise
1938 this.
1939 In summary:
1941 · Emulate the create subcommand to create all the items in the
1943 correct format
1944 · Emulate the cget subcommand for the options -width and -height
1946 to allow the correct calculation of the rectangle's position and
1947 size
1948 · Solve the problem of raising and lowering the items so that they
1950 are properly clipped, for instance by redefining the routine
1951 DrawMask.
1952 · Take care of the currently fixed text size properties
1954
1956 As an example of some special effects you can achieve, here is the code
1957 for a plot where the area below the data line varies in colour:
1958 canvas .c -background white -width 400 -height 200
1960 pack .c -fill both
1961 set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]
1963 $s background gradient green top-down
1965 $s dataconfig series1 -filled up -fillcolour white
1967 $s plot series1 0.0 20.0
1969 $s plot series1 10.0 20.0
1970 $s plot series1 30.0 50.0
1971 $s plot series1 35.0 45.0
1972 $s plot series1 45.0 25.0
1973 $s plot series1 75.0 55.0
1974 $s plot series1 100.0 55.0
1975 $s plaintext 30.0 60.0 "Peak" south
1977 The trick is to fill the background with a colour that changes from
1979 green at the top to white at the bottom. Then the area above the data
1980 line is filled with a white polygon. Thus the green shading varies with
1981 the height of the line.
1982
1984 In this version there are a lot of things that still need to be imple‐
1985 mented:
1986 · More robust handling of incorrect calls (right now the proce‐
1988 dures may fail when called incorrectly):
1989 · The axis drawing routines can not handle inverse axes
1991 right now.
1992 · If the user provides an invalid date/time string, the
1994 routines simply throw an error.
1995
1997 Plotchart has not been designed to create plots and charts that keep
1998 track of the data that are put in. This means that if an application
1999 needs to allow the user to resize the window holding the plot or chart,
2000 it must take care to redraw the complete plot.
2001 The code below is a simple example of how to do that:
2003 package require Plotchart
2005 grid [canvas .c -background white] -sticky news
2007 grid columnconfigure . 0 -weight 1
2008 grid rowconfigure . 0 -weight 1
2009 bind .c <Configure> {doResize}
2011 proc doPlot {} {
2013 #
2014 # Clean up the contents (see also the note below!)
2015 #
2016 .c delete all
2017 #
2019 # (Re)draw the bar chart
2020 #
2021 set p [::Plotchart::createBarchart .c {x y z} {0 100 10} 3]
2022 $p plot R {10 30 40} red
2023 $p plot G {30 40 60} green
2024 }
2025 proc doResize {} {
2027 global redo
2028 #
2030 # To avoid redrawing the plot many times during resizing,
2031 # cancel the callback, until the last one is left.
2032 #
2033 if { [info exists redo] } {
2034 after cancel $redo
2035 }
2036 set redo [after 50 doPlot]
2038 }
2039 Please note: The code above will work fine for barcharts and many other
2040 types of plots, but as Plotchart keeps some private information for xy
2041 plots, more is needed in these cases. This actually requires a command
2042 "destroyPlot" to take care of such details. A next version of Plotchart
2043 will have that.
2044
2046 As the Plotchart package does not keep track of the data itself,
2047 rescaling an existing plot - for instance when zooming in - would have
2048 to be done by redefining the plot and redrawing the data. However, the
2049 canvas widget offers a way out by scaling and moving items, so that
2050 zooming in becomes a bit simpler.
2051 Whether zooming is indeed useful, depends on the type of plot. Cur‐
2053 rently it is defined for XY-plots only. The method is called "rescale"
2054 and simply redraws the axes and scales and moves the data items so that
2055 they conform to the new axes. The drawback is that any symbols are
2056 scaled by the same amount. The rescale method works best for plots that
2057 only have lines, not symbols.
2058 The method works very simply:
2060 $p rescale {newxmin newxmax newxstep} {newymin newymax newystep}
2062
2065 The command plotconfig can be used to set all manner of options. The
2066 syntax is:
2067 ::Plotchart::plotconfig charttype component property value
2069 Set a new value for the property of a component in a particular
2070 chart or plot type or query its current value. Each argument is
2071 optional.
2072 string charttype (in)
2074 The type of chart or plot (see the configuration type
2075 that is mentioned for each create command). If not given
2076 or empty, a list of chart types is returned. If it is
2077 given, the properties for that particular type are used.
2078 string component (in)
2080 The component of the plot/chart: leftaxis, rightaxis,
2081 background, margin and so on. If not given or empty, a
2082 list of components is returned. If it is given, the prop‐
2083 erties for that particular component will be set for that
2084 particular type of chart.
2085 string property (in)
2087 The property of the component of the plot/chart: text‐
2088 color, thickness of the axis line, etc. If not given or
2089 empty, a list of properties is returned. If it is given,
2090 that particular property for that particular component
2091 will be set for that particular type of chart.
2092 string value (in)
2094 The new value for the property. If empty, the current
2095 value is returned. If the value is "default", the
2096 default value will be restored.
2097 Note, that in some cases an empty value is useful. Use
2099 "none" in this case - it can be useful for colours and
2100 for formats.
2101 Below is a more detailed list of the components and properties:
2103 · Axes come in a wide variety:
2105 · leftaxis, rightaxis, topaxis, bottomaxis for the plots
2107 with a rectangular shape.
2108 · xaxis, yaxis and zaxis are used for the 3D plots
2110 · axis, this represents the radial and tangential axes of a
2112 polar plot
2113 All axes have the following properties:
2114 · color - the colour of the line and the tickmarks
2116 · thickness - the width of the line of the axis itself, not
2118 the tickmarks
2119 · ticklength - the length of the tickmarks in pixels. A
2121 positive value is outward, a negative value is inward.
2122 · font - the font for the labels and the text at the axis
2124 · format - the format for rendering the (numerical) labels.
2126 For the time axis it is the format for a date and time.
2127 · textcolor - the colour for the labels and the text.
2129 · The margin is important for the layout. Currently only the rec‐
2131 tangular plots allow the margins to be set: left, right, top and
2132 bottom. The values are in pixels.
2133 · The text component is meant for any text appearing via the
2135 plaintext subcommand. The properties are: textcolor, font and
2136 anchor (positioning of the text relative to the given coordi‐
2137 nates).
2138 · The background has two properties: outercolor, the colour out‐
2140 side of the actual plot, and innercolor, the colour inside the
2141 plot. (Note: only "outercolor" has now been implemented).
2142 · The legend has three properties: background, border and posi‐
2144 tion. See the legend subcommand for the meaning.
2145 See the examples in plotdemos7.tcl for it use.
2147
2149 For two types of plots automatic scrolling management has been imple‐
2150 mented: timecharts and Gantt charts. The subcommands hscroll and
2151 vscroll associate (existing) scrollbars to the plot, in much the same
2152 way as for text and canvas widgets.
2153 Once the association is made, the scrollbars are automatically updated
2155 if:
2156 · You add an item with a period wider than the current one.
2158 · You add a vertical line for a time beyond the current bounds.
2160 · You add an extra item beyond the number that was used to create
2162 the chart.
2163 For instance:
2165 package require Plotchart
2167 canvas .c -width 400 -height 200
2169 scrollbar .y -orient vertical
2170 scrollbar .x -orient horizontal
2171 grid .c .y -sticky news
2173 grid .x -sticky news
2174 source plotchart.tcl
2176 set s [::Plotchart::createTimechart .c "1 january 2004" "31 december 2004" 4]
2178 $s period "Spring" "1 march 2004" "1 june 2004" green
2180 $s period "Summer" "1 june 2004" "1 september 2004" yellow
2181 $s vertline "1 jan" "1 january 2004"
2182 $s vertline "1 apr" "1 april 2004"
2183 $s vertline "1 jul" "1 july 2004"
2184 $s vertline "1 oct" "1 october 2004"
2185 $s vertline "1 jan" "1 january 2005"
2186 $s vertline "1 apr" "1 april 2005"
2187 $s vertline "1 jul" "1 july 2005"
2188 $s milestone "Longest day" "21 july 2004"
2189 $s milestone "Longest day 2" "21 july 2004"
2190 $s milestone "Longest day 3" "21 july 2004"
2191 $s milestone "Longest day 4" "21 july 2004"
2192 $s milestone "Longest day 5" "21 july 2004"
2193 $s milestone "Longest day 6" "21 july 2004"
2194 $s title "Seasons (northern hemisphere)"
2195 $s vscroll .y
2197 $s hscroll .x
2198 The original extent of the chart is from 1 january 2004 to 31 december
2200 2004. But because of the addition of vertical lines in 2005 and more
2201 items than was specified at the creation of the chart, both the hori‐
2202 zontal and the vertical scrollbar will be enabled.
2203
2205 The command plotpack allows you to copy the contents of a plot into
2206 another canvas widget. This canvas widget does not act as a composite
2207 plot, but it can be saved as a PostScript file for instance: Note: the
2208 command simply takes a snapshot of the plots/charts as they are at that
2209 moment.
2210 ::Plotchart::plotpack w dir args
2212 Copy the contents of the plots/charts into another widget, in a
2213 manner similar to the pack geometry manager.
2214 widget w (in)
2216 The name of the canvas widget to copy the plots/charts
2217 into
2218 string dir (in)
2220 The direction of the arrangement - top, left, bottom or
2221 right
2222 list args (in)
2224 List of plots/charts to be copied.
2225 For example:
2227 set p1 [createXYPlot ...]
2229 set p2 [createBarchart ...]
2230 ... fill the plots ...
2232 toplevel .t
2234 pack [canvas .t.c2 -width ...]
2235 #
2237 # Copy the two plots above each other in the new canvas
2238 #
2239 plotpack .t.c2 top $p1 $p2
2240
2243 P.M.
2244
2246 I have the following wishlist:
2247 · Isometric plots - allow new items to be implemented easily.
2249 · A general 3D viewer - emphasis on geometry, not a ray-tracer.
2251 · Several improvements for boxplots:
2253 · Height of the box scales with the logarithm of the number
2255 of points
2256 · Marker line to indicate a "current" value
2258 · Box drawn from quantiles
2260
2262 3D bars, 3D surfaces, bar charts, charts, coordinate transformations,
2263 coordinates, graphical presentation, isometric plots, pie charts, plot‐
2264 ting, polar plots, strip charts, time charts, xy-plots
2265
2267 Copyright (c) 2007 Arjen Markus <arjenmarkus@users.sourceforge.net>
2268plotchart 1.6 Plotchart(n)