PLOTXY and other Bob Parker programs (CONTOUR, COLOR)

Bob Parker wrote a series of plotting programs that became
widely used in the geophysical community because of their
versatility and ease of use.  They are written in Fortran
and can be easily copied to and run on any UNIX machine that
supports Fortran.  PLOTXY is the most widely used of these
programs and there was a period when a fair fraction of the
geophysical papers in JGR contained PLOTXY plots.  The use
of PLOTXY is decreasing now, as other plotting packages
become more widely available, but I was still easily able to
find 3 articles in recent JGRs that have PLOTXY plots.

The strength of these programs continues to be that they are
very good at a single purpose--making high quality plots.  They
are not part of a much larger software package that does many
other things.  In addition, they have sensible default values
but give the user considerable control over the appearance of
the plots if this is desired.

Finally they have been almost completely debugged over the
years and are exceptionally well documented in Bob Parker's
own inimitable style.  Links to this documentation as well
as downloading instructions can found at:

http://mahi.ucsd.edu/parker/Software/software.html


PLOTXY

Let's start with a simple example.  Suppose we have four
points in an ascii data file called "data4"

1.0  1.0
2.0  1.9
3.0  3.2
4.0  4.0

To plot these points using plotxy, enter:

plotxy
file data4
read
plot
stop

Of course, we can also do this as a UNIX script:
                                                     (xycmd1)
plotxy << !
file data4
read
plot
stop
!

We will not include the first and last lines in the examples
that follow, but they are best implemented as scripts.

The output to the plot is written to a Postscript file with
the default name "mypost" which can be previewed to the 
screen using pageview or ghostview.

Now let's explore ways that we might want to change the
way that this is plotted.  My own preference is almost
always to have a complete frame around the plot.  This
can be done using the frame command, i.e.,

frame on

We also might want the plot dimensions to be smaller.  We can 
fix the size of the x- and y-axes in inches using the xlim and 
ylim commands:

xlim 4
ylim 4

Putting this all in the same script, we have:
                                                     (xycmd2)
file data4
read
frame on
xlim 4
ylim 4
plot
stop

The plot now looks too close to the lower left corner of the page.
The position on the page of the lower left corner of the plot can
be changed by added arguments to the plot command:

plot 2.5 3

In this case the plot will be positioned such that the lower left
corner is 2 inches from the left edge of the paper and 3 inches from the
bottom edge.  While we're at it, let's add some axes labels.  This
can be done with xlabel and ylabel:

xlab Observed amplitude (m/s^2)
ylab Predicted amplitude (m/s^2)

Adding this to our script, we have:
                                                     (xycmd3)
file data4
read
frame on
xlim 4
ylim 4
xlab Observed acceleration (m/s^2)
ylab Predicted acceleration (m/s^2)
plot 2.5 3
stop

Next, we may decide that we want to show the individual data
points and not connect them with a line.  To do this, use the
symbol command:

symbol plus    (=plus, cross, circle, square, triangle, etc.)

A wide variety of symbols are available.  If desired, the
symbol height in inches can be entered as a second argument.
The prefix "filled" can be used in front of circle, square
and triangle.  Note that the symbol command must go before the
read command because plotxy permits reading from multiple data
file before plotting, using a different symbol in each case.  We 
also decide that we want to add a title using the title command:

title A Good Experiment

so our script now is:
                                                     (xycmd4)
file data4
symbol plus
read
frame on
xlim 4
ylim 4
xlab Observed acceleration (m/s^2)
ylab Predicted acceleration (m/s^2)
title A Good Experiment
plot 2.5 3
stop

We note that the first point is too close to the corner.  We
can change the axes limits by adding more arguments to the
xlim and ylim commands:

xlim 4 0.5 4.5
ylim 4 0.5 4.5

We also don't like the way s^2 looks so we take advantage
of the PLOTXY ability to implement superscripts:

xlab Observed acceleration (m/s\sup{2})
ylab Predicted acceleration (m/s\sup{2})

and our script becomes:
                                                       (xycmd5) 
file data4
symbol 4
read
frame on
xlim 4 0.5 4.5
ylim 4 0.5 4.5
xlab Observed acceleration (m/s\sup{2})
ylab Predicted acceleration (m/s\sup{2})
title A Good Experiment
plot 2.5
stop

Next, let's reduce the size of the characters slightly, make the 
data points red, connect them with a curved, dash line, and add
a reference note:
                                                       (xycmd6)
CHAR .12
file data4
symbol 4
COLOR red
read
file data4
SMOOTH
COLOR black
DASH .1 .1
read
frame on
xlim 4 0.5 4.5
ylim 4 0.5 4.5
xlab Observed acceleration (m/s\sup{2})
ylab Predicted acceleration (m/s\sup{2})
title A Good Experiment
NOTE (0.5 4.2) Data from Klinger (1995)
plot 2.5 3
stop

The color command can specify red, blue, green, brown, orange,
purple, black, gray, white, and lightgray.  The smooth command
turns off the current symbol and draws a smooth line through
the next data points to be read.  The dash command plots the
next data series as a dashed line with visible segments 0.1
inches long (the first argument) and missing segments 0.1
inches long (the second argument).

As a final example in this series, let's add another plot on
the same page.  This will be of the same data set but converted
to cm/s^2.
                                                       (xycmd7)
char .12
file data4
symbol plus
color red
read
file data4
smooth
color black
dash .1 .1
read
frame on
xlim 4 0.5 4.5
ylim 4 0.5 4.5
xlab Observed acceleration (m/s\sup{2})
ylab Predicted acceleration (m/s\sup{2})
title A Good Experiment
note (0.5 4.2) Data from Klinger (1995)
plot 2.5 5.5

file data4
dash 0 0
symbol plus 0.2
color blue
AFFINE 100 0 100 0
read
color black
xlim 4 50 450
ylim 2.5 50 450
xlab Observed acceleration (cm/s\sup{2})
ylab Pred. accel. (cm/s\sup{2})
title 
note
plot 0 -3.5

stop


Note that the same data series can be read multiple times.  When plot
is called more than once, the plot coordinates are the offsets from
the previous plot position, not absolute coordinates.  Note the
use of the "affine" command to scale the data by 100 upon reading 
in order to convert to cm.

The PLOTXY documentation is very good and there is no need to
repeat all of it here.  A few random points:

The program only reads the first four characters of the commands;
thus "affi" and "affine" do the same thing.  It's your choice if
you prefer to spell out the complete command.

You can change the format of the read statement using the "format"
and "mode" commands to read different columns of the input file.
I find "mode 20" particularly useful because it permits the x and
y columns to be directly specified.

In addition to superscripts and subscripts, Greek letters are
also supported.  Just enclose them in backslashes, e.g., \theta\, etc.

If you want to read only part of a file, or skip over header information,
use the "skip" and "read" commands, e.g.,

skip 5
read 20

will skip the first 5 lines of the file and then read the next 20 lines.

One interesting aspect of plotxy is that it was originally written for
a pen plotter. (If you don't know what this is, you're lucky!  Ask in a 
computer museum some time...)  The distinctive plotxy font is not a
standard Postscript font.  The characters are actually "drawn" on the
paper using a series of move and draw commands.  You will notice this
if you try to edit the Postscript file to change one of the axis labels
and do a search for the text (you won't find it!).


CONTOUR

This program makes contour plots of data sampled at regular intervals
in a rectangular array.  For example, suppose we have a data file
called "data.30.20" that contains the following:

745 800 849 892 927 956 976 988 992 988 976 956 927 892 849 800 745 684 620 551
785 833 874 909 936 956 968 972 968 956 936 909 874 833 785 732 673 611 544 475
806 846 878 904 923 934 938 934 923 904 878 846 806 761 711 655 596 533 467 400
806 837 861 878 889 892 889 878 861 837 806 770 728 681 630 575 517 456 394 331
784 806 822 831 834 831 822 806 784 757 725 687 645 599 549 497 443 387 330 274
741 755 763 766 763 755 741 723 699 671 638 602 562 519 474 427 378 329 280 231
680 686 689 686 680 668 653 633 610 583 553 520 485 448 409 369 328 287 247 208
602 604 602 597 588 576 561 544 523 500 474 447 419 389 358 327 296 265 235 205
513 512 509 503 495 485 472 458 443 426 407 388 367 347 325 304 283 263 243 224
418 416 414 409 404 398 391 383 375 365 355 345 335 324 313 303 292 282 273 264
322 322 322 322 322 322 322 322 322 322 322 322 322 322 322 322 322 322 322 322
231 235 241 247 254 262 270 280 290 300 310 321 332 342 353 363 372 381 389 396
150 160 173 187 202 219 238 257 278 298 320 341 362 382 402 421 438 454 469 481
 84 101 122 145 171 198 226 256 287 318 349 380 410 440 467 493 517 538 557 573
 35  62  92 125 160 197 236 276 317 358 398 437 475 511 544 575 603 627 648 665
  7  43  83 126 171 218 267 316 365 414 461 507 551 591 629 662 692 717 737 752
  0  46  95 148 202 258 315 371 428 483 535 586 633 676 715 749 778 801 818 829
 15  70 128 189 251 314 377 440 501 559 615 668 716 759 797 829 855 874 886 892
 49 112 178 245 313 381 449 515 579 639 696 748 795 836 870 898 919 932 938 936
101 170 241 313 385 456 526 593 657 716 771 820 864 900 929 951 965 972 970 960
165 238 312 387 460 532 601 667 729 785 836 881 918 949 971 986 992 990 980 962
237 312 387 462 534 604 671 733 790 841 886 924 955 978 993 999 997 987 969 942
312 387 460 532 601 667 729 785 836 881 918 949 971 986 992 990 980 962 936 902
385 456 526 593 656 716 771 820 863 900 929 951 965 971 970 960 942 917 884 845
449 515 579 639 696 748 794 835 870 898 918 932 938 936 927 910 886 855 818 774
500 559 615 668 716 759 797 829 854 873 886 891 890 881 866 843 815 780 740 694
535 585 632 676 714 748 777 800 817 828 833 832 824 810 790 765 734 697 657 612
550 591 628 662 691 716 736 751 761 765 764 757 745 728 706 679 647 612 573 531
544 575 603 627 647 664 676 684 688 687 681 671 657 639 616 590 561 529 494 458
516 538 556 572 585 594 600 603 602 598 590 579 565 548 528 506 481 455 426 397

This contains 30 rows with 20 numbers in each row and represents a smoothly
varying function of both x and y.  To plot this using contour, simply enter:

contour
file data30.20
read 30 20 1
plot
stop

Of course this is probably better done with a script file:
                                                        (contcmd1)
contour << !
file data30.20
read 30 20 1
plot
stop
!

The READ command tells the program to read 30 lines of 20 numbers
each.  The third argument describes the orientation of the data
in the array.  Use "1" here to obtain plots that are the same
orientation as a hard copy of the data file.  Other choices
will reverse the order of the x and y-axes and/or rotate the
plot (see contour documentation).

The plot will be output to a Postscript file called "mypost."
Note that the program chooses contour intervals of 100 for this plot.
The plot aspect ratio is assumed to be in proportion to the number
of x and y values.  The dimensions and the position of the plot 
can be changed used HEIGHT, WIDTH and PLOT as follows:
                                                         (contcmd2)
file data30.20
read 30 20 1
HEIGHT 5
WIDTH 5
PLOT 1.5 3
stop

Note that this forces the x and y dimensions to be the same.  We can
add axes tic marks and labels as follows:
                                                         (contcmd3)
file data30.20
read 30 20 1
height 5
width 5
AXES 0 20 0 30
XLAB East distance (km)
YLAB North distance (km)
plot 1.5 3
stop

If we don't like the default contour intervals, we can change this
using the LEVEL command:
                                                         (contcmd4)
file data30.20
read 30 20 1
LEVEL 0 200 400 600 800
height 5
width 5
axes 0 20 0 20
xlab East distance (km)
ylab North distance (km)
plot 1.5 3
stop

In this we forced intervals at every 200 instead of every 100.
We can also change the thickness of every contour and whether
we label the contour.  For example, let's have bold labeled
contours every 200 and dashed unlabeled contours every 100:
                                                          (contcmd5)
file data30.20
read 30 20 1
LEVEL 100 200 300 400 500 600 700 800 900
CODE   -4   2  -4   2  -4   2  -4   2  -4
height 5
width 5
axes 0 20 0 20
xlab East distance (km)
ylab North distance (km)
plot 1.5 3
stop

Each number in the code command corresponds to a level in the
level command.  The choices are 1 for a line of ordinary weight,
2 for a heavy line and 3 to 5 for dashed lines of increasing
lightness.  Negative numbers indicate unlabeled contours.
The result is that we have complete control over the appearance
of the contours.  Note that the contours do NOT have to be
at regular intervals!

There are many additional features that are described in the
contour documentation.  It is easy to add notes or x-y data
to the plots.  Multiple plots can be produced on the same
page.  Greek letters and sub/superscripts are supported, just
like in PLOTXY.  Different colors can be specified for the
contours.  The degree of smoothing applied to drawing the
contours can be modified.

As a final example, let's plot the bathmetry/topography
data for the SIO area that we previously considered in
the Matlab examples.  Here is a script that will read these
data from the file siotopo.ascii and make a contour plot:
                                                (do.contour)
contour << !
Color 12000
file siotopo.ascii
read -214 171 3
axes 0 13.260 0 19.809
height 4.95225
width 3.315
xlab East distance (km)
ylab North distance (km)
title La Jolla Canyon Bathymetry
note (11.0 8.5 13.2 11 0.12) Good surfing here
plot 2 3
stop
!
pageview mypost


COLOR

This program is similar to CONTOUR but adds color between
the contours.  For example, using the same data file as
in the CONTOUR examples, we could enter
                                              (colorcmd1)        
color
file data30.20
palette 1
read 30 20 1
height 5
width 5
plot 1.5 3
stop

This gives us a nice result using the default color palette.
We can change the color palette or explicitly change the
colors if we so desired (see color documentation).  It
is often good to add contour lines to better separate
the color boundaries.  We can do this will the OUTLINE
command:
                                              (colorcmd2)
file data30.20
palette 1
read 30 20 1
height 5
width 5
axes 0 20 0 20
outline
plot 1.5 3
stop

Here we have also used the AXES command to add tic marks
and coordinates.

As a final example, let's plot the SIO topography data:
                                               (colorcmd3)
file siotopo.ascii
palette 1
read -214 171 3
axes 0 13.260 0 19.809
height 4.95225
width 3.315
outline
note ( 0.9 -0.5 0.2) East distance (km)
note (-0.5  1.5 0.2  90.) North distance (km)
note ( 4.4  3.0 0.2 -90.) Elevation (m)
plot 2 3
stop

One limitation of COLOR is that it does not implement the
XLAB and YLAB commands of the contour program.  Thus,
these labels have to be entered manually using the
NOTE command.

Notice that COLOR shows this image as a discrete set of
colors rather than the continuous range of colors that
we saw in the Matlab example.  This is fundamental to the
COLOR program, which is essentially a contouring program
that permits different colors or gray shades to be placed
between the contour lines.  This approach is well suited
to publications (where the color reproduction may be marginal)
and because it is easier to estimate values for specific points 
on the plot, particularly when there is a corresponding color 
bar.