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 function wlpf
, data ecg
, 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.
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 you should ... read and delete.
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: lattice
License: GPL
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)
@
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