Kickstarting R - Making your work portable

What are packages?

In case you haven't noticed, computer programs have become so interconnected that the majority come in some sort of package. It's no longer the rule that you create a directory, copy the program(s) to that directory and start it up. All sorts of links and dependencies have to be satisfied before things will work properly. R, like everybody else, has a system for packaging things, described in detail in R-exts. It's about as difficult to understand as other packaging systems, requiring you to learn the R documentation language among other things. The purpose of this manual is to enable you to get started with simple tasks without sending you off for a week or two of training.

Using existing packages

From the same place that you downloaded R, you should be able to download packages that will do an amazing variety of things. Finding out exactly what they do is not always straightforward. My current favorite among the cryptically named packages is e1071. I'll leave it to the reader to find out what this package does and why it has this name.

Packages are structured in the same way as the R distribution, a compressed archive of code that can be built into the required function library. Just download the package that you want, preferably to a convenient place (I use /usr/local/R-pkg) and then use the following command to build it:

R CMD INSTALL /usr/local/R-pkg/package_1.0-2.tar.gz

of course substituting the correct path and package name. If you would like to avoid having the whole range of help files written, the option:

--no-xxxxx

may interest you, where xxxxx indicates a sort of documentation(example, latex, html or text). This will stop the program from generating that particular type of help.

Making a minimal package

So, you've figured out how to write some really useful functions that you wish to apply to the entire animal kingdom, not just aardvarks. You don't want to laboriously copy these functions to every one of your working R directories. Gather your functions together in your favorite editor (assuming that they are all written in R script) and think of a great name. I call mine lemons, which is really embarrassing in the creativity stakes, but I'm trying to maintain a modicum of honesty here.

Let's say you're about at my level of creativity and have decided to call your file of functions mystuff. First you'll need a place to store your masterpiece. Go to the directory library just beneath the R directory itself. Make a directory named mystuff, and a directory below that named R. You may have to become root (or administrator, i.e. THE BOSS of your system) to do this. Now, save your file of R functions into the mystuff/R directory as (surprise!) mystuff. This repetition of names may seem mysterious. It is. For the moment, just accept that this is how the system works.

Now you have to create a file in the mystuff directory named DESCRIPTION that will look like this:

Package: mystuff
Version: 1.0
Date: 13/1/2003
Author: Your name
Maintainer: Your name
Description: my ingenious functions
Depends: (the names of any other libraries that your library needs to run)
License: GPL
Built: R 1.6.2; i586-pc-linux-gnu; Mon Jan 13 12:50:30 EST 2003

The last line can be copied from another DESCRIPTION file - it's only there to con the system into accepting the package. This is the absolute minimum necessary to be able to load your functions with the command:

library(mystuff)

This allows you access to your functions in any directory in which you start R. You can also add the library() command to your .First file to automatically load your functions at startup.

If you're on a system that doesn't allow you access to the R directory structure, you can still have your functions. Just create the file of all the functions (for the sake of propriety, you might call it mystuff.R this time) and store it in a directory to which you do have access (e.g. /home/jim/R). You can then put the following line in your .First function and it will automatically load your functions.

source("/home/jim/R/mystuff.R")

This doesn't allow you to package up your functions so that the INSTALL command will neatly install them, or allow you to create help files that will show up automatically on the list of packages. So when you get some free time, have a look at R-exts and learn how to make real packages.

Back to Table of Contents