S-PLUS 5.x Info

This document gives a little info about S-PLUS Version 5 for people who are mystified.

This page currently describes only S-PLUS 5.1 on the HP workstations. The SGI server (superior.stat.umn.edu) will be upgraded to S-PLUS Version 5 but hasn't as of this writing.

MySwork and .Data
Splus CHAPTER
Converting Old Datasets and Functions
Calling C from S-PLUS
Compiling and Loading
The Call to C
S-PLUS Wrapper Functions
Attaching S-PLUS Chapters

MySwork and .Data

The first difference everyone notices is that your old .Data directories don't get used by the new version of S-PLUS. The reason is that there are some incompatibilities between the old and new versions and it would be a Bad Thing to use a .Data directory created by an older version of S-PLUS as the working directory for the new version.

For this reason the only directories which can be working directories for the new version are .Data directories that are inside a directory that is a valid S-PLUS 5.x chapter. We will see how to create such a beastie below. For now it is enough to know that S-PLUS creates one for you the first time it is run. It is the MySwork subdirectory of your home directory.

Thus whenever you start S-PLUS, whether the current directory contains a .Data subdirectory or not, the only S-PLUS datasets you can access are in the directory

   ~/MySwork/.Data

unless you have made the current directory a valid S-PLUS 5.x chapter as described below.

Splus CHAPTER

To make a valid S-PLUS 5.x chapter do the following

   Splus CHAPTER

in a directory that does not have a .Data directory made by a previous version of S-PLUS.

Now if you run S-PLUS in this directory it will use the .Data subdirectory of this directory as the working directory. It will not use the ~/MySwork/.Data directory.

Converting Old Datasets and Functions

To convert files in .Data directories made by older versions of S-PLUS to the new format do the following.

Make a valid S-PLUS 5.x chapter as described in the preceding section.
Go into S-PLUS (say Splus at a UNIX prompt).
Run the S-PLUS command convertOldLibrary on the old .Data directory. For example, if I want to convert the old directory ~/Blurfle/fluff/.Data I do
```
   convertOldLibrary("$HOME/Blurfle/fluff/.Data", "./.Data")
```

All the files (datasets) that can be just copied are. All the files that need changes to be correct in S-PLUS Version 5 are modified. The current directory is now a valid S-PLUS 5.x chapter containing these datasets and functions.

Calling C from S-PLUS

S-PLUS is rotten at iterative algorithms that require loops iterated many times (especially Markov chain Monte Carlo). A way to get all the speed advantages of C with most of the convenience of S-PLUS is to write the inner loop in C and call it from S-PLUS.

Here is a very simple C function

   void foo(long *nin, double *x)
   {
           int n = nin[0];

           int i;

           for (i=0; i<n; i++)
                   x[i] = x[i] * x[i];
   }

which does nothing but square the elements of the n-vector x.

Notice two properties that are required for a function callable from S-PLUS

The function does not return a value. All work is accomplished as a "side effect" (changing the values of arguments).
All the arguments are pointers. Even scalars are vectors (of length one) in S-PLUS.

Compiling and Loading

Put the code in a file foo.c, put this file in a directory by itself, and run the command

   Splus CHAPTER

which makes this directory a valid S-PLUS 5.x chapter. Or you can put the file foo.c in a directory that is already a valid S-PLUS 5.x chapter and rerun the Splus CHAPTER command. Either will work.

Then run the UNIX make command as follows

   export SHOME=`Splus SHOME`
   make

(it is a mystery to me why the variable SHOME is not defined in the makefile, but it isn't). This creates a file S.so which is a UNIX shared library that is automatically loaded whenever S-PLUS uses this chapter.

The Call to C

The actual call to C from S-PLUS is made by the S-PLUS function .C like this

   .C("foo", n=as.integer(5), x=as.double(rnorm(5)))

The function .C takes nargs + 1 arguments if the C function being called takes nargs arguments. The first argument is the name of the C function to be called, and the rest are the arguments to the function call. The arguments generally have to be coerced to the proper type using as.integer, as.double, and similar functions. The function .C returns a list whose elements are the arguments to the function call (in this case n and x). The values are the values after the call (as changed by the function foo).

For more on this subject see the S-PLUS help for .C or the S-PLUS Programmer's Manual.

S-PLUS Wrapper Functions

It is considered user-friendly to wrap the call to .C in an S-PLUS function, like

   foo <- function(x) {
           if (!is.numeric(x))
                   stop("argument x must be numeric")
           out <- .C("foo",
                   n=as.integer(length(x)),
                   x=as.double(x))
           return(out$x)
   }

This has three benefits

It allows some error checking in S-PLUS, where it is easier than in C.
It allows some arguments (like n here) to be calculated so they don't have to be supplied by the user.
It allows you to return only what the user needs.

Now the call is much simpler, just

   foo(x)

where x is any S-PLUS expression that evaluates to a numeric vector.

Attaching S-PLUS Chapters

When S-PLUS starts it looks at the file

   ~/MySwork/.S.chapters

for a list of valid S-PLUS 5.x chapters that to attach on startup. In this file you put, one to a line, the complete paths to the S-PLUS chapters you want attached. Each chapter is a directory. By complete path we mean the path from the root of the UNIX file system, for example,

   /FACHOME/isles/charlie/tmp/Bar

if that is the directory in which the Splus CHAPTER command was run.

Questions or comments to: Charles Geyer charlie@stat.umn.edu

S-PLUS 5.x Info

Contents