Plotchart - Simple plotting and charting package
Plotchart is a Tcl-only package that focuses on the easy creation of xy-plots, barcharts and other common types of graphical presentations. The emphasis is on ease of use, rather than flexibility. The procedures that create a plot use the entire canvas window, making the layout of the plot completely automatic.
This results in the creation of an xy-plot in, say, ten lines of code:
package require Plotchart
canvas .c -background white -width 400 -height 200
pack .c -fill both
#
# Create the plot with its x- and y-axes
#
set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]
foreach {x y} {0.0 32.0 10.0 50.0 25.0 60.0 78.0 11.0 } {
$s plot series1 $x $y
}
$s title "Data series"
A drawback of the package might be that it does not do any data management. So if the canvas that holds the plot is to be resized, the whole plot must be redrawn. The advantage, though, is that it offers a number of plot and chart types:
XY-plots like the one shown above with any number of data series.
Stripcharts, a kind of XY-plots where the horizontal axis is adjusted automatically. The result is a kind of sliding window on the data series.
Polar plots, where the coordinates are polar instead of cartesian.
Histograms, for plotting statistical information.
Isometric plots, where the scale of the coordinates in the two directions is always the same, i.e. a circle in world coordinates appears as a circle on the screen.
You can zoom in and out, as well as pan with these plots (Note: this works best if no axes are drawn, the zooming and panning routines do not distinguish the axes), using the mouse buttons with the control key and the arrow keys with the control key.
Piecharts, with automatic scaling to indicate the proportions.
Barcharts, with either vertical or horizontal bars, stacked bars or bars side by side.
Timecharts, where bars indicate a time period and milestones or other important moments in time are represented by triangles.
3D plots (both for displaying surfaces and 3D bars)
With version 1.5 a new command has been introduced: plotconfig, which can be used to configure the plot options for particular types of plots and charts (cf. CONFIGURATION OPTIONS) With version 1.8.3 several new features were introduced, which allow more interactivity (cf. INTERACTIVE USE)
You create the plot or chart with one single command and then fill the plot with data:
Create a new xy-plot (configuration type: xyplot).
Name of the existing canvas widget to hold the plot.
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order. For an inverted axis, where the maximum appears on the left-hand side, use: maximum, minimum and a negative stepsize.
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order. For an inverted axis, where the maximum appears at the bottom, use: maximum, minimum and a negative stepsize.
Zero or more options that influence the appearance of the plot:
-xlabels {labels}: Custom labels for the x-axis. If the labels are numeric, they are positioned according to the given scale, otherwise they are positioned with equal distance, based on the number of labels. Note: this only works if the stepsize of the xaxis argument is the empty string.
-ylabels {labels}: Similarly, custom labels for the y-axis.
-box {measures}: See ARRANGING MULTIPLE PLOTS IN A CANVAS
-axesbox {measures}: See ARRANGING MULTIPLE PLOTS IN A CANVAS
Create a new strip chart (configuration type: stripchart). The only difference to a regular XY plot is that the x-axis will be automatically adjusted when the x-coordinate of a new point exceeds the maximum.
Name of the existing canvas widget to hold the plot.
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order. Note that an inverted x-axis is not supported for this type of plot.
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order. For an inverted axis, where the maximum appears at the bottom, use: maximum, minimum and a negative stepsize.
Create a new time-x-plot (configuration type: txplot). The horizontal axis represents the date/time of the data and the vertical axis the values themselves.
Name of the existing canvas widget to hold the plot.
A 3-element list containing the minimum and maximum date/time to be shown and the stepsize (in days) for the time-axis, in this order. Note that an inverted time-axis is not supported.
A 3-element list containing minimum, maximum and stepsize for the vertical axis, in this order. For an inverted axis, where the maximum appears at the bottom, use: maximum, minimum and a negative stepsize.
Create a new xy-plot where the y-axis has a logarithmic scale (configuration type: xlogyplot).
The data should be given as for a linear scale, as the logarithmic transformation is taken of internally.
Name of the existing canvas widget to hold the plot.
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order. For an inverted axis, where the maximum appears on the left-hand side, use: maximum, minimum and a negative stepsize.
A 2-element list containing minimum and maximum for the y-axis, in this order. Note that an inverted logarithmic axis is not supported.
Create a new xy-plot where the x-axis has a logarithmic scale (configuration type: logxyplot).
The data should be given as for a linear scale, as the logarithmic transformation is taken of internally.
Name of the existing canvas widget to hold the plot.
A 2-element list containing minimum and maximum for the x-axis, in this order. Note that an inverted logarithmic axis is not supported.
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order. For an inverted axis, where the maximum appears on the left-hand side, use: maximum, minimum and a negative stepsize.
Create a new xy-plot where both the x-axis and the y-axis have a logarithmic scale (configuration type: logxlogyplot).
The data should be given as for a linear scale, as the logarithmic transformation is taken of internally.
Name of the existing canvas widget to hold the plot.
A 2-element list containing minimum and maximum for the x-axis, in this order. Note that an inverted logarithmic axis is not supported.
A 2-element list containing minimum and maximum for the y-axis, in this order. Note that an inverted logarithmic axis is not supported.
Create a new polar plot (configuration type: polarplot).
Name of the existing canvas widget to hold the plot.
A 2-element list containing maximum radius and stepsize for the radial axis, in this order.
Create a new windrose diagram. The diagram will consist of concentric circles as defined by the radius_data argument and a number of sectors (given by the sectors argument). The sectors are drawn in the "nautical" convention, that is: the first is located at the positive y-axis, the second is to the right and so on in a clockwise direction.
Name of the existing canvas widget to hold the diagram
A 2-element list, the first element is the maximum radius, the second is the step to be used for the circles.
Number of sectors to use (defaults to 16).
Create a new isometric plot, where the vertical and the horizontal coordinates are scaled so that a circle will truly appear as a circle (configuration type: isometric).
Name of the existing canvas widget to hold the plot.
A 2-element list containing minimum, and maximum for the x-axis, in this order.
A 2-element list containing minimum, and maximum for the y-axis, in this order.
Either the stepsize used by both axes or the keyword noaxes to signal the plot that it should use the full area of the widget, to not draw any of the axes.
Create a new histogram (configuration type: histogram).
Name of the existing canvas widget to hold the plot.
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
Create a new 3D plot.
Name of the existing canvas widget to hold the plot.
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
A 3-element list containing minimum, maximum and stepsize for the z-axis, in this order.
Create a new 3D ribbon plot. It is a simplification of the full 3D plot and allows for the drawing of a ribbon only (the x-axis is dropped).
Name of the existing canvas widget to hold the plot.
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
A 3-element list containing minimum, maximum and stepsize for the z-axis, in this order.
Create a new piechart (configuration type: piechart).
Name of the existing canvas widget to hold the plot.
Create a new "spiral pie" (configuration type: spiralpie), a variation on the ordinary piechart. The value is used to scale the radius, rather than the angle. By default the data are sorted.
Name of the existing canvas widget to hold the plot.
Create a new radial chart (the data are drawn as a line connecting the spokes of the diagram) (configuration type: radialchart).
Name of the existing canvas widget to hold the plot.
Names for the spokes.
Scale value to determine the position of the data along the spokes.
Style of the chart (optional). One of:
lines - the default: draw the data as independent polylines.
cumulative - draw the data as polylines where the data are accumulated.
filled - draw the data as filled polygons where the data are accumulated
Create a new barchart with vertical bars (configuration type: vertbars). The horizontal axis will display the labels contained in the argument xlabels. The number of series given by noseries determines both the width of the bars, and the way the series will be drawn.
If the keyword stacked was specified the series will be drawn stacked on top of each other. Otherwise each series that is drawn will be drawn shifted to the right.
The number of series determines the width of the bars, so that there is space of that number of bars. If you use a floating-point number, like 2.2, instead of an integer, like 2, a small gap between the sets of bars will be drawn - the width depends on the fractional part.
Name of the existing canvas widget to hold the plot.
List of labels for the x-axis. Its length also determines the number of bars that will be plotted per series.
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
The number of data series that will be plotted. This has to be an integer number greater than zero (if stacked is not used).
Create a new barchart with horizontal bars (configuration type: horizbars). The vertical axis will display the labels contained in the argument ylabels. The number of series given by noseries determines both the width of the bars, and the way the series will be drawn.
If the keyword stacked was specified the series will be drawn stacked from left to right. Otherwise each series that is drawn will be drawn shifted upward.
Name of the existing canvas widget to hold the plot.
A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
List of labels for the y-axis. Its length also determines the number of bars that will be plotted per series.
The number of data series that will be plotted. This has to be an integer number greater than zero (if stacked is not used).
Create a new barchart with 3D vertical bars (configuration type: 3dbars). The horizontal axis will display the labels per bar. The number of bars given by nobars determines the position and the width of the bars. The colours can be varied per bar. (This type of chart was inspired by the Wiki page on 3D bars by Richard Suchenwirth.)
Name of the existing canvas widget to hold the plot.
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
The number of bars that will be plotted.
Create a new "ribbon chart" (configuration type: 3dribbon). This is a chart where the data series are represented as ribbons in a three-dimensional axis system. Along the x-axis (which is "into" the screen) the names are plotted, each representing a single series. The first plot command draws the furthest series, the second draws the series in front of that and so on.
Name of the existing canvas widget to hold the plot.
Names of the series, plotted as labels along the x-axis
A 3-element list containing minimum, maximum and stepsize for the y-axis (drawn horizontally!), in this order.
A 3-element list containing minimum, maximum and stepsize for the z-axis (drawn vertically), in this order.
The number of bars that will be plotted.
Create a new boxplot with horizontal or vertical boxes (box-and-whiskers) (configuration type: boxplot). Depending on the orientation the x- or y-axis is drawn with labels. The boxes are drawn based on the raw data (see the plot subcommand for this type of plot).
Name of the existing canvas widget to hold the plot.
This is either a 3-element list containing minimum, maximum and stepsize for the x-axis, in this order (when orientation is horizontal), or a list of labels for the x-axis (when orientation is vertical). The length of the label list also determines the number of boxes that can be plotted. The labels are also used in the plot subcommand.
This is either a 3-element list containing minimum, maximum and stepsize for the y-axis, in this order (when orientation is vertical), or a list of labels for the y-axis (when orientation is horizontal). The length of the label list also determines the number of boxes that can be plotted. The labels are also used in the plot subcommand.
If given, "horizontal" or "vertical" determines the orientation of the boxes. This optional value (default: horizontal) also determines the interpretation of the xdata and ydata arguments.
Create a new timechart (configuration type: timechart). The time axis (= x-axis) goes from time_begin to time_end, and the vertical spacing is determined by the number of items to plot.
Name of the existing canvas widget to hold the plot.
The start time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
The end time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
The remaining arguments can be:
The expected/maximum number of items. This determines the vertical spacing. (If given, it must be the first argument after "time_end"
The keyword -barheight and the number of pixels per bar. This is an alternative method to determine the vertical spacing.
The keyword -ylabelwidth and the number of pixels to reserve for the labels at the y-axis.
Create a new Gantt chart (configuration type: ganttchart). The time axis (= x-axis) goes from time_begin to time_end, and the vertical spacing is determined by the number of items to plot. Via the specific commands you can then add tasks and connections between the tasks.
Name of the existing canvas widget to hold the plot.
The start time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
The end time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
The remaining arguments can be:
The expected/maximum number of items. This determines the vertical spacing. (If given this way, it must be the first argument after "time_end")
The expected/maximum width of the descriptive text (roughly in characters, for the actual space reserved for the text, it is assumed that a character is about ten pixels wide). Defaults to 20. (If given this way, it must be the second argument after "time_end").
The keyword -barheight and the number of pixels per bar. This is an alternative method to determine the vertical spacing.
The keyword -ylabelwidth and the number of pixels to reserve for the labels at the y-axis.
Create a plot command that will use a right axis instead of the left axis (configuration type: inherited from the existing plot). The canvas widget must already contain an ordinary plot, as the horizontal axis and other properties are reused. Preferably use the plot command, as with multiple plots in a canvas (also when redefining an existing plot!), the wrong geometry might be used.
To plot data using the right axis, use this new command, to plot data using the left axis, use the original plot command.
Name of the existing canvas widget to hold the plot or preferably the plot command for the plot with the left axis.
A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
Create a command to draw a table. You can use a variety of commands to draw the actual rows of the table, but the number of columns is fixed. (See TABLE CHARTS for an example)
Name of the canvas widget to hold the table.
The headers of the columns in the table. The number of elements determines the number of columns.
If given, either a single value, the width in pixels for all columns or for each column the width of that column. If not given, the table is spread out over the width of the canvas (minus the margins).
Each of the creation commands explained in the last section returns the name of a new object command that can be used to manipulate the plot or chart. The subcommands available to a chart command depend on the type of the chart.
General subcommands for all types of charts. \$anyplot is the command returned by the creation command:
Specify the title of the whole chart.
The text of the title to be drawn.
The position of the title. The default position is "center", but you can alternatively use "left" or "right". You can use multiple titles with different positions.
Specify the subtitle of the whole chart.
The text of the subtitle to be drawn.
Return the name of the canvas (or the alias if you use more than one plot within a canvas). Use this value for the coordinate transformations.
Draws the plot into a file, using PostScript.
Contain the path name of the file to write the plot to.
If the standard PostScript output is used, the option -plotregion can be specifed to save the whole plot (value: bbox) regardless of what is visible in the window. The default (value: window) is to only plot the visible part of the plot.
Optionally you can specify the option -format "some picture format" to store the plot in a different file than a PostScript file. This, however, relies on the Img package to do the actual job.
Note: Because the window holding the plot must be fully visible before Img can successfully grab it, it is raised first. On some systems, for instance Linux with KDE, raising a window is not done automatically, but instead you need to click on the window in the task bar. Similar things happen on Windows XP.
There seems to be something wrong under some circumstances, so instead of waiting for the visibility of the window, the procedure simply waits two seconds. It is not ideal, but it seems to work better.
Specify the title of the (horizontal) x-axis, for those plots that have a straight x-axis.
The text of the x-axis label to be drawn.
Specify the title of the (horizontal) y-axis, for those plots that have a straight y-axis.
The text of the y-axis label to be drawn.
Draw a vertical label to the y-axis. Note: this requires Tk 8.6 or later, for older versions it does nothing.
Text to drawn to the y-axis
Specify the subtext of the (horizontal) x-axis, for those plots that have a straight x-axis. This text is drawn below the primary text.
Since this involves positioning the primary text and setting margins, you need to set the option "usesubtext" for the bottom axis via the plotstyle command. The relevant options are: usesubtext, subtextcolor and subtextfont.
The secondary text of the x-axis label to be drawn.
Specify the subtext of the (vertical) y-axis, for those plots that have a straight y-axis. This text is drawn below the primary text, for both axes on the left and the right.
Since this involves positioning the primary text and setting margins, you need to set the option "usesubtext" for the left or right axis via the plotstyle command. The relevant options are: usesubtext, subtextcolor and subtextfont.
The secondary text of the y-axis label to be drawn.
Specify the subtext of the (vertical) y-axis, for those plots that have a straight y-axis. This text is drawn to the right of the primary text, for both axes on the left and the right.
Since this involves positioning the primary text and setting margins, you need to set the option "usesubtext" for the left or right axis via the plotstyle command. The relevant options are: usevsubtext, vsubtextcolor and vsubtextfont. (Note the "v" to distinguish this option from the text at the top of a vertical axis that is drawn via $anyplot ytext or $anyplot ysubtext.)
The secondary (vertical) text of the y-axis label to be drawn.
Set one or more configuration parameters for the x-axis. The following options are supported:
Set one or more configuration parameters for the y-axis. This method accepts the same options and values as the method xconfig.
Set the background of a part of the plot
Which part of the plot: "axes" for the axes area and "plot" for the inner part. The interpretation depends on the type of plot. Two further possibilities are:
image, in which case a predefined image is loaded into the background of the plot.
gradient, in which case the background is coloured in different shades of the given colour. The "dir" argument specifies the direction in which the colour gets whiter.
Colour for that part or the name of the image if "part" is "image"
The direction of the gradient. One of: top-down, bottom-up, left-right or right-left.
Indicates whether the colour should become brighter (bright) or darker (dark). Defaults to bright
Draw vertical ticklines at each tick location
Colour of the lines. Specifying an empty colour ("") removes them again. Defaults to "black"
Optional argument to specify the dash pattern for the lines. Defaults to "lines" Possible values: lines, dots1, dots2, dots3, dots4, dots5. The actual effect depends on the platform.
Draw horizontal ticklines at each tick location
Colour of the lines. Specifying an empty colour ("") removes them again Defaults to "black"
Optional argument to specify the dash pattern for the lines. Defaults to "lines" Possible values: lines, dots1, dots2, dots3, dots4, dots5. The actual effect depends on the platform.
Add an entry to the legend. The series determines which graphical symbol is to be used. (As a side effect the legend is actually drawn.)
Name of the data series. This determines the colour of the line and the symbol (if any) that will be drawn.
Text to be drawn next to the line/symbol.
Optional argument to specify the vertical spacing between the entries (in pixels). (Note that this spacing will be reused later.)
Remove an entry for a series from the legend and redraw it.
Name of the data series to be removed.
Set one or more options for the legend. The legend is drawn as a rectangle with text and graphics inside.
Add balloon text to the plot (except for 3D plots). The arrow will point to the given x- and y-coordinates. For xy-graphs and such, the coordinates are directly related to the axes; for vertical barcharts the x-coordinate is measured as the number of bars minus 1 and similar for horizontal barcharts.
X-coordinate of the point that the arrow of the balloon will point to.
Y-coordinate of the point that the arrow of the balloon will point to.
Text to be drawn in the balloon.
Direction of the arrow, one of: north, north-east, east, south-east, south, south-west, west or north-west.
Configure the balloon text for the plot. The new settings will be used for the next balloon text.
Add plain text to the plot (except for 3D plots). The text is positioned at the given x- and y-coordinates. For xy-graphs and such, the coordinates are directly related to the axes; for vertical barcharts the x-coordinate is measured as the number of bars minus 1 and similar for horizontal barcharts.
X-coordinate of the text position
Y-coordinate of the text position
Text to be drawn.
Anchor for the text, one of: north, north-east, east, south-east, south, south-west, west or north-west.
Configure the plain text annotation for the plot. The new settings will be used for the next plain text.
Draw a canvas item in the plot where the coordinates are scaled using the coordinate system of the plot. In addition to the standard canvas types, it also supports circles, dots and crosses.
Note: Currently implemented for xy-plots, (vertical and horizontal) barcharts, and piecharts.
Note: To add an entry in the legend for the object, you can use the dataconfig subcommand with a type "rectangle". This will cause a rectangle to be shown.
Name of a standard canvas item or "circle", "dot" or "cross"
The data series it belongs to, used for setting the default drawing options
List of coordinates and drawing options
Remove the lines, symbols and other graphical object associated with the actual data from the plot.
Note: Currently implemented for xy-plots only
Note: The existing options for data series and the legend entry are kept as they were.
Note: Currently there are side effects if the canvas contains more than one plot.
Note: The commands xconfig and yconfig are currently implemented only for XY-plots and only the option -format has any effect.