The SM Tutorial

by Robert Lupton and Patricia Monger


Table of Contents


What is SM?

SM is an interactive plotting package for drawing graphs. It does have some capability to handle image data, but mostly works with vectors. The main features of the package are that one can generate a nice looking plot with a minimum number of simple commands, that one can view the plot on the screen and then with a very simple set of commands send the same plot to a hardcopy device, that one can build and save ones own plot subroutines to be invoked with a single user-defined command, that the program keeps a history of ones plot commands, which can be edited and defined as a plot subroutine, to be reused, and that one can define the data to be plotted from within the program, or read it from a simple file.

You might ask, "Why do I need SM?", but I am not going to answer you. If you read through this tutorial, and use the package for a while, and still can't see why you need it, then you probably don't need it.

How should I get data into SM?

Plot vectors may be generated in several ways:

a.
You may read the vectors from a file using the read command The file is expected to be an ASCII file of columns of numbers (separated by spaces, tabs, or commas). You define the file to SM using the data command, and associate a column or row of numbers with a SM vector using the read command. Example: Say I have a file named test.dat with the following data in it:
1       2       3       5.6     10
3       6       8       2.3     11
5       8       2       7.7     12
7       9       4       9.3     13
9       3       1       4.8     14
Then the commands to issue to SM to get the data into the program are:
        data test.dat
        read x 1
        read y 2
(or read { x 1 y 2 }). In the last 2 commands I have told SM to read the values in column 1 of the file test.dat, and assign them to a vector named x, and read the values in column 2 of the file and assign them to a vector named y. I could read any of the other columns in as well, of course, and assign them to vectors. And I can name the vectors whatever I like, as long as the name consists of the characters a-z,A-Z,0-9, and _ (underscore). I can also read a row from the file, instead of a column, by saying
        read row x 1
Note that the vector is defined by the read command. But I can redefine it whenever I wish, and change the size. The only point to remember is that when you redefine the vector, the old values are overwritten. A final point to note about defining vectors from files is that you can skip over lines in the file with the lines command. lines defines which lines in the file you want to read. A limitation of lines is that you may only define one set of lines to read; that is, if you had a 30 line file, and wanted to read lines 3-9 and 15-30, you couldn't (well, you could, but you'd have to make clever use of the method of defining vectors which is discussed in the next subsection, or make lines 10-14 each begin with a #).
b.
You may define the vectors within SM using the set command. This command has a number of forms:
c.
You can redefine an existing vector element by element with a do loop:
        set y = 1,50
        ...
        do i=0,49 { set y[$i] = $i**2 }
(Note Well that vector elements are numbered starting from 0)
d.
You may create a vector with the spline command. This fits a spline function to a previously defined pair of vectors, and evaluates it at the points given in a third vector, to produce a fourth vector for you.
        set x = 0, 2 * PI, PI/4
        set y = sin(x)
        set xx = 0, 2 * PI, PI/32
        spline x y xx yy
This will fit a spline to the curve y vs x, at the points 0, PI/32, PI/16, 3 * PI/32,... (i.e. the points in the xx vector), and the spline values will be stored in the vector yy.
e.
You may define a vector with the graphics cursor using the cursor command. If you type the command
cursor a b
then a cursor will be displayed on the screen, and to the spline command. This will take a horizontal slice through the image. If you do not give a filename, the vectors are printed to the terminal.
f.
If you want vectors that look properly scientific to play with, you might find that
set x=random(100)
is just what you want.

How do I generate a basic plot for data in a file?

The procedures listed above describe how to get your data in to SM. Then the steps to plotting it are as follows:

For example, you might type:

device x11
echo reading test.dat
data test.dat
read { x 1 y 2 z 4 }
limits x y
box
connect x y
ptype 6 3
points x z
xlabel This is the X axis
ylable This is data plotted against X

There are a number of other commands that elaborate on this basic set to allow logarithmic axes, labelling curves, putting an ID on the plot, reading positions from the plot with a cursor, manipulating 2-D data, and much more. Some of these commands are described in this tutorial (see section What are the other common commands?); the definitive source, however, is in the real manual, where all the commands plus their syntax are described.

What do I have to do to start up SM?

With any luck, your system manager has set up SM so that you can run it by typing a single command. She should have created a system wide file called an ``.sm' file'. Just in case she was negligent, or in case you want to overrule some of her choices, you can have in addition your own `.sm' in your home directory. This file is used by SM to tell it a number of things. A prototype .sm file for a VMS system is reproduced below:

        device          hirez
        edit            $disk:[sm_dir]maps.dat
        filecap         $disk:[sm_dir]filecap
        file_type       vms_var
        fonts           $disk:[sm_dir]fonts.bin
        help            $disk:[sm_dir.help]
        history         80
        history_file    .smhist
        graphcap        $disk:[sm_dir]graphcap
        macro           $disk:[sm_dir.macro]
        macro2          $disk:[lupton.sm]
        name            my_friend
        printer         qms
        temp_dir        sys$scratch:
        term            hirez
        termcap         $disk:[sm_dir]termcap

Now, what is all this?

device
allows SM to initialize a default plotting device for you. If it finds an entry of this type in your .sm file, it will do the call to the device command for you.
edit
is used by SM to find out how to map the key sequences used by the macro and command line editor. The only reason you need to change this line is if you decide you want to define the key sequences differently. For example, if you invoke the macro editor ( See section What is a plot macro, and how do I make one? to find out what that means), and want to edit your macro and, say, insert a line, to do that you type ^M (hold down the CTRL key and then press the m key, or simply hit Carriage Return). Now, if you don't like that particular choice of keys, you can set up your own key definitions in your own edit file, and tell SM to use that instead of the default ones by redefining the edit line of the .sm file.
filecap
is a file that tells SM how to read 2-dimensional files. As mentioned in section 11, binary files vary enormously from operating system to operating system, and also depend on the language of the program you wrote to generate them, so we defined a few simple file formats you can use to read binary data into SM, and SM interprets them via the filecap file. Read the manual if you want to plot 2-D data.
file_type
is also for 2-D data. This sets the default file type for the binary files. The types are described in the manual (see section `Filecap' in The SM Manual). The filecap file tells SM how to read data of the given file_type
fonts
This tells SM where to find the font definition file. You will almost certainly never change this, but if you have made a new font file you would cause SM to use it instead of the one we supply by changing this line in your .sm file.
help
This tells SM where to find the command help files.
history
The number of history commands to remember (see the next entry).
history_file
SM keeps of history of the commands you used in your SM session in a file. It reads in the last history file when you start it up again, and you can reuse those commands as you wish (e.g. scroll through them like with the VMS command line editor, extract a group of commands into a macro (see section What is a plot macro, and how do I make one?), ...). If you don't want a history, leave this line blank. Otherwise, specify a filename.
graphcap
This is the file SM uses to figure out what magic commands to send to your plot device to cause it to go into graphics mode. We have defined many device types, so hopefully the one you need is already in the default file. If not, you may want a private graphcap.
macro
SM loads a set of default plot macros for you when you start it up. This line gives the location of the default macro file.
macro2
You can load 2 default files if you wish, and this is where you define the second one. @item macro2 is the name of a directory where SM expects to find a file name `default', in which are contained SM macros. You should load our default one first, for reasons which are explained in the manual. The macro startup2 in file `default' will be executed.
name
This is the name by which SM will address you when you use it.
printer
There is a macro called `hcopy' that replays the commands used to generate a plot on your screen and changes the device to a printer to allow you to easily get a hardcopy of your screen plot. This line tells SM what printer you want to use. You can also get hardcopy plots manually (see section How do I get a hardcopy of a plot?).
temp_dir
Hardcopy plots are written to a disk file, and then submitted to a print queue and deleted. This tells SM what directory you want it to write the disk files to. They can be large, so if you have disk quota problems, temp_dir ought to point to a scratch disk or something
term
SM knows about terminals, and uses that knowledge to allow you to do command line editing. Here is where you specify what kind of terminal you have. Note this is for `text' only; the graphics description is given in the device line at the start of this file. The available terminal types are described in the termcap entry.
termcap
This file describes terminals.

So to run SM, you should have a file like this in your home directory, with the directory names, etc changed to point to your computer and you, and then just run the program. If all goes well, when you invoke the program, you will wait a while, and then get the following message

Hello, <name>, please give me a command

where <name> is as defined in the .sm file name line, and you will get a prompt. If this isn't what happens, you need to contact the people who installed SM on your system.

How do I define variables, and how can I use them?

Scalar variables are defined with the define command. As mentioned above, vectors are defined with the set command. A variable may be a number, or a character string. You may use them in any SM command, by preceding the name of the variable with a $. For example:

        define two_pi 6.283        # or define two_pi $(2*pi)
        set x=1,100
        do i = 0, 0.99, .01 {
           set x[100*$i] = $i * $two_pi
        }
        set i=0, 0.99 , .01
        set x=$two_pi*i
        set y = sin(x)
        limits x y
        box
        define xlab {my signal}
        xlabel $xlab
        ylabel sine

What is a plot macro, and how do I make one?

A plot macro is a set of commands that you can execute together by invoking the name of the macro; in effect, it is a plot subroutine. For example, suppose you had a set of plots that you wanted to generate, using the same type of axis box and labels. Rather than laboriously typing the box and label and limits commands for each set of data, you could define a macro as follows:

        drawbox         # this is a comment
                        limits 0 20 0 100
                        box
                        xlabel xdata
                        ylabel ydata

where the macro name in this example is drawbox. Then, when you access your data, you could do as follows:

        data file1.dat
        read { x 1 y 2 }
        drawbox
        connect x y
	erase
        data file2.dat
        read x 3
        read y 7
        drawbox
        connect x y

(The read { x 1 y 2 } is the same as read x 1 read y 2, but faster). This is a simple-minded example, and you can immediately see ways to improve the macro I have created to save even more typing. Macros may consist of any SM commands, and may have arguments. You specify the number of arguments in the macro definition, and refer to them by number, preceded by $. In the example I gave above, suppose we wanted to make the axis labels into variables. Then the macro definition would look like this:

        drawbox 2       # this is also a comment, but not a very useful one
                        limits 0 20 0 100
                        box
                        xlabel $1
                        ylabel $2

Then to invoke the macro, I type

        drawbox xdata ydata

You can make a macro in 4 ways:

a.
You can create it with your favorite editor outside of SM. The rule to remember if you do this is that the name of the macro must be the first thing on a line of the file, and should be followed by SM commands. All the commands must start in a column in the file other than the first column. To read this macro into SM, use the macro read command
        macro read macro.file
will read all the macros in the file macro.file.
b.
You can define the macro within SM by extracting a set of commands from the history buffer
        macro mname 1 20
will extract lines 1 through 20 from the history buffer, and create the macro mname which consists of those 20 lines.
c.
You can define the macro within SM with the macro command
        macro mname {
will start the definition of the macro named mname. You then enter SM commands, and terminate the macro definition with a closing }.
d.
You can define the macro within SM with the macro edit command
        macro edit mname
will invoke the macro editor, and you can then enter SM commands to define the macro. The editor is described in detail in the SM manual; the main commands to remember are as follows: In the following descriptions ^X means hold down the CTRL key and then press the X key

How do I save macros?

Once you have defined the macro, the command

        macro write macro1 macro_file.dat

will write the macro named macro1 to the file macro_file.dat The macro write command remembers the name of the last file it wrote a macro to, and if the filename is the same in the next command, it will append the new macro to the file, otherwise it will delete it first (you can get round this -- see section `Macro' in The SM Manual). In this way, related macros can be written to the same file.

Another (maybe easier?) way is to use the save command. the command

        save save_file

will save everything to a file -- macros, variables and vectors. To get them all back, say

        restore save_file

You can even logout, go to dinner, come back, restart SM, use restore, and be back where you left off.

How do I get a hardcopy of a plot?

You can simply define the hardcopy device with the device command, then issue the plot commands, and then type

        hardcopy

which sends the plot to the hardcopy device.

Or, in the more common scenario, you have put the plot on the screen, and fiddled with it until you were happy with it, and then want to plot it to a hardcopy device. In this case, you make use of the fact that SM saves your plotting commands in a buffer, and you can manipulate that command list. The command

        history

will print out the list of commands, in reverse chronological order (or chronological order with history -). You can then delete all the commands in that buffer that you don't want with the DELETE command.

        DELETE 1 10

will delete lines 1 through 10 from the history list. Once you have deleted all the lines from the history list except the ones you used to make the plot on the screen, you can change devices to the hardcopy device using the device command, and then type

        playback
        hardcopy

This will execute the commands in the history list, and then print the hardcopy plot. In fact, there is a macro hcopy defined to do this for you. hcopy sets the device to the hardcopy device (as defined in your .sm file on the printer line), then does a playback, then sends the plot to the hardcopy device, and then resets the device type to be whatever it was when you invoked the hcopy macro. You don't have to playback all the lines; both hcopy and playback have optional arguments to specify the range of lines that you want.

You could also define the commands from the history list into a macro, as discussed in section 6, and invoke the macro to execute the plot commands:

        macro hcplot 1 20
        device qms lca0
        hcplot
        hardcopy

This will execute the plot commands from the history buffer lines 1 through 20, and then send the plot to the hardcopy device for printing.

An important point to note about the hardcopy devices is that you have to reissue the device command each time you do a hardcopy command. This is because the hardcopy plot vectors are actually written to a file, and this file is closed, sent to the plotter, and deleted when you issue the hardcopy command. No new file is opened for you automatically, so you must issue the device command to open a new plot file if you want another hardcopy plot, or to redefine the device to a terminal, if that is what you want. You may be able to use the PAGE command to start a new page without starting a whole new plot.

What about 2-dimensional data?

SM has some capability for handling image data. You can define an image with the image command, which is analogous to the data command for vectors. As described in the manual, you must first tell SM what sort of image file it is. Binary data is rather tricky to define in a general way, and certainly differs from one operating system to the next, so the few standard types of binary files we have defined will hopefully cover most cases, and if not, you can always write a program to convert your data into one of those types, or try to teach SM about your data format after reading the filecap appendix to the manual (see section `Filecap' in The SM Manual).

Once you have read in the image, you can contour it with the contour command (first define the contour levels with the levels command), you can take a slice through it with the set x = image(x,y) command, you can draw it as a surface plot (see section `Surface' in The SM Manual), or you can draw a greyscale version of the data (this is a macro. Say HELP greyscale for details, or load demos grey_sincos for a demonstration).

It is possible that more capabilities will be added someday, but SM is not intended to be an image processing system.

What are the other common commands?

There are many more commands, which are described at the back of the manual. You will regret not reading about them.

What are Common Errors, and What Should I Do?

Where do I go from here?

To the real manual, of course, wherein you will find all the commands described, a list of all currently defined macros and what they do, plus a description of the program structure as well as information about the graphics back end that will enable you to add drivers for other devices. See section `Introduction' in The SM Manual.


This document was generated on 4 March 1998 using the %M% translator version %I%.