Go to the first, previous, next, last section, table of contents.

Gnudl prototype tutorial

In this tutorial section, the prompt ; -> will indicate output from gnudl (I will not reproduce most output here, just interesting output lines); lines in the

example typeface

without ; -> are lines you should type. You can cut the example sections from this manual and paste them into gnudl.

You can invoke gnudl by typing


Also: the demos in this tutorial are all stored in the file "demo.scm", so you can type (load "demo") in gnudl and it will tell you how you can run the individual demos.

Elementary examples

Surface plots

Gnudl provides, in the proto4 snapshot, a very elementary surface plotting mechanism. If you have a height matrix a, which you could form with

(define a (make-matrix-index (lambda (x y)
			       (* (exp (- (/ (+ (* (- x 5) (- x 5))
						(* (- y 5) (- y 5))) 30)))
				  (sin (/ x 2))))
			     20 20))

then you can render a surface wire mesh plot with hidden lines using:

(surface a)

Notice that the height matrix a was formed with the make-matrix-index procedure, which makes a matrix of the given size (20x20), and fills it with the given procedure:

(lambda (x y)
  (* (exp (- (/ (+ (* (- x 5) (- x 5))
                   (* (- y 5) (- y 5))) 30)))
     (sin (/ x 2))))

The procedure is applied to the matrix indices, and it scales down the x and y values (since they are integers).

Right now there are no options for shifting the view angle (should be easy to add), or for shading the wire mesh (probably harder). The surface call is a trivial call to gnuplot's splot command, with the hidden line removal option.

[NOTE: I am still looking for someone to take the lead on 3D work for Gnudl. Talk to Mark Galassi (rosalia@nis.lanl.gov) if you are interested.]

You can also draw a contour plot of the same height matrix with

(contour m)

If you want more contour levels (the default is 6), use

(contour m n-levels)

Like surface, contour is just a pipe to ghostscript right now, and pretty unsophisticated.

Random numbers and probability distributions

Gnudl provides several routines that generate vectors filled with random numbers satisfying various probability distributions.

Getting data from a file

It is nice to create vectors online and play with them, but most of the time experimental scientists will be reading in data from a file. We provide a sample data file with the gnudl distribution, called hete_sample.dat. This file contains actual data from the HETE satellite experiment, organized as X and Y columns of numbers.

Display of images

Gnudl has facilities for incorporating pre-made images in a variety of formats into its plotting window. Here are some examples, based on two GIF files supplied with the software:

The plotting screen layout

So far you have seen gnudl operate in a mode where it shows x columns and y rows of plots. But gnudl can have very general plot screens of all sorts of shapes and sizes: the p-multi procedure is simply a short cut for more general plot-list management routines.

The underlying mechanism to add a plot to the plot-list is the plot-list-add procedure. To demonstrate its use, try resetting the plot list to only have a background plot:


now add a plot in the rectangle (100 100 400 300:

(set! default-plot-list (plot-list-add default-plot-list '(100 100 400 300) '() #f '()))

The arguments '() #f '() specify, respectively, that there is no "hook" procedure to be invoked for this plot; that this plot is not to be skipped by plot, and that we start with no list of postscript instructions.

Now add a second plot rectangle

(set! default-plot-list (plot-list-add '(400 400 550 600) '() #f '()))

and reset the current-plot variable with


and refresh the screen by typing


Now try making some new plots:

(define (new-func x) (times (cos x) (sin x)))
(define x-vals (span -10 10 500))
(plot (new-func x-vals))
(plot (sin x-vals) (new-func x-vals))

As you see, these plots went into the two rectangles defined with plot-list-add.

There is another much more general routine for manipulating the plot-list: boxl->plot-listD takes a box list describing a full screen layout and uses it to add several plots to the default-plot-list. The box matrix is a list of nested lists that describe how many columns and rows should be nested in the various areas of the plot list.

Box lists are best explained by example; try pasting these in (notice that new-func and x-vals are defined in previous examples):

(boxl->plot-listD '(1))
(plot (times (sin (times 4 x-vals)) (exp (divide x-vals -4))))
(boxl->plot-listD '(3 1 2))
(plot (times (sin (times 4 x-vals)) (exp (divide x-vals 3))))
(plot ((lambda (x) (times (sin (times 4 x)) (divide 1 (plus 1 (times x x))))) x-vals))
(plot ((lambda (x) (times (sin (times 4 x)) (divide 1 (plus 1 (times x x))))) x-vals))
(plot (times (sin (times 4 x-vals)) (exp (divide x-vals 3))))
(plot ((lambda (x) (times (sin (times 4 x)) (divide 1 (plus 1 (times x x))))) x-vals))
(plot (times (sin (times 4 x-vals)) (exp (divide x-vals 3))))

This will set the plot screen to have three plots in the top row, one in the middle row and two on the bottom row, and show some sample data in those plots.

Try some more complicated box matrices with nested sub-boxes, such as:

(define boxl '( (2 1) (1 3) (1 (1 1)) 1 ((1 2) 1 1)) )
(boxl->plot-listD boxl)

and then make various plots in it (there are 16 plots in this box list).

Numerical analysis support

Gnudl provides a large library (actually it's pretty small right now) of numerical routines that can be applied to data or to functions. More routines can be added by programming them in C or scheme, but in this tutorial I only describe the use of some analysis routines that we provide with guile.

Operations on vector data

You have noticed how arithmetic operations and transcendental functions can all be applied to vector data as well as single numbers.

There two more operations which make vector manipulatio powerful and flexible: the where operator and subscripting with a list of indices.

Saving postscript files and printing

Gnudl has a command (ps-snapshot plot-list file-name) for saving postscript

Special plotting commands

Apart from the standard "x-y plotting" possibilities, gnudl also allows you to splatter arbitrary shapes onto into a plot rectangle. In this mode the coordinates of the objects you draw always range from (0, 0) to (1, 1).

(p-multi 3 3)
(add-rect 0 0 0.5 0.5 'blue)
(add-rectR 0 0.5 0.6 0.6 'red)  ; the R means you refresh after drawing
(add-segmentR 0 0 1 1 'green)
(add-boxR 0.3 0.3 0.4 0.4 'purple)

Another example shows the use of bar charts:

(p-multi 1 10)
(bar-chart-flat (span 0 20 20)) ; all rectangles are the same height
(bar-chart (span 0 20 20))      ; height is proportional to the value
(bar-chart-flat (sin (span 0 200 200)))
(bar-chart (span -10 10 200))
(bar-chart (times 30 (sin (span -10 10 200))))
(bar-chart (times 30 (sin (span -10 10 200))) 'red)
;; now do some bar charts of histograms
(define b (span -2 4 2000))
(define esb (times (exp (divide b (- 2))) (sin (times b 8))))
(define hesb500 (histogram esb 500))
(bar-chart (cdr hesb500))     ; the histogram puts the actual data in the cdr
(bar-chart (cdr hesb500) 'blue)
(define hesb250 (histogram esb 250))
(bar-chart (cdr hesb250))     ; the histogram puts the actual data in the cdr
(bar-chart (cdr hesb250) 'blue)

The Cellular Automata package

Mark Galassi wrote a package which allows some displaying of cellular automata as well as displaying results from his ga_ca project. Take a look at the file ca.scm to see how special-plot and other constructs are used together to make vignettes of many types of data.

Go to the first, previous, next, last section, table of contents.