Stripchart

Name

stripchart - 2D strip chart for plotting x and y coordinate data.

Synopsis

stripchart pathName ?option value? …

Description

The stripchart command creates a strip chart for plotting two-dimensional data (x,y coordinates). It has many configurable components: coordinate axes, elements, legend, grid lines, cross hairs, etc. They allow you to customize the look and feel of the strip chart.

The stripchart is essentially the same as the graph widget. It works almost exactly the very same way.

The use of a strip chart differs in that the X-axis typically refers to time points. Data values are added at intervals. The strip chart lets you automatically maintain a view of the most recent time points. The axis options -shiftby and -autorange control this. You can specify different line styles for data points (see the -styles option).

Introduction

The stripchart command creates a new window for plotting two-dimensional data (x,y coordinates). Data points are plotted in a box displayed in the center of the new window. This is the plotting area. The coordinate axes are displayed in the margins around the plotting area. By default, the legend is displayed in the right margin. The title is displayed in top margin.

A strip chart is composed of several components: coordinate axes, data elements, legend, grid, cross hairs, pens, postscript, and annotation markers.

Syntax

Example

The stripchart command creates a new strip chart.

# Create a new strip chart.  Plotting area is black.
stripchart .s -plotbackground black

A new Tcl command .s is also created. This command can be used to query and modify the strip chart. For example, to change the title of the strip chart to “My Plot”, you use the new command and the widget’s configure operation.

# Change the title.
.s configure -title "My Plot"

A strip chart has several components. To access a particular component you use the component’s name. For example, to add data elements, you use the new command and the element component.

# Create a new element named "line1"
.s element create line1 -xdata {0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0}\
        -ydata {26.18 50.46 72.85 93.31 111.86 128.47 143.14 155.85 166.60 175.38}

The element’s X and Y coordinates are specified using lists of numbers. Alternately, Rbc vectors could be used to hold the X-Y coordinates.

# Create two vectors and add them to the strip chart.
vector xVec yVec
xVec set { 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0 }
yVec set { 26.18 50.46 72.85 93.31 111.86 128.47 143.14 155.85 166.60 175.38 }
.s element create line1 -xdata xVec -ydata yVec

The advantage of using vectors is that when you modify one, the graph is automatically redrawn to display the new values.

# Change the X-Y coordinates of the first point.
set xVec(0) 0.18
set yVec(0) 25.18

An element named line1 is now created in .s. By default, the element’s label in the legend will be also line1. You can change the label, or specify no legend entry, again using the element’s configure operation.

# Don’t display "line1" in the legend.
.s element configure line1 -label ""

You can configure more than just the element’s label. An element has many attributes such as symbol type and size, dashed or solid lines, colors, line width, etc.

.s element configure line1 -symbol square -color red -dashes { 2 4 2 } -linewidth 2 -pixels 2c

Four coordinate axes are automatically created: x, x2, y, and y2. And by default, elements are mapped onto the axes x and y. This can be changed with the -mapx and -mapy options.

# Map "line1" on the alternate Y-axis "y2".
.s element configure line1 -mapy y2

Axes can be configured in many ways too. For example, you change the scale of the Y-axis from linear to log using the axis operation.

# Y-axis is log scale.
.s axis configure y -logscale yes

Axis limits are reset by simply specifying new axis limits using the -min and -max configuration options.

.s axis configure x -min 1.0 -max 1.5
.s axis configure y -min 12.0 -max 55.15

By default, the limits of the axis are determined from data values. To reset back to the default limits, set the -min and -max options to the empty value.

# Reset the axes to autoscale again.
.s axis configure x -min {} -max {}
.s axis configure y -min {} -max {}

It’s common with strip charts to automatically maintain a view of the most recent time points. You can do this my setting the -autorange option.

.s axis configure x -autorange 20.0

If the time points are added in X-coordinates 1.0 unit, only the last twenty time points will be displayed. As more data is added, the view will march along.

Sometimes the rate of data is so high that changing the axis limits with each additional time point is prohibitive. You can use the -shiftby option to define an increment to shift the view when needed.

.s axis configure x -shiftby 15.0

When the view is shifted, it will allow a range of 15 new time points to be added until the axis limits are recomputed.

By default, the legend is displayed in the right margin. You can change this or any other legend configuration options using the legend component.

# Configure the legend font, color, and relief
.s legend configure -position left -relief raised -font fixed -fg blue

To prevent the legend from being displayed, turn on the -hide option.

# Don’t display the legend.
.s legend configure -hide yes

The stripchart widget has simple drawing procedures called markers. They can be used to highlight or annotate data in the strip chart. The types of markers available are bitmaps, images, polygons, lines, or windows. Markers can be used, for example, to mark or brush points. Here is a text marker which labels the data first point. Markers are created using the marker operation.

# Create a label for the first data point of "line1".
.s marker create text -name first_marker -coords {0.2 26.18} -text "start" -anchor se -xoffset -10 -yoffset -10

This creates a text marker named first_marker. It will display the text “start” near the coordinates of the first data point. The -anchor, -xoffset, and -yoffset options are used to display the marker above and to the left of the data point, so that the actual data point isn’t covered by the marker. By default, markers are drawn last, on top of data. You can change this with the -under option.

# Draw the label before elements are drawn.
.s marker configure first_marker -under yes

You can add cross hairs or grid lines using the crosshairs and grid operations.

# Display both cross hairs and grid lines.
.s crosshairs configure -hide no -color red
.s grid configure -hide no -dashes {2 2}

Finally, to get hard copy of the strip chart, use the postscript operation.

# Print the strip chart into file "file.ps"
.s postscript output file.ps -maxpect yes -decorations no

This generates a file file.ps containing the encapsulated PostScript of the strip chart. The option -maxpect says to scale the plot to the size of the page. Turning off the -decorations option indicates that no borders or color backgrounds should be displayed (i.e. the background of the margins, legend, and plotting area will be white).

Stripchart operations

Stripchart components

A strip chart is composed of several components: coordinate axes, data elements, legend, grid, cross hairs, postscript, and annotation markers. Instead of one big set of configuration options and operations, the strip chart is partitioned, where each component has its own configuration options and operations that specifically control that aspect or part of the strip chart.

Axis components

Four coordinate axes are automatically created: two X-coordinate axes (x and x2) and two Y-coordinate axes (y, and y2). By default, the axis x is located in the bottom margin, y in the left margin, x2 in the top margin, and y2 in the right margin.

An axis consists of the axis line, title, major and minor ticks, and tick labels. Major ticks are drawn at uniform intervals along the axis. Each tick is labeled with its coordinate value. Minor ticks are drawn at uniform intervals within major ticks.

The range of the axis controls what region of data is plotted. Data points outside the minimum and maximum limits of the axis are not plotted. By default, the minimum and maximum limits are determined from the data, but you can reset either limit.

You can create and use several axes. To create an axis, invoke the axis component and its create operation.

# Create a new axis called "temperature"
.s axis create temperature

You map data elements to an axis using the element’s -mapy and -mapx configuration options. They specify the coordinate axes an element is mapped onto.

# Now map the temperature data to this axis.
.s element create "temp" -xdata $x -ydata $tempData -mapy temperature

While you can have many axes, only four axes can be displayed simultaneously. They are drawn in each of the margins surrounding the plotting area. The axes x and y are drawn in the bottom and left margins. The axes x2 and y2 are drawn in top and right margins. Only x and y are shown by default. Note that the axes can have different scales.

To display a different axis, you invoke one of the following components: xaxis, yaxis, x2axis, and y2axis. The use operation designates the axis to be drawn in the corresponding margin: xaxis in the bottom, yaxis in the left, x2axis in the top, and y2axis in the right.

# Display the axis temperature in the left margin.
.s yaxis use temperature

You can configure axes in many ways. The axis scale can be linear or logarithmic. The values along the axis can either monotonically increase or decrease. If you need custom tick labels, you can specify a Tcl procedure to format the label as you wish. You can control how ticks are drawn, by changing the major tick interval or the number of minor ticks. You can define non-uniform tick intervals, such as for time-series plots.

Crosshairs component

Cross hairs consist of two intersecting lines (one vertical and one horizontal) drawn completely across the plotting area. They are used to position the mouse in relation to the coordinate axes. Cross hairs differ from line markers in that they are implemented using XOR drawing primitives. This means that they can be quickly drawn and erased without redrawing the entire strip chart.

The following operations are available for cross hairs:

Element components

A data element represents a set of data. It contains x and y vectors containing the coordinates of the data points. Elements can be displayed with a symbol at each data point and lines connecting the points. Elements also control the appearance of the data, such as the symbol type, line width, color etc.

When new data elements are created, they are automatically added to a list of displayed elements. The display list controls what elements are drawn and in what order.

The following operations are available for elements.

Grid component

Grid lines extend from the major and minor ticks of each axis horizontally or vertically across the plotting area. The following operations are available for grid lines.

Legend component

The legend displays a list of the data elements. Each entry consists of the element’s symbol and label. The legend can appear in any margin (the default location is in the right margin). It can also be positioned anywhere within the plotting area.

The following operations are valid for the legend.

Pen components

Pens define attributes (both symbol and line style) for elements. Pens mirror the configuration options of data elements that pertain to how symbols and lines are drawn. Data elements use pens to determine how they are drawn. A data element may use several pens at once. In this case, the pen used for a particular data point is determined from each element’s weight vector (see the element’s -weight and -style options).

One pen, called activeLine, is automatically created. It’s used as the default active pen for elements. So you can change the active attributes for all elements by simply re configuring this pen.

.s pen configure "activeLine" -color green

You can create and use any number of pens. To create a pen, invoke the pen component and its create operation.

.s pen create myPen

You map pens to a data element using either the element’s -pen or -activepen options.

.s element create "line1" -xdata $x -ydata $tempData -pen myPen

An element can use several pens at once. This is done by specifying the name of the pen in the element’s style list (see the -styles option).

.s element configure "line1" -styles {myPen 2.0 3.0}

This says that any data point with a weight between 2.0 and 3.0 is to be drawn using the pen myPen. All other points are drawn with the element’s default attributes.

The following operations are available for pen components.

Postscript component

The strip chart can generate encapsulated PostScript output. There are several configuration options you can specify to control how the plot is generated. You can change the page dimensions and borders. The plot itself can be scaled, centered, or rotated to landscape. The PostScript output can be written directly to a file or returned through the interpreter.

The following postscript operations are available.

Marker components

Markers are simple drawing procedures used to annotate or highlight areas of the strip chart. Markers have various types: text strings, bitmaps, images, connected lines, windows, or polygons. They can be associated with a particular element, so that when the element is hidden or un-hidden, so is the marker. By default, markers are the last items drawn, so that data elements will appear in behind them. You can change this by configuring the -under option.

Markers, in contrast to elements, don’t affect the scaling of the coordinate axes. They can also have elastic coordinates (specified by -Inf and Inf respectively) that translate into the minimum or maximum limit of the axis. For example, you can place a marker so it always remains in the lower left corner of the plotting area, by using the coordinates -Inf,-Inf.

The following operations are available for markers.

Bitmap markers

A bitmap marker displays a bitmap. The size of the bitmap is controlled by the number of coordinates specified. If two coordinates, they specify the position of the top-left corner of the bitmap. The bitmap retains its normal width and height. If four coordinates, the first and second pairs of coordinates represent the corners of the bitmap. The bitmap will be stretched or reduced as necessary to fit into the bounding rectangle.

Bitmap markers are created with the marker’s create operation in the form:

The following options are specific to bitmap markers:

Image markers

A image marker displays an image. Image markers are created with the marker’s create operation in the form:

There may be many option-value pairs, each sets a configuration option for the marker. These same option-value pairs may be used with the marker’s configure operation.

The following options are specific to image markers:

Anchor tells how to position the image relative to the positioning point for the image. For example, if anchor is center then the image is centered on the point; if anchor is n then the image will be drawn such that the top center point of the rectangular region occupied by the image will be at the positioning point. This option defaults to center.

Specifies the image to be drawn. If image is "", the marker will not be drawn. The default is "".

Line markers

A line marker displays one or more connected line segments. Line markers are created with marker’s create operation in the form:

Polygon markers

A polygon marker displays a closed region described as two or more connected line segments. It is assumed the first and last points are connected. Polygon markers are created using the marker create operation in the form:

There may be many option-value pairs, each sets a configuration option for the marker. These same option-value pairs may be used with the marker configure command to change the marker’s configuration. The following options are supported for polygon markers:

Text markers

A text marker displays a string of characters on one or more lines of text. Embedded newlines cause line breaks. They may be used to annotate regions of the strip chart. Text markers are created with the create operation in the form:

Window markers

A window marker displays a widget at a given position. Window markers are created with the marker’s create operation in the form:

Graph component bindings

Specific stripchart components, such as elements, markers and legend entries, can have a command trigger when event occurs in them, much like canvas items in Tk’s canvas widget. Not all event sequences are valid. The only binding events that may be specified are those related to the mouse and keyboard (such as Enter, Leave, ButtonPress, Motion, and KeyPress).

Only one element or marker can be picked during an event. This means, that if the mouse is directly over both an element and a marker, only the uppermost component is selected. This isn’t true for legend entries. Both a legend entry and an element (or marker) binding commands will be invoked if both items are picked.

It is possible for multiple bindings to match a particular event. This could occur, for example, if one binding is associated with the element name and another is associated with one of the element’s tags (see the -bindtags option). When this occurs, all of the matching bindings are invoked. A binding associated with the element name is invoked first, followed by one binding for each of the element’s bindtags. If there are multiple matching bindings for a single tag, then only the most specific binding is invoked. A continue command in a binding script terminates that script, and a break command terminates that script and skips any remaining scripts for the event, just as for the bind command.

The -bindtags option for these components controls addition tag names which can be matched. Implicitly elements and markers always have tags matching their names. Setting the value of the -bindtags option doesn’t change this.

C language API

You can manipulate data elements from the C language. There may be situations where it is too expensive to translate the data values from ASCII strings. Or you might want to read data in a special file format.

Data can manipulated from the C language using BLT vectors. You specify the x and y data coordinates of an element as vectors and manipulate the vector from C. The strip chart will be redrawn automatically after the vectors are updated.

From Tcl, create the vectors and configure the element to use them.

vector X Y
.s element configure line1 -xdata X -ydata Y

To set data points from C, you pass the values as arrays of doubles using the Rbc_ResetVector call. The vector is reset with the new data and at the next idle point (when Tk re-enters its event loop), the strip chart will be redrawn automatically.

#include <tcl.h>
#include <rbc.h>

register int i;
Rbc_Vector *xVec, *yVec;
double x[50], y[50];

/* Get the RBC vectors "X" and "Y" (created above from Tcl) */
if ((Rbc_GetVector(interp, "X", 50, &xVec) != TCL_OK) ||
    (Rbc_GetVector(interp, "Y", 50, &yVec) != TCL_OK)) {
    return TCL_ERROR;
}

for (i = 0; i < 50; i++) {
    x[i] = i * 0.02;
    y[i] = sin(x[i]);
}


/* Put the data into RBC vectors */
if ((Rbc_ResetVector(xVec, x, 50, 50, TCL_VOLATILE) != TCL_OK) ||
    (Rbc_ResetVector(yVec, y, 50, 50, TCL_VOLATILE) != TCL_OK)) {
   return TCL_ERROR;
}

See the vector manual page for more details.

Speed tips

There may be cases where the strip chart needs to be drawn and updated as quickly as possible. If drawing speed becomes a big problem, here are a few tips to speed up displays.

Limitations

Auto-scale routines do not use requested min/max limits as boundaries when the axis is logarithmically scaled.

The PostScript output generated for polygons with more than 1500 points may exceed the limits of some printers (See PostScript Language Reference Manual, page 568). The work-around is to break the polygon into separate pieces.

Future incompatibility

The -mapped options are obsoleted and will be removed. You can achieve the same results using the -hide option instead.

# Works for now.
.s legend configure -mapped no

# Instead use this.
.s legend configure -hide yes