How to Create an R Package

5 Easy Steps

1. Create R functions, classes, and data objects interactively

Copy-and-paste the code below from here: ecg.R.
R version 2.13.0 (2011-04-13)
Copyright (C) 2011 The R Foundation for Statistical Computing
ISBN 3-900051-07-0
Platform: x86_64-unknown-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

  Natural language support but running in an English locale

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> #windowed sinc low pass filter
> #y - vector to filter
> #t - time interval between measurements (s)
> #f - low pass frequency (Hz)
> wlpf <- function( y, t, f ) {
+     #sinc function of frequency f
+     sinc <- function( x, f )
+         ifelse(x==0, 2*pi*f, sin(2*pi*f*x)/x)
+     #Blackman window from 0..m
+     Blackman <- function( m )
+         0.42-0.5*cos(2*pi*(0:m)/m)+0.08*cos(4*pi*(0:m)/m)
+     m  <- min(floor(length(y)/2), 500)
+     rk <- sinc(-m:m, f*t)  
+     bk <- Blackman(2*m) * rk
+     k  <- c(bk, rep(0,length(y)-length(bk)))
+     fy  <- fft(fft(k)*fft(y), inverse=TRUE)
+     return(Re(fy))
+ }
> 
> ecg  <- scan("http://biostatmatt.com/csv/ecg.csv")
Read 22650 items
> ecg  <- ( ecg - mean(ecg) ) / sd(ecg)
> ls()
[1] "ecg"  "wlpf"

2. Use package.skeleton

> package.skeleton("ecg", ls())
Creating directories ...
Creating DESCRIPTION ...
Creating Read-and-delete-me ...
Saving functions and data ...
Making help files ...
Done.
Further steps are described in './ecg/Read-and-delete-me'.

When R evaluates the package.skeleton function, a directory named ecg is created (as a subdirectory of the current working directory, see ?getwd). This directory contains all of the necessary R package structure, including subdirectories named data, R, and man. The data subdirectory contains the ecg data in the RDA format. When the package is loaded, these data are accessed by data(ecg). The R subdirectory contains R code files, one for each code object (i.e. wlpf.R). Finally, the man subdirectory contains several Rd files, which are used to document the various aspects of your code and data.

3. Document the package functions, data, and the package DESCRIPTION

Documenting your work takes time. Files in the man subdirectory must be edited and formatted in the Rd format. Fortunately, the package.skeleton function generates some of this structure for you. Follow the queues in the automatically generated .Rd files.

Here is a tersely edited wlpf.Rd:
\name{wlpf}
\alias{wlpf}
\title{
Windowed (Blackman) Low Pass Filter
}
\description{
Filter a sequence of data using a Blackman-windowed sinc low pass filter.
}
\usage{
wlpf(y, t, f)
}
\arguments{
  \item{y}{numeric vector - the sequence to be filtered}
  \item{t}{numeric scalar - time interval between measurements in seconds}
  \item{f}{numeric scalar - low pass frequency (Hz)}
}
\value{
A vector the same length as \code{y}.
}
\author{
Matt Shotwell <matt.shotwell@vanderbilt.edu>
}
\examples{
plot(wlpf(rnorm(1500),1,1/100), type='l')
}

In addition to files in the man directory, you must also edit the DESCRIPTION file in the root directory. This file contains general information about the package. Finally, the package.skeleton creates a file in the root directory called Read-and-delete-me, which gives instructions similar to these five easy steps.

Here's a reasonable DESCRIPTION file for the ecg package:
Package: ecg
Type: Package
Title: Experiments with a homemade ECG
Version: 1.0
Date: 2011-06-06
Author: Matt Shotwell <matt.shotwell@vanderbilt.edu>
Maintainer: Matt Shotwell <matt.shotwell@vanderbilt.edu> 
Description: A package to document experiments with a homemade ECG
Depends: R (>= 2.10), lattice
License: GPL (>= 2)
LazyLoad: yes

4. Check that the package is structured and documented correctly

From the Linux shell, the R CMD build ecg command builds and stores the package as a compressed archive (i.e. ecg_1.0.tar.gz):
matt@pal:~$ R CMD build ecg
* checking for file ‘ecg/DESCRIPTION’ ... OK
* preparing ‘ecg’:
* checking DESCRIPTION meta-information ... OK
* checking for LF line-endings in source and make files
* checking for empty or unneeded directories
* looking to see if a 'data/datalist' file should be added
* building ‘ecg_1.0.tar.gz’
Again, from the Linux shell, the R CMD check ecg_1.0.tar.gz checks the built package to ensure that all data and code items are documented correctly, that the examples work, and that the package can be installed. In other words, R CMD check checks that the newly created R package is structured correctly.
matt@pal:~$ R CMD check ecg_1.0.tar.gz 
* using log directory ‘/home/matt/ecg.Rcheck’
* using R version 2.13.0 (2011-04-13)
* using platform: x86_64-unknown-linux-gnu (64-bit)
* using session charset: UTF-8
* checking for file ‘ecg/DESCRIPTION’ ... OK
* checking extension type ... Package
* this is package ‘ecg’ version ‘1.0’
* checking package dependencies ... OK
* checking if this is a source package ... OK
* checking for executable files ... OK
* checking whether package ‘ecg’ can be installed ... OK
* checking installed package size ... OK
* checking package directory ... OK
* checking for portable file names ... OK
* checking for sufficient/correct file permissions ... OK
* checking DESCRIPTION meta-information ... OK
* checking top-level files ... OK
* checking index information ... OK
* checking package subdirectories ... OK
* checking R files for non-ASCII characters ... OK
* checking R files for syntax errors ... OK
* checking whether the package can be loaded ... OK
* checking whether the package can be loaded with stated dependencies ... OK
* checking whether the package can be unloaded cleanly ... OK
* checking for unstated dependencies in R code ... OK
* checking S3 generic/method consistency ... OK
* checking replacement functions ... OK
* checking foreign function calls ... OK
* checking R code for possible problems ... OK
* checking Rd files ... OK
* checking Rd metadata ... OK
* checking Rd cross-references ... OK
* checking for missing documentation entries ... OK
* checking for code/documentation mismatches ... OK
* checking Rd \usage sections ... OK
* checking Rd contents ... OK
* checking for unstated dependencies in examples ... OK
* checking contents of 'data' directory ... OK
* checking data for non-ASCII characters ... OK
* checking data for ASCII and uncompressed saves ... OK
* checking examples ... OK
* checking PDF version of manual ... OK

Here is what the complete R package looks like: ecg_1.0.tar.gz

5. Upload the package to CRAN

If R CMD check indicates that all checks are passed (OK), then the package is structured correctly, and may be uploaded to the Comprehensive R Archive Network (CRAN). Packages in the CRAN are freely available for download. In particular, CRAN packages may be installed using the R function install.packages.

To upload your package to CRAN, follow the instructions in the Writing R Extensions Manual.


Add a Package Vignette with Sweave

A package vignette is a short article that describes the package. Vignettes are often instructive, or tutorial like. We can use Sweave to create a vignette by creating the inst/doc subdirectories in the package hierarchy, and placing an Sweave file (i.e. a file ending in .Rnw) there. During the R CMD build and R CMD check processes, the vignette is automatically Sweave'd and included with the package. Package vignettes may be accessed at the R prompt using the vignette() command.

Here's a simple vignette for illustration (saved to inst/doc/ecg.Rnw):
\documentclass{article}
%\VignetteIndexEntry{ecg}
\begin{document}
\begin{center}
\Large
{\tt ecg} Package Vignette
\normalsize
\end{center}
The following figure illustrates a sequence of low-pass filters, applied to a series of electrocardiographic recording.
<<fig=TRUE, keep.source=TRUE>>=
library('lattice')
library('ecg')
data('ecg')

#filter high frequency noise
fecg <- wlpf(ecg, 1/1000, 30)
fecg <- (fecg-mean(fecg))/sd(fecg)

#isolate respiration bias
recg <- wlpf(ecg, 1/1000, 1)
recg <- (recg-mean(recg))/sd(recg)

#subtract respiration bias from ecg signal
eecg <- fecg - recg

require(lattice)
xplot <- rep((0:(length(ecg)-1))/1000,4)
yplot <- c(ecg, fecg, recg, eecg)
gplot <- c(rep("Raw",length(ecg)),
           rep("High Frequency Filter",length(ecg)),
           rep("Low Frequency Filter",length(ecg)),
           rep("ECG",length(ecg)))
tp <- xyplot(yplot ~ xplot | gplot, type="l",
     layout=c(1,4), xlab="Time", ylab="V")
print(tp)
@
\end{document}

Once the vignette is written, it is necessary to build and check the R package (step 4.) again. Here is the complete R package, with vignette: ecg_plus_vignette_1.0.tar.gz

Resources


Comments

  • R CMD check doesn't ensure that your package documentation is 'good', only that it is structured correctly
  • R CMD check doesn't ensure that your package code does anything useful

Topic attachments
I Attachment Action Size Date Who Comment
ecg.RR ecg.R manage 0.7 K 08 Jun 2011 - 23:25 MattShotwell Step 1. R Code
ecg_1.0.tar.gzgz ecg_1.0.tar.gz manage 34.3 K 08 Jun 2011 - 23:53 MattShotwell The complete R package: ecg
ecg_plus_vignette_1.0.tar.gzgz ecg_plus_vignette_1.0.tar.gz manage 435.4 K 09 Jun 2011 - 00:19 MattShotwell The complete R package, with vignette: ecg
Topic revision: r5 - 14 Jun 2011, MattShotwell
 

This site is powered by FoswikiCopyright © 2013-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Vanderbilt Biostatistics Wiki? Send feedback