NAME

Plotchart - Simple plotting and charting package

SYNOPSIS

package require Tcl ?8.4?

package require Tk ?8.4?

package require Plotchart ?1.9.0?

::Plotchart::createXYPlot w xaxis yaxis

::Plotchart::createStripchart w xaxis yaxis

::Plotchart::createTXPlot w timeaxis xaxis

::Plotchart::createXLogYPlot w xaxis yaxis

::Plotchart::createLogXYPlot w xaxis yaxis

::Plotchart::createLogXLogYPlot w xaxis yaxis

::Plotchart::createPolarplot w radius_data

::Plotchart::createWindrose w radius_data sectors

::Plotchart::createIsometricPlot w xaxis yaxis stepsize

::Plotchart::createHistogram w xaxis yaxis

::Plotchart::create3DPlot w xaxis yaxis zaxis

::Plotchart::create3DRibbonPlot w yaxis zaxis

::Plotchart::createPiechart w

::Plotchart::createRadialchart w names scale style

::Plotchart::createBarchart w xlabels yaxis noseries

::Plotchart::createHorizontalBarchart w xaxis ylabel noseries

::Plotchart::create3DBarchart w yaxis nobars

::Plotchart::create3DRibbonChart w names yaxis zaxis

::Plotchart::createBoxplot w xaxis ylabels

::Plotchart::createTimechart w time_begin time_end args

::Plotchart::createGanttchart w time_begin time_end args

::Plotchart::createRightAxis w yaxis

$anyplot title text

$anyplot saveplot filename args

$anyplot xtext text

$anyplot ytext text

$anyplot vtext text

$anyplot xconfig -option value ...

$anyplot yconfig -option value ...

$anyplot background part colour_or_image dir ?brightness?

$anyplot xticklines colour

$anyplot yticklines colour

$anyplot legend series text

$anyplot legendconfig -option value ...

$anyplot balloon x y text dir

$anyplot balloonconfig args

$anyplot plaintext x y text dir

$anyplot plaintextconfig args

$xyplot plot series xcrd ycrd

$xyplot trend series xcrd ycrd

$xyplot rchart series xcrd ycrd

$xyplot interval series xcrd ymin ymax ?ycentr?

$xyplot box-and-whiskers series xcrd ycrd

$xyplot vector series xcrd ycrd ucmp vcmp

$xyplot vectorconfig series -option value ...

$xyplot dot series xcrd ycrd value

$xyplot dotconfig series -option value ...

$xyplot contourlines xcrd ycrd values ?classes?

$xyplot contourlinesfunctionvalues xvec yvec valuesmat ?classes?

$xyplot contourfill xcrd ycrd values ?classes?

$xyplot contourbox xcrd ycrd values ?classes?

$xyplot colorMap colours

$xyplot grid xcrd ycrd

$xyplot xband ymin ymax

$xyplot yband xmin xmax

$xyplot labeldot x y text orient

$polarplot plot series radius angle

$windrose plot data colour

$plot3d plotfunc function

$plot3d plotfuncont function contours

$plot3d gridsize nxcells nycells

$plot3d plotdata data

$plot3d colours fill border

$plot3d ribbon yzpairs

$plot3d plot yzpairs

$xyplot dataconfig series -option value ...

$pie plot data

$pie colours colour1 colour2 ...

$pie explode segment

$radial plot data colour thickness

$pie colours colour1 colour2 ...

$barchart plot series ydata colour ?dir? ?brightness?

$barchart config -option value ...

$barchart plot series xdata colour ?dir? ?brightness?

$barchart config -option value ...

$barchart plot label yvalue colour

$barchart config -option value ...

$ribbon line xypairs colour

$ribbon area xypairs colour

$boxplot plot label values

$timechart period text time_begin time_end colour

$timechart milestone text time colour

$timechart vertline text time

$timechart hscroll scrollbar

$timechart vscroll scrollbar

$ganttchart task text time_begin time_end completed

$ganttchart milestone text time colour

$ganttchart vertline text time

$ganttchart connect from to

$ganttchart summary text args

$ganttchart color keyword newcolor

$ganttchart font keyword newfont

$ganttchart hscroll scrollbar

$ganttchart vscroll scrollbar

$isoplot plot rectangle x1 y1 x2 y2 colour

$isoplot plot filled-rectangle x1 y1 x2 y2 colour

$isoplot plot circle xc yc radius colour

$isoplot plot filled-circle xc yc radius colour

::Plotchart::viewPort w pxmin pymin pxmax pymax

::Plotchart::worldCoordinates w xmin ymin xmax ymax

::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax

::Plotchart::coordsToPixel w x y

::Plotchart::coords3DToPixel w x y z

::Plotchart::polarCoordinates w radmax

::Plotchart::polarToPixel w rad phi

::Plotchart::pixelToCoords w x y

::Plotchart::pixelToIndex w x y

::Plotchart::determineScale xmin xmax inverted

::Plotchart::determineScaleFromList values inverted

::Plotchart::plotconfig charttype component property value

::Plotchart::createTargetDiagram w limits scale

$target plot series xvalues yvalues

::Plotchart::createPerformanceProfile w max

$performance plot series_and_data_pairs

::Plotchart::plotmethod charttype methodname plotproc

::Plotchart::plotpack w dir args

$anyplot bindplot event command args

$anyplot bindlast series event command

DESCRIPTION

Plotchart is a Tcl-only package that focuses on the easy creation of xy-plots, barcharts and other common types of graphical presentations. The emphasis is on ease of use, rather than flexibility. The procedures that create a plot use the entire canvas window, making the layout of the plot completely automatic.

This results in the creation of an xy-plot in, say, ten lines of code:

    package require Plotchart


    canvas .c -background white -width 400 -height 200


    pack   .c -fill both


    #


    # Create the plot with its x- and y-axes


    #


    set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]


    foreach {x y} {0.0 32.0 10.0 50.0 25.0 60.0 78.0 11.0 } {


        $s plot series1 $x $y


    }


    $s title "Data series"

A drawback of the package might be that it does not do any data management. So if the canvas that holds the plot is to be resized, the whole plot must be redrawn. The advantage, though, is that it offers a number of plot and chart types:

• XY-plots like the one shown above with any number of data series.
• Stripcharts, a kind of XY-plots where the horizontal axis is adjusted automatically. The result is a kind of sliding window on the data series.
• Polar plots, where the coordinates are polar instead of cartesian.
• Histograms, for plotting statistical information.
• Isometric plots, where the scale of the coordinates in the two directions is always the same, i.e. a circle in world coordinates appears as a circle on the screen.

  You can zoom in and out, as well as pan with these plots (Note: this works best if no axes are drawn, the zooming and panning routines do not distinguish the axes), using the mouse buttons with the control key and the arrow keys with the control key.

• Piecharts, with automatic scaling to indicate the proportions.
• Barcharts, with either vertical or horizontal bars, stacked bars or bars side by side.
• Timecharts, where bars indicate a time period and milestones or other important moments in time are represented by triangles.
• 3D plots (both for displaying surfaces and 3D bars)

With version 1.5 a new command has been introduced: plotconfig, which can be used to configure the plot options for particular types of plots and charts (cf. CONFIGURATION OPTIONS) With version 1.8.3 several new features were introduced, which allow more interactivity (cf. INTERACTIVE USE)

PLOT CREATION COMMANDS

You create the plot or chart with one single command and then fill the plot with data:

::Plotchart::createXYPlot w xaxis yaxis

Create a new xy-plot (configuration type: xyplot).

::Plotchart::createStripchart w xaxis yaxis

Create a new strip chart (configuration type: stripchart). The only difference to a regular XY plot is that the x-axis will be automatically adjusted when the x-coordinate of a new point exceeds the maximum.

::Plotchart::createTXPlot w timeaxis xaxis

Create a new time-x-plot (configuration type: txplot). The horizontal axis represents the date/time of the data and the vertical axis the values themselves.

::Plotchart::createXLogYPlot w xaxis yaxis

Create a new xy-plot where the y-axis has a logarithmic scale (configuration type: xlogyplot).

The data should be given as for a linear scale, as the logarithmic transformation is taken of internally.

::Plotchart::createLogXYPlot w xaxis yaxis

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.

::Plotchart::createLogXLogYPlot w xaxis yaxis

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.

::Plotchart::createPolarplot w radius_data

Create a new polar plot (configuration type: polarplot).

::Plotchart::createWindrose w radius_data sectors

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.

::Plotchart::createIsometricPlot w xaxis yaxis stepsize

Create a new isometric plot, where the vertical and the horizontal coordinates are scaled so that a circle will truly appear as a circle (configuration type: isometric).

::Plotchart::createHistogram w xaxis yaxis

Create a new histogram (configuration type: histogram).

::Plotchart::create3DPlot w xaxis yaxis zaxis

Create a new 3D plot.

::Plotchart::create3DRibbonPlot w yaxis zaxis

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).

::Plotchart::createPiechart w

Create a new piechart (configuration type: piechart).

::Plotchart::createRadialchart w names scale style

Create a new radial chart (the data are drawn as a line connecting the spokes of the diagram) (configuration type: radialchart).

::Plotchart::createBarchart w xlabels yaxis noseries

Create a new barchart with vertical bars (configuration type: vertbars). The horizontal axis will display the labels contained in the argument xlabels. The number of series given by noseries determines both the width of the bars, and the way the series will be drawn.

If the keyword stacked was specified the series will be drawn stacked on top of each other. Otherwise each series that is drawn will be drawn shifted to the right.

The number of series determines the width of the bars, so that there is space of that number of bars. If you use a floating-point number, like 2.2, instead of an integer, like 2, a small gap between the sets of bars will be drawn - the width depends on the fractional part.

::Plotchart::createHorizontalBarchart w xaxis ylabel noseries

Create a new barchart with horizontal bars (configuration type: horizbars). The vertical axis will display the labels contained in the argument ylabels. The number of series given by noseries determines both the width of the bars, and the way the series will be drawn.

If the keyword stacked was specified the series will be drawn stacked from left to right. Otherwise each series that is drawn will be drawn shifted upward.

::Plotchart::create3DBarchart w yaxis nobars

Create a new barchart with 3D vertical bars (configuration type: 3dbars). The horizontal axis will display the labels per bar. The number of bars given by nobars determines the position and the width of the bars. The colours can be varied per bar. (This type of chart was inspired by the Wiki page on 3D bars by Richard Suchenwirth.)

::Plotchart::create3DRibbonChart w names yaxis zaxis

Create a new "ribbon chart" (configuration type: 3dribbon). This is a chart where the data series are represented as ribbons in a three-dimensional axis system. Along the x-axis (which is "into" the screen) the names are plotted, each representing a single series. The first plot command draws the furthest series, the second draws the series in front of that and so on.

::Plotchart::createBoxplot w xaxis ylabels

Create a new boxplot with horizontal boxes (box-and-whiskers). The y-axis is drawn with labels. The boxes are drawn based on the raw data (see the plot subcommand for this type of plot).

::Plotchart::createTimechart w time_begin time_end args

Create a new timechart (configuration type: timechart). The time axis (= x-axis) goes from time_begin to time_end, and the vertical spacing is determined by the number of items to plot.

::Plotchart::createGanttchart w time_begin time_end args

Create a new Gantt chart (configuration type: ganttchart). The time axis (= x-axis) goes from time_begin to time_end, and the vertical spacing is determined by the number of items to plot. Via the specific commands you can then add tasks and connections between the tasks.

::Plotchart::createRightAxis w yaxis

Create a plot command that will use a right axis instead of the left axis (configuration type: inherited from the existing plot). The widget (w) must already contain an ordinary plot, as the horizontal axis and other properties are reused. To plot data using the right axis, use this new command, to plot data using the left axis, use the original plot command.

PLOT METHODS

Each of the creation commands explained in the last section returns the name of a new object command that can be used to manipulate the plot or chart. The subcommands available to a chart command depend on the type of the chart.

General subcommands for all types of charts. $anyplot is the command returned by the creation command:

$anyplot title text

Specify the title of the whole chart.

$anyplot saveplot filename args

Draws the plot into a file, using PostScript.

$anyplot xtext text

Specify the title of the (horizontal) x-axis, for those plots that have a straight x-axis.

$anyplot ytext text

Specify the title of the (horizontal) y-axis, for those plots that have a straight y-axis.

$anyplot vtext text

Draw a vertical label to the y-axis. Note: this requires Tk 8.6 or later, for older versions it does nothing.

$anyplot xconfig -option value ...

Set one or more configuration parameters for the x-axis. The following options are supported:

$anyplot yconfig -option value ...

Set one or more configuration parameters for the y-axis. This method accepts the same options and values as the method xconfig.

$anyplot background part colour_or_image dir ?brightness?

Set the background of a part of the plot

$anyplot xticklines colour

Draw vertical ticklines at each tick location

$anyplot yticklines colour

Draw horizontal ticklines at each tick location

$anyplot legend series text

Add an entry to the legend. The series determines which graphical symbol is to be used. (As a side effect the legend is actually drawn.)

$anyplot legendconfig -option value ...

Set one or more options for the legend. The legend is drawn as a rectangle with text and graphics inside.

$anyplot balloon x y text dir

Add balloon text to the plot (except for 3D plots). The arrow will point to the given x- and y-coordinates. For xy-graphs and such, the coordinates are directly related to the axes; for vertical barcharts the x-coordinate is measured as the number of bars minus 1 and similar for horizontal barcharts.

$anyplot balloonconfig args

Configure the balloon text for the plot. The new settings will be used for the next balloon text.

$anyplot plaintext x y text dir

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.

$anyplot plaintextconfig args

Configure the plain text annotation for the plot. The new settings will be used for the next plain text.

Note: The commands xconfig and yconfig are currently implemented only for XY-plots and only the option -format has any effect.

For xy plots, stripcharts, histograms and time-x-plots:

$xyplot plot series xcrd ycrd

Add a data point to the plot.

Note on histograms:

For histograms the x-coordinate that is given is interpreted to be the x-coordinate of the right side of the bar. The first bar starts at the y-axis on the left. To completely fill the range of the x-axis, you should draw a bar at the maximum x-coordinate.

For xy plots:

$xyplot trend series xcrd ycrd

Draw or update a trend line using the data given sofar.

$xyplot rchart series xcrd ycrd

Draw data in the same way as the plot method, but with two lines added that indicate the expected range (+/- 3*standard deviation) of the data.

$xyplot interval series xcrd ymin ymax ?ycentr?

Add a vertical error interval to the plot. The interval is drawn from ymin to ymax. If the ycentr argument is given, a symbol is drawn at that position.

$xyplot box-and-whiskers series xcrd ycrd

Draw a box and whiskers in the plot. If the argument xcrd is a list of several values and the argument ycrd is a single value, a horizontal box is drawn with the quartiles determined from the list of values contained in xcrd.

If, instead, the argument ycrd contains a list of several values and the argument xcrd a single value, then a vertical box is drawn and the quartiles are determined from ycrd. (There must be exactly one list of several values. Otherwise an error is reported.)

The option -boxwidth (default: 10 pixels) determines the width (or height) of the box.

$xyplot vector series xcrd ycrd ucmp vcmp

Draw a vector in the plot. The vector can be given as either cartesian coordinates or as length/angle, where the angle is in degrees and is interpreted according to the mathematical convention or the nautical. (See the vectorconfig subcommand)

$xyplot vectorconfig series -option value ...

] Set the vector drawing options for a particular series

$xyplot dot series xcrd ycrd value

Draw a dot in the plot. The size and colour is determined by the value and by the options set for the series it belongs to. (See the dotconfig subcommand)

$xyplot dotconfig series -option value ...

] Set the dot drawing options for a particular series

$xyplot contourlines xcrd ycrd values ?classes?

Draw contour lines for the values given on the grid. The grid is defined by the xcrd and ycrd arguments. The xcrd argument (resp. ycrd) is expected to be a matrix, implemented as a list of lists which gives the x-coordinates (resp. y-coordinates) of the grid cell corners. The function values are given at these corners. The number of rows in xvec (resp. yvec) is ny and each row contains nx values so that the total number of values in xvec (resp. yvec) is nx * ny. The classes determine which contour lines are drawn. If a value on one of the corners is missing, the contour lines in that cell will not be drawn.

$xyplot contourlinesfunctionvalues xvec yvec valuesmat ?classes?

Draw contour lines for the values given on the grid. The grid is defined by the xvec and yvec arguments. Here, xvec (resp. yvec) is a list of x-coordinates (resp. y-coordinates). The number of values in xvec (resp. yvec) is the number of points in the x-coordinate (resp. y-coordinate). The function values are given at these corners. The classes determine which contour lines are drawn. If a value on one of the corners is missing, the contour lines in that cell will not be drawn.

$xyplot contourfill xcrd ycrd values ?classes?

Draw filled contours for the values given on the grid. (The use of this method is identical to the "contourlines" method).

$xyplot contourbox xcrd ycrd values ?classes?

Draw the cells as filled quadrangles. The colour is determined from the average of the values on all four corners.

$xyplot colorMap colours

Set the colours to be used with the contour methods. The argument is either a predefined colourmap (grey/gray, jet, hot or cool) or a list of colours. When selecting the colours for actually drawing the contours, the given colours will be interpolated (based on the HLS scheme).

$xyplot grid xcrd ycrd

Draw the grid cells as lines connecting the (valid) grid points.

$xyplot xband ymin ymax

Draw a light grey band in the plot, ranging over the full x-axis. This can be used to indicate a "typical" range for the data.

$xyplot yband xmin xmax

Draw a light grey band in the plot, ranging over the full y-axis. This can be used to indicate a "typical" range for the data.

$xyplot labeldot x y text orient

Draw a label and a symbol in the plot. The label will appear near the symbol. The label will be drawn in grey, so as not to be too conspicuous.

You can configure the appearance of the symbol by using the data series name "labeldot": $w dataconfig labeldot -colour red -type symbol -symbol dot

For polar plots:

$polarplot plot series radius angle

Add a data point to the polar plot.

For wind rose diagrams:

$windrose plot data colour

Draw the data contained in the data argument. The data are added to the existing spokes towards the outer circle.

For 3D plots:

$plot3d plotfunc function

Plot a function defined over two variables x and y. The resolution is determined by the set grid sizes (see the method gridsize for more information).

$plot3d plotfuncont function contours

Plot a function defined over two variables x and y using the contour levels in contours to colour the surface. The resolution is determined by the set grid sizes (see the method gridsize for more information).

$plot3d gridsize nxcells nycells

Set the grid size in the two directions. Together they determine how many polygons will be drawn for a function plot.

$plot3d plotdata data

Plot a matrix of data.

$plot3d colours fill border

Configure the colours to use for polygon borders and inner area.

$plot3d ribbon yzpairs

Plot a ribbon based on the pairs of yz-coordinates. The colours for the ribbon itself and the edge are taken from the colours option.

For 3D ribbon plots:

$plot3d plot yzpairs

Plot a ribbon based on the pairs of yz-coordinates. The colours for the ribbon itself and the edge are taken from the colours option.

For xy plots, stripcharts and polar plots:

$xyplot dataconfig series -option value ...

Set the value for one or more options regarding the drawing of data of a specific series.

The following options are allowed:

For piecharts:

$pie plot data

Fill a piechart.

$pie colours colour1 colour2 ...

Set the colours to be used.

$pie explode segment

Explode a segment (that is: move one segment out of the circle). If the segment is indicated as "auto", then you can click on a segment. This will be exploded instead of any previously exploded segment.

For radial charts:

$radial plot data colour thickness

Draw a new line in the radial chart

$pie colours colour1 colour2 ...

Set the colours to be used.

For vertical barcharts:

$barchart plot series ydata colour ?dir? ?brightness?

Add a data series to a barchart.

$barchart config -option value ...

Set options for drawing the bars.

For horizontal barcharts:

$barchart plot series xdata colour ?dir? ?brightness?

Add a data series to a barchart.

$barchart config -option value ...

Set options for drawing the bars.

For 3D barcharts:

$barchart plot label yvalue colour

Add the next bar to the barchart.

$barchart config -option value ...

Set one or more configuration parameters. The following options are supported:

For 3D ribbon charts:

$ribbon line xypairs colour

Plot the given xy-pairs as a ribbon in the chart

$ribbon area xypairs colour

Plot the given xy-pairs as a ribbon with a filled area in front. The effect is that of a box with the data as its upper surface.

For boxplots:

$boxplot plot label values

Add a box-and-whisker to the plot.

For timecharts:

$timechart period text time_begin time_end colour

Add a time period to the chart.

$timechart milestone text time colour

Add a milestone (represented as an point-down triangle) to the chart.

$timechart vertline text time

Add a vertical line (to indicate the start of the month for instance) to the chart.

$timechart hscroll scrollbar

Connect a horizontal scrollbar to the chart. See also the section on scrolling.

$timechart vscroll scrollbar

Connect a vertical scrollbar to the chart. See also the section on scrolling.

For Gantt charts:

$ganttchart task text time_begin time_end completed

Add a task with its period and level of completion to the chart. Returns a list of canvas items that can be used for further manipulations, like connecting two tasks.

$ganttchart milestone text time colour

Add a milestone (represented as an point-down triangle) to the chart.

$ganttchart vertline text time

Add a vertical line (to indicate the start of the month for instance) to the chart.

$ganttchart connect from to

Add an arrow that connects the from task with the to task.

$ganttchart summary text args

Add a summary item that spans all the tasks listed. The graphical representation is a thick bar running from the leftmost task to the rightmost.

Use this command before connecting the tasks, as the arrow would not be shifted down!

$ganttchart color keyword newcolor

Set the colour of a part of the Gantt chart. These colours hold for all items of that type.

$ganttchart font keyword newfont

Set the font of a part of the Gantt chart. These fonts hold for all items of that type.

$ganttchart hscroll scrollbar

Connect a horizontal scrollbar to the chart. See also the section on scrolling.

$ganttchart vscroll scrollbar

Connect a vertical scrollbar to the chart. See also the section on scrolling.

For isometric plots (to be extended):

$isoplot plot rectangle x1 y1 x2 y2 colour

Plot the outlines of a rectangle.

$isoplot plot filled-rectangle x1 y1 x2 y2 colour

Plot a rectangle filled with the given colour.

$isoplot plot circle xc yc radius colour

Plot the outline of a circle.

$isoplot plot filled-circle xc yc radius colour

Plot a circle filled with the given colour.

There are a number of public procedures that may be useful in specific situations: Pro memorie.

COORDINATE TRANSFORMATIONS

Besides the commands that deal with the plots and charts directly, there are a number of commands that can be used to convert world coordinates to pixels and vice versa. These include:

::Plotchart::viewPort w pxmin pymin pxmax pymax

Set the viewport for window w. Should be used in cooperation with ::Plotchart::worldCoordinates.

::Plotchart::worldCoordinates w xmin ymin xmax ymax

Set the extreme world coordinates for window w. The world coordinates need not be in ascending order (i.e. xmin can be larger than xmax, so that a reversal of the x-axis is achieved).

::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax

Set the extreme three-dimensional world coordinates for window w. The world coordinates need not be in ascending order (i.e. xmin can be larger than xmax, so that a reversal of the x-axis is achieved).

::Plotchart::coordsToPixel w x y

Return a list of pixel coordinates valid for the given window.

::Plotchart::coords3DToPixel w x y z

Return a list of pixel coordinates valid for the given window.

::Plotchart::polarCoordinates w radmax

Set the extreme polar coordinates for window w. The angle always runs from 0 to 360 degrees and the radius starts at 0. Hence you only need to give the maximum radius. Note: If the viewport is not square, this procedure will not adjust the extremes, so that would result in an elliptical plot. The creation routine for a polar plot always determines a square viewport.

::Plotchart::polarToPixel w rad phi

Wrapper for a call to ::Plotchart::coordsToPixel, which assumes the world coordinates and viewport are set appropriately. Converts polar coordinates to pixel coordinates. Note: To be useful it should be accompanied by a matching ::Plotchart::worldCoordinates procedure. This is automatically taken care of in the creation routine for polar plots.

::Plotchart::pixelToCoords w x y

Return a list of world coordinates valid for the given window.

::Plotchart::pixelToIndex w x y

Return the index of the pie segment containing the pixel coordinates (x,y)

Furthermore there is a routine to determine "pretty" numbers for use with an axis:

::Plotchart::determineScale xmin xmax inverted

Determine "pretty" numbers from the given range and return a list containing the minimum, maximum and stepsize that can be used for a (linear) axis.

::Plotchart::determineScaleFromList values inverted

Determine "pretty" numbers from the given list of values and return a list containing the minimum, maximum and stepsize that can be used for a (linear) axis.

MISSING VALUES

Often data that need to be plotted contain gaps - in a series of measurement data, they can occur because the equipment failed, a sample was not collected correctly or for many other reasons. The Plotchart handles these gaps by assuming that one or both coordinates of such data points are an empty string:

    #


    # Create the plot with its x- and y-axes


    #


    set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]


    foreach {x y} {0.0 32.0 10.0 {} 25.0 60.0 78.0 11.0 } {


        $s plot series1 $x $y


    }

The effect varies according to the type of plot:

• For xy-plots, radial plots and strip charts the missing data point causes a gap in the line through the points.
• For barchats, missing values are treated as if a value of zero was given.
• For time charts and Gantt charts missing values cause errors - there is no use for them there.

OTHER OUTPUT FORMATS

Besides output to the canvas on screen, the module is capable, via canvas postscript, of producing PostScript files. One may wonder whether it is possible to extend this set of output formats and the answer is "yes". This section tries to sum up the aspects of using this module for another sort of output.

One way you can create output files in a different format, is by examining the contents of the canvas after everything has been drawn and render that contents in the right form. This is probably the easiest way, as it involves nothing more than the re-creation of all the elements in the plot that are already there.

The drawback of that method is that you need to have a display, which is not always the case if you run a CGI server or something like that.

An alternative is to emulate the canvas command. For this to work, you need to know which canvas subcommands are used and what for. Obviously, the create subcommand is used to create the lines, texts and other items. But also the raise and lower subcommands are used, because with these the module can influence the drawing order - important to simulate a clipping rectangle around the axes. (The routine DrawMask is responsible for this - if the output format supports proper clipping areas, then a redefinition of this routine might just solve this).

Furthermore, the module uses the cget subcommand to find out the sizes of the canvas. A more mundane aspect of this is that the module currently assumes that the text is 14 pixels high and that 80 pixels in width suffice for the axis' labels. No "hook" is provided to customise this.

In summary:

• Emulate the create subcommand to create all the items in the correct format
• Emulate the cget subcommand for the options -width and -height to allow the correct calculation of the rectangle's position and size
• Solve the problem of raising and lowering the items so that they are properly clipped, for instance by redefining the routine DrawMask.
• Take care of the currently fixed text size properties

SPECIAL EFFECTS

As an example of some special effects you can achieve, here is the code for a plot where the area below the data line varies in colour:

canvas .c  -background white -width 400 -height 200
pack .c -fill both
set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]
$s background gradient green top-down
$s dataconfig series1 -filled up -fillcolour white
$s plot series1  0.0 20.0
$s plot series1 10.0 20.0
$s plot series1 30.0 50.0
$s plot series1 35.0 45.0
$s plot series1 45.0 25.0
$s plot series1 75.0 55.0
$s plot series1 100.0 55.0
$s plaintext 30.0 60.0 "Peak" south

The trick is to fill the background with a colour that changes from green at the top to white at the bottom. Then the area above the data line is filled with a white polygon. Thus the green shading varies with the height of the line.

ROOM FOR IMPROVEMENT

In this version there are a lot of things that still need to be implemented:

•

More robust handling of incorrect calls (right now the procedures may fail when called incorrectly):

RESIZING

Plotchart has not been designed to create plots and charts that keep track of the data that are put in. This means that if an application needs to allow the user to resize the window holding the plot or chart, it must take care to redraw the complete plot.

The code below is a simple example of how to do that:

package require Plotchart
grid [canvas .c -background white] -sticky news
grid columnconfigure . 0 -weight 1
grid rowconfigure . 0 -weight 1
bind .c <Configure> {doResize}
proc doPlot {} {


    #


    # Clean up the contents (see also the note below!)


    #


    .c delete all


    #


    # (Re)draw the bar chart


    #


    set p [::Plotchart::createBarchart .c {x y z} {0 100 10} 3]


    $p plot R {10 30 40} red


    $p plot G {30 40 60} green
}
proc doResize {} {


    global redo


    #


    # To avoid redrawing the plot many times during resizing,


    # cancel the callback, until the last one is left.


    #


    if { [info exists redo] } {


        after cancel $redo


    }


    set redo [after 50 doPlot]
}

Alternatively, you can use the xyplot package which is built on top of Plotchart. This package supports zooming in and zooming out, as well as resizing the plot as a whole. Here is a small demonstration program:

# xyplot_demo.tcl --
#     Demonstration of the xyplot package
#
package require xyplot
set xydata1 {}
set xydata2 {}
set xydata3 {}
set xydata4 {}
for { set i 0 } { $i < 1024 } { incr i } {


    lappend xydata1 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2))}]


    lappend xydata2 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6))}]


    lappend xydata3 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6) + 0.0625 * sin($i/256.0*3.1415*10))}]


    lappend xydata4 [expr {$i-1000}] [expr {$i * sin($i/4096.0*3.1415*2) * (sin($i/256.0*3.1415*2) + 0.25 * sin($i/256.0*3.1415*6) + 0.0625 * sin($i/256.0*3.1415*10) + 0.015625 * sin($i/256.0*3.1415*14))}]
}
set xyp [xyplot .xyp -xformat "%5.0f" -yformat "%5.0f" -title "XY plot testing" -background gray90]
pack $xyp -fill both -expand true
set s1 [$xyp add_data sf1 $xydata1 -legend "Serie 1 data" -color red]
set s2 [$xyp add_data sf2 $xydata2 -legend "Serie 2 data" -color green]
set s3 [$xyp add_data sf3 $xydata3 -legend "Serie 3 data" -color blue]
set s4 [$xyp add_data sf4 $xydata4 -legend "Serie 4 data" -color orange]
set xyp2 [xyplot .xyp2 -xticks 8 -yticks 4 -yformat %.2f -xformat %.0f]
pack $xyp2 -fill both -expand true
set s1 [$xyp2 add_data sf1 $xydata1]
set s2 [$xyp2 add_data sf2 $xydata2]
set s3 [$xyp2 add_data sf3 $xydata3]
set s4 [$xyp2 add_data sf4 $xydata4]

ZOOMING IN

As the Plotchart package does not keep track of the data itself, rescaling an existing plot - for instance when zooming in - would have to be done by redefining the plot and redrawing the data. However, the canvas widget offers a way out by scaling and moving items, so that zooming in becomes a bit simpler.

Whether zooming is indeed useful, depends on the type of plot. Currently it is defined for XY-plots only. The method is called "rescale" and simply redraws the axes and scales and moves the data items so that they conform to the new axes. The drawback is that any symbols are scaled by the same amount. The rescale method works best for plots that only have lines, not symbols.

The method works very simply:

   $p rescale {newxmin newxmax newxstep} {newymin newymax newystep}

CONFIGURATION OPTIONS

The command plotconfig can be used to set all manner of options. The syntax is:

::Plotchart::plotconfig charttype component property value

Set a new value for the property of a component in a particular chart or plot type or query its current value. Each argument is optional.

Below is a more detailed list of the components and properties:

•

Axes come in a wide variety:

• The margin is important for the layout. Currently only the rectangular plots allow the margins to be set: left, right, top and bottom. The values are in pixels.
• The text component is meant for any text appearing via the plaintext subcommand. The properties are: textcolor, font and anchor (positioning of the text relative to the given coordinates).
• The background has two properties: outercolor, the colour outside of the actual plot, and innercolor, the colour inside the plot. (Note: only "outercolor" has now been implemented).
• The legend has three properties: background, border and position. See the legend subcommand for the meaning.

See the examples in plotdemos7.tcl for it use.

SCROLLING FOR TIMECHARTS AND GANTT CHARTS

For two types of plots automatic scrolling management has been implemented: timecharts and Gantt charts. The subcommands hscroll and vscroll associate (existing) scrollbars to the plot, in much the same way as for text and canvas widgets.

Once the association is made, the scrollbars are automatically updated if:

• You add an item with a period wider than the current one.
• You add a vertical line for a time beyond the current bounds.
• You add an extra item beyond the number that was used to create the chart.

For instance:

package require Plotchart
canvas .c -width 400 -height 200
scrollbar .y -orient vertical
scrollbar .x -orient horizontal
grid .c .y -sticky news
grid .x    -sticky news
source plotchart.tcl
set s [::Plotchart::createTimechart .c "1 january 2004"  "31 december 2004" 4]
$s period "Spring" "1 march 2004" "1 june 2004" green
$s period "Summer" "1 june 2004" "1 september 2004" yellow
$s vertline "1 jan" "1 january 2004"
$s vertline "1 apr" "1 april 2004"
$s vertline "1 jul" "1 july 2004"
$s vertline "1 oct" "1 october 2004"
$s vertline "1 jan" "1 january 2005"
$s vertline "1 apr" "1 april 2005"
$s vertline "1 jul" "1 july 2005"
$s milestone "Longest day" "21 july 2004"
$s milestone "Longest day 2" "21 july 2004"
$s milestone "Longest day 3" "21 july 2004"
$s milestone "Longest day 4" "21 july 2004"
$s milestone "Longest day 5" "21 july 2004"
$s milestone "Longest day 6" "21 july 2004"
$s title "Seasons (northern hemisphere)"
$s vscroll .y
$s hscroll .x

SPECIALISED PLOTS

Most of the plot and chart types described above have a fairly general use and you simply prepares the data to be plotted yourself. This section describes several plot types that are more specialised, in the sense that they have specific purposes and you pass raw data that are then processed in the plotting routines.

Currently there are the following types:

• Target diagrams are used to assess the capacity of numerical models to reproduce measurement data. They are described in detail in:

  Jason K. Joliff et al.
  
  
      Summary diagrams for coupled hydrodynamic-ecosystem model skill assessment
  
  
      Journal of Marine Systems 76 (2009) 64-82
  
  
      DOI: 10.1016/j.jmarsys.2008.05.014
      

• Performance profiles are used for comparing the performance of numerical methods or implementations thereof with each other. For more information:

  Desmond Higham and Nicholas Higham
  
  
      Matlab Guide
  
  
      SIAM, 2005, Philadephia
      

Most of the general methods for XY-plots work for these plots as well, but their creation and the methods to plot the data are very specific.

::Plotchart::createTargetDiagram w limits scale

Create a new target diagram with circles indicating specific limits. The x-axis represents the unbiased "root-mean-square difference" (typically varying between -1 and 1) and the y-axis represents the normalised bias.

Data points closer to the origin represent better results than data points further away.

$target plot series xvalues yvalues

The plot method takes two series of data of the same length, the first one representing the model results, the second one represent the measurements or, more general, the data that need to be reproduced.

::Plotchart::createPerformanceProfile w max

Create a diagram to show the performance of various numerical methods (or solvers). The idea is to first run these methods on a set of problems and measure their performance. The smaller the number the better. Then these methods are compared via a so-called performance profile: the data are scaled and ordered, such that the best method ends up highest.

Because of the nature of the plot all data must be given at once.

$performance plot series_and_data_pairs

Plot the data for each given method. The data are identified by the series name and the appearance is controlled via prior dataconfig subcommand.

The command plotmethod can be used to add new methods for a particular plot or chart type. It is intended to help you develop specialised graphical displays.

::Plotchart::plotmethod charttype methodname plotproc

Adds a new method for the given plot or chart type. The method is implemented by the command or procedure given in the plotproc argument. The procedure will be called with two extra arguments, the name of the created plot and the canvas widget that contains (see the example below).

Here is a trivial example of how to use this:

#
# The custom method "doodle" always adds the text "DOODLE"
# to the plot
#
proc doodle {p w x y} {


    $p plaintext $x $y "DOODLE"
}
::Plotchart::plotmethod xyplot doodle doodle
#
# Use it
pack [canvas .c]
set p [::Plotchart::createXYPlot .c {0 100 10} {0 20 5}]
$p doodle 40 10

CONTROL DISPLAYS

TODO

ARRANGING MULTIPLE PLOTS IN A CANVAS

The command plotpack allows you to copy the contents of a plot into another canvas widget. This canvas widget does not act as a composite plot, but it can be saved as a PostScript file for instance: Note: the command simply takes a snapshot of the plots/charts as they are at that moment.

::Plotchart::plotpack w dir args

Copy the contents of the plots/charts into another widget, in a manner similar to the pack geometry manager.

For example:

    set p1 [createXYPlot ...]


    set p2 [createBarchart ...]


    ... fill the plots ...


    toplevel .t


    pack [canvas .t.c2 -width ...]


    #


    # Copy the two plots above each other in the new canvas


    #


    plotpack .t.c2 top $p1 $p2

INTERACTIVE USE

Plotchart has several features for interactive use (cf. NOTES ON TAGS):

• The legend can be moved around by pressing mouse button 1 in the legend's box and keeping it down.
• You can use the bindplot and bindlast commands to define actions that are to be taken when the user clicks on an element of the plot or chart. (see below, see also the sample code in plotdemos12.tcl)
• Piecharts can show an "exploded" segment that you can select with mouse button 1.

If you require different forms of interaction, not covered by Plotchart itself, you can use the tags on the various canvas elements to define other bindings.

The bindplot and bindlast are defined as follows:

$anyplot bindplot event command args

Register a command that will be run whenever the given event occurs in the plot.

$anyplot bindlast series event command

Register a command that will be run when the event occurs within the neighbourhood of the last point added to the given series. (You can use directly after inserting a data point. All such commands will remain active).

Here is an example - show the values of the data points in an annotation (from the sample code in plotdemos12.tcl):

#
# Procedure for showing an annotation
#
proc showAnnotation {xcoord ycoord plot w} {


    $plot balloon $xcoord $ycoord "Data point: [format "%.3f, %.3f" $xcoord $ycoord]" north


    after 2000 [list removeAnnotation $w]
}
#
# Procedure for erase an annotation
#
proc removeAnnotation {w} {


    # Use the tags to remove all annotations


    $w delete BalloonText


    $w delete BalloonFrame
}
#
# Create a simple plot and a label
#
pack [canvas .c -bg white] [label .l -textvariable coords]
set p [::Plotchart::createXYPlot .c {0 1000 200} {0 10 1}]
$p dataconfig series1 -type both -symbol cross
foreach x {1 2 5 10 20 50 100 200 500 1000} {


    $p plot series1 $x [expr {log($x)}]


    #


    # Show the annotation for each data point


    #


    $p bindlast series1 <Enter> [list showAnnotation $p %W]
}

NOTES ON TAGS

The implementation of Plotchart relies heavily on the canvas's ability to identify graphical objects by tags and to change the drawing order of the objects. This section documents the tags that are used.

(Note: the tags are not always used consistently - see the notes appearing with the various tags. This section describes the current state.)

General graphical objects:

• mask - Used to manipulate the opaque rectangles that ensure data outside the viewport are not shown.
• topmask, horizmask, vertmask - specialised tags, used for scrollable plots.
• title - Used for title strings. BalloonText, BalloonFrame - Used to manipulate balloon text. PlainText - Used to manipulate ordinary text without any decoration. background - Tag used for gradient and image backgrounds (and for gradient-filled bars). xaxis, yaxis - Tags used for all objects related to horizontal or vertical axes. (also: both for numerical axes and axes with labels as in barcharts). Note, however, that the text along the axes has no particular tag. raxis - Tag used for all objects related to a right axis. taxis - Tag used for all objects related to a time axis. axis3d - Tag used for 3D axes xtickline, ytickline - Tags used for ticklines. legend, legengb, legendobj - Tags used for the legend. The latter is used to manipulate the legend as a whole. legend_series - Tag used to control the appearance of the legend entry ("series" should be replaced by the series name).

XY-plots (all types of axes):

•

data - The general tag to identify graphical objects associated with data. data_seriesname - The tag specific to a data series ("seriesname" should be replaced). band - The horizontal or vertical band drawn with the xband otr yband subcommands have this tag by the actual name).

Items such as labelled dots only have the "data" tag.

Piecharts:

•

segment_segmentnumber - The tag identifying the segment, the string "segmentnumber" should be replaced by the actual number. This tag is used to explode the segments.

Barcharts:

Barcharts use the same tags as xy-plots (but for gradient-filled bars the data_seriesname is not used).

Histograms and isometric plots:

Currently the only tag used is "data".

Time-charts:

As these plots are scrollable, several tags are used specific to the scrolling: vertscroll, horizscroll, below, lowest, above, timeline, tline. Each item also has a tag of the form "item_number", where "number" is to be replaced by the actual sequence number of the item.

Gantt charts:

In addition to the tags described for the time-charts, the following tags are used: description, completed, summary and summarybar.

Radial charts and polar plots:

Currently the radial lines indicating the grid have no tags. The graphical objects associated with data only have the "data" tag.

Windroses:

Only the tag data_number is currently used ("number" should be replaced by the sequence number of the data, starting at 0.

Contour and isoline plots:

No tags are used.

3D plots and 3D ribbon plots:

No tags are used for the data objects, only for the axes.

Charts decorated with 3D effects:

The following tags are used to identify various types of graphical objects: platform, background, d, u, ticklines.

The text associated with the bars has no tags. The ribbon lines and areas have no tags either.

TODO - SOME PRIVATE NOTES

I have the following wishlist:

• Isometric plots - allow new items to be implemented easily.
• A general 3D viewer - emphasis on geometry, not a ray-tracer.
• Several improvements for boxplots:

KEYWORDS

3D bars, 3D surfaces, bar charts, charts, coordinate transformations, coordinates, graphical presentation, isometric plots, pie charts, plotting, polar plots, strip charts, time charts, xy-plots

COPYRIGHT

Copyright (c) 2010 Arjen Markus <arjenmarkus@users.sourceforge.net>