R in a Nutshell

Custom Packages

Building your own packages is a good idea if you want to share code or data with other people, or if you just want to pack it up in a form that’s easy to reuse, you should consider building your own package. This section explains the easy way to create your own packages.

Creating a Package Directory

To build a package, you need to place all of the package files (code, data, documentation, etc.) inside a single directory. You can create an appropriate directory structure using the R function package.skeleton:

package.skeleton(name = "anRpackage", list,
                 environment = .GlobalEnv,
                 path = ".", force = FALSE, namespace = FALSE,
                 code_files = character())

This function can also copy a set of R objects into that directory. Here’s a description of the arguments to package.skeleton.

Argument	Description	Default
name	A character value specifying a name for the new package	“anRpackage” (as a side note, this may be the least useful default value for any R function)
list	A character vector containing names of R objects to add to the package
environment	The environment in which to evaluate list	.GlobalEnv
path	A character vector specifying the path in the file system	“.”
force	A Boolean value specifying whether to overwrite files, if a directory name already exists at path	FALSE
namespace	A Boolean value specifying whether to add a namespace to the package	FALSE
code_files	A character vector specifying the paths of files containing R code	character()

For this book, I created a package called nutshell containing most of the data sets used in this book:

> package.skeleton(name="nutshell",path="~/Documents/book/current/")
Creating directories ...
Creating DESCRIPTION ...
Creating Read-and-delete-me ...
Saving functions and data ...
Making help files ...
Done.
Further steps are described in 
'~/Documents/book/current//nutshell/Read-and-delete-me'.

The package.skeleton function creates a number of files. There are directories named man (for help files), R (for R source files), and data (for data files). One of the most imporant is the DESCRIPTION file, at the root of the created directory. Here is the file that was generated by the package.skeleton function:

Package: nutshell
Type: Package
Title: What the package does (short line)
Version: 1.0
Date: 2009-08-18
Author: Who wrote it
Maintainer: Who to complain to <[e-mail]>
Description: More about what it does (maybe more than one line)
License: What license is it under?
LazyLoad: yes

Many of these items are self-explanatory, although a couple of items require more explanation. Additionally, there are a few useful optional items:

LazyLoad

LazyLoad controls how objects (including data) are loaded into R. If you set LazyLoad to yes (the default), then data files in the packages are not loaded into memory. Instead, promise objects are loaded for each data package. You can still access the objects, but they take up (almost) no space.

LazyData

LazyData works like LazyLoad but specifies what to do (specifically) with data files.

Depends

If your package depends on other packages to be installed (or on certain versions of R), you can specify them with this line. For example, to specify that your package requires R 2.8 or later and the earth package, you would add the line:

Depends: R(>= 2.8), nnet

R includes a set of functions that help automate the creation of help files for packages: prompt (for generic documentation), promptData (for documenting data files), promptMethods (for documenting methods of a generic function), and promptClass (for documenting a class). See the help files for these functions for additional information.

You can add data files to the data directory in several different forms: as R data files (created by the save function and named with either a .rda or a .Rdata suffix), as comma-separated value files (with a .csv suffix), or as an R source file containing R code (with a .R suffix).

Building the Package

After you’ve added all the materials to the package, you can build it from the command line on your computer (not the R shell). It’s usually a good idea to start by using the check command to make sure that. For the previous example, we would use the following command:

% R CMD check nutshell

You can get more information about the CMD check command by entering "R CMD CHECK --help" on the command line. To build the package, you would use the following command:

% R CMD build nutshell

As above, help is available through the --help option. If you’re really interested in how to build R packages, see the manual Writing R Extensions, available at http://cran.r-project.org/doc/manuals/R-exts.pdf.