Quick Reference

3.8 Writing new plotting functions

You may want to plot something not directly supported by one of the plotting primitive functions. Usually, you can write your own plotting function to perform such a task. As an example, suppose you want to plot a histogram -- that is, instead of a smooth curve connecting a series of (x,y) points, you want to draw a line consisting of a horizontal segment at each value of y, joined by vertical segments (this is sometimes called a Manhattan plot for its resemblance to the New York City skyline).

You quickly realize that to draw a histogram, you really need the x values at the vertical segments. This function works:

func plh(y,x) { yy = xx = array(0.0, 2*numberof(y)); yy(1:-1:2) = yy(2:0:2) = y; xx(2:-2:2) = xx(3:-1:2) = x(2:-1); xx(1) = x(1); xx(0) = x(0); plg, yy, xx; }

Notice that the x array must have one more element that the y array; otherwise the assignment operations to xx will fail for lack of conformability.

A more sophistocated version would include the possibility for the caller to pass plh the keywords accepted by the plg function. Also, you might want to allow y to have one more element than x instead of x one more than y, in order to start and end the plot with a vertical segment instead of a horizontal segment. Here is a more complete version of plh:

func plh(y,x,marks=,color=,type=,width=) /* DOCUMENT plh, y, x plot a histogram (Manhattan plot) of Y versus X. That is, the result of a plh is a set of horizontal segments at the Y values connected by vertical segments at the X values. If X has one more element than Y, the plot will begin and end with a horizontal segment; if Y has one more element than X, the plot will begin and end with a vertical segment. The keywords are a subset of those for plg. KEYWORDS: marks, color, type, width SEE ALSO: plg */ { swap = numberof(x)<numberof(y); if (swap) { yy = y; y = x; x = yy; } yy = xx = array(0.0, 2*min(numberof(y),numberof(x))); yy(1:-1:2) = yy(2:0:2) = y; xx(2:-2:2) = xx(3:-1:2) = x(2:-1); xx(1) = x(1); xx(0) = x(0); if (swap) { y = yy; yy = xx; xx = y } plg, yy, xx, marks=marks, color=color, type=type, width=width; }

The point of an interpreted language is to allow you to easily alter the user interface to suit your own needs. Designing an interface for a wide variety of users is much harder than designing one for your own use. (The first version of plh might be adequate for your own use; I wouldn't release less than the second version to a larger public.) Linking your routines to the Yorick help command via a document comment is useful even if never anticipate anyone other than yourself will use them. Public interface routines should always have a document comment.