Multiplot Plugin, Version 1.5

The Multiplot plugin provides an easy to use Tcl text interface for plotting one or more datasets (in the vertical axis) versus another axis (the horizontal axis). Many instances of Multiplot can be created concurrently, through the use of handles which are returned when new plots are created. Creation of a new graph doesn't interfere with existing ones.

Author:

Jan Saam
Institute of Biochemistry
Charite Berlin
Germany
saam@charite.de

Contributing Authors:

Axel Kohlmeyer <akohlmey@gmail.com>: support for using multiplot as a non-toplevel widget.
Nadja Lederer <nadja_lederer@gmx.at>: support for deleting objects created with draw.
James Gumbart <gumbart@ks.uiuc.edu>: support for changing the plot range.

Using Multiplot

First you must create a plot using the multiplot command which returns a handle to the new plot. The handle allows to control this plot independently of other plots you might create. 
    set plothandle [multiplot ?reset|list|embed ? ?options?]
multiplot list Lists all existing plothandles
multiplot reset Closes all windows and deletes all namespaces and plothandles
multiplot embed <path> Allows to use multiplot as an embedded widget. You have to give widget path to the parent window as argument. The path to the created widget tree can be retrieved with the 'getpath' command.
Image of NAMD Plot
NAMDPlot results displayed using Multiplot plugin
 

The options are used to define the plot. They are described further below. Note that you can create an empty plot and provide data and configure it any time later using the plothandle.

Once you have a plothandle you can use it to control the plot: 

    $plothandle add|replot|namespace|configure|data|export|quit ?options?
$plothandle add X Y ?options? Adds a dataset to the plot.
$plothandle replot Replots the current data.
$plothandle namespace Returns the current namespace.
$plothandle configure ?options? Modifies the existing plot according to the options. These modifications are silent until you call 'replot' unless you specify the flag -plot !!!
$plothandle nsets Returns the number of datasets in the plot.
$plothandle data Returns all x and y datasets of the plot.
$plothandle xdata Returns all x datasets of the plot.
$plothandle ydata Returns all y datasets of the plot.
$plothandle getpath Returns the widget path to the highest level widget. Useful to manipulating embedded multiplot widgets.
$plothandle export program filename Exports plot to external program.
$plothandle getpath Returns the widget path to the plot window.
$plothandle draw <item> ?options? Draws arbitrary item into canvas. The item can be one of the items defined in Tk's canvas command (arc, bitmap, image, line, oval, polygon, rectangle, text, window). The options are the same as for the corresponding canvas create <item> command (they are directly passed to canvas create). Don't dare to ask me about these options, read the Tk manual! For your convenience I have added wrappers for the oval and rectangle items where you can specify the center coordinates instead of the two opposite corners of the bounding box. These two additional items are called circle and square. The size is controlled by the additional flag -radius (which in case of square denotes the half side length).
$plothandle undraw <tag> Deletes an item that is associated with a tag. The item can be one of the items defined in Tk's 'canvas' command (see draw command above).
$plothandle clear Removes all datasets but does not delete the plothandle.
$plothandle quit Destroys the window of the plot and delete all data.

Options for the plothandle:

-lines Connect datapoint with lines.
-nolines Don't connect datapoint with lines.
-stats Print some statistics of the last added dataset.
-nostats Get rid of the statistics.
-plot Actually plot the data otherwise only the canvas and the axes are drawn This is equivalent to '$plothandle replot'. If you have multiple datasets it is a good idea to add all data first and then plot them all at once since this will be a lot faster.
-autoscale Automatically scale plot to fit all data points.
-xanglescale Use 90 degree as major tic unit for the x-axis.
-yanglescale Use 90 degree as major tic unit for the y-axis.
-set <i> Apply all dataset specific modifications to dataset <i>.
-x <X> Supply the x-values for a dataset in a list.
-y <Y> Supply the y-values for a dataset in a list.
-title <text> Title of the plot.
-xlabel <text> Text for the x-axis label.
-ylabel <text> Text for the y-axis label.
-xmajortics <dist> Distance between two x-axis ticlabels.
-ymajortics <dist> Distance between two y-axis ticlabels.
-xminortics <dist> Distance between two x-axis minor tic marks.
-yminortics <dist> Distance between two y-axis minor tic marks.
-xsize <s> Width of the canvas.
-ysize <s> Height of the canvas.
-xmin <s> Minimum x value; use "auto" to take the minimum x value of all datasets.
-xmax <s> Maximum x value; use "auto" to take the maximum x value of all datasets.
-ymin <s> Minimum y value; use "auto" to take the minimum y value of all datasets.
-ymax <s> Maximum y value; use "auto" to take the maximum y value of all datasets.
-marker <type> Draw markers at datapoints (none|point|circle|square).
-radius <r> Data point marker (radius of circle and point, size of square).
-fillcolor <color> Fill color of datapoint markers.
-linewidth <w> Width of the lines connecting datapoints.
-linecolor <color> Color of the lines connecting datapoints.
-dash <pattern> Draw dashed lines. The dash pattern is specified by one of the following characters "-,._" (uses the same format as -dash for Tk canvas) Note that each line segment is dashed. Hence you'll get a solid line when the datapoints are so dense that the line segments are shorter than the dashes!
-legend <text> Add an entry for this dataset to the legend Note that the legend is drawn in the upper left corner of the plot but you can drag the legend anywhere you want using the mouse.
-hline <{y args}> Draw a horizontal line at position y, args are arguments for the Tk canvas 'create line' command. Through args like '-width 2 -fill red -dash "-"' you can determine the line style.
-hline <{y args}> Draw a vertical line at position x, args are arguments for the Tk canvas 'create line' command. Through args like '-width 2 -fill red -dash "-"' you can determine the line style.

Example:

  package require multiplot
  set x {-2 -1 0 1 2 3 4 5 6 7 8 9 10}
  set y {-2  0 2 3 4 5 5 4 3 2 1 0 1}
  # This plot will be immediately created because we specified -plot
  set plothandle [multiplot -x $x -y $y -title "Example plot" -lines -linewidth 3 -marker point -plot]

  # Now we change the appearence of the existing plot.
  # BUT WE WON'T SEE THIS change until the next replot is requested!
  $plothandle configure -fillcolor yellow -radius 6

  # Let's add a vertical dotted line at x=3
  $plothandle configure -vline {3 -width 2 -fill red -dash "."}

  # And now redraw the plot so that the changes become visible:
  $plothandle replot;

  # It's time to add a second dataset to the same plot
  set y2 {8  7 6 6 5 4 4 3 2 3 4 3 1}
  $plothandle add $x $y2 -fillcolor green -radius 4 -plot

  # Of course we can change the appearence of the the two sets independently:
  $plothandle configure -set 1 -lines -linewidth 4 -dash "," -plot

  # Export to xmgrace, load with 'xmgrace -nxy /tmp/foo.plot'
  $plothandle export xmgrace /tmp/foo.plot

  # Close the plot
  $plothandle quit