506 CHAPTER 21 Creating a package

#' @keywords datasets #' @name life

#' @usage life

#' @format A data frame with 50 rows and 4 variables. The variables #' are as follows:

#' \describe{

#' }

#' @source The \code{hlem} and \code{hlef} data were obtained from #' the Center for Disease Control and Prevention

#' \emph{Morbidity and Mortality Weekly Report} at \url{

#' http://www.cdc.gov/mmwr/preview/mmwrhtml/mm6228a1.htm?s_cid=mm6228a1_w}. #' The \code{region} variable was added from the

#' \code{\link[datasets]{state.region}} dataset. NULL

Note that the code in listing 21.7 consists entirely of comments. In the next section, you’ll process all the comments in the .R files in this section to create the package’s documentation. R requires that rigorous and structured documentation be included with any package.

21.3 Creating the package documentation

Every R package follows the same set of enforced guidelines for documentation. Each function in a package must be documented in the same fashion using LaTeX, a document markup language and typesetting system. Each function is placed in a separate

.R file, and the documentation for that function (written in LaTeX) is placed in a .Rd file. Both the .R and .Rd files are text files.

There are two limitations to this approach. First, the documentation is stored separately from the functions it describes. If you change the function code, you have to search out the documentation and change it as well. Second, the user has to learn LaTeX. If you thought R has a steep learning curve, wait until you start working with LaTeX!

The roxygen2 package can dramatically simplify the creation of documentation. You place comments in the head of each .R file that will serve as the function’s documentation. Then, the documentation is created using a simple markup language. When the file is processed by Roxygen2, lines that start with #' are used to generate the LaTeX documentation (.Rd file) automatically.

Look at the file contents in listings 21.4–21.7. The comments at the head of each file use the tags described in table 21.2. The tags (called roclets) are fundamental to how Roxygen2 creates LaTeX documentation.

To see what the resulting documentation looks like, be sure the npar package has been loaded, and request help on each of the functions (help(oneway), help (print.oneway), help(summary.oneway), and help(plot.oneway)). The help(life)

statement should provide information about the dataset. See help(rd_roclet) for more details about these tags.

Table 21.2 Tags for use with Roxygen2

A few additional markup elements are useful to know as you create documentation. The tag \code{text} prints text in code font, and \link{function} generates a hypertext link to an R function in the current package or elsewhere. Finally, \item{text} generates an itemized list. This is particularly useful for describing the results returned by a function.

There is a documentation task that is optional, but useful. As described so far, when a user installs the npar package, no help is available for ?npar. How is the user to know what functions are available? One way would be to type help(package="npar"), but you can make it easier for them by adding another file to the documentation; see the following listing.

Listing 21.8 Contents of the npar.R file

#' Functions for nonparametric group comparisons. #'

#' npar provides tools for calculating and visualizing #' nonparametric differences among groups.

#'

#' @docType package #' @name npar-package #' @aliases npar NULL

... this file must end with a blank line after the NULL...

Note that the last line of this file must be blank. When the package is built, a call to ?npar will now produce a description of the package, with a clickable link to an index of functions.

Finally, create a text file named DESCRIPTION that describes the package. Following is a sample.

Listing 21.9 Contents of the DESCRIPTION file

Package: npar Type: Package

Title: Nonparametric group comparisons Version: 1.0

Date: 2015-01-26 Author: Rob Kabacoff

Maintainer: Robert Kabacoff <robk@statmethods.net>

Description: This package assesses group differences using nonparametric statistics. Currently a one-way layout is supported. Kruskal-Wallis test followed by pairwise Wilcoxon tests are provided. p-values are adjusted for multiple comparisons using the p.adjust() function. Results are plotted via annotated boxplots.

LazyData: yes License: GPL-3

The Description: section can be span several lines but must be indented after the first line. The LazyData: yes statement indicates that the datasets in the package (life, in this case) should be available as soon as the package is loaded. If this was set to no, the user would have to use data(life) to access the dataset.

The final line indicates the license under which the package is being released. Common license types include MIT, GPL-2, and GPL-3. See www.r-project.org/Licenses for license descriptions. Of course, when creating your own package, don’t use my name (unless the package is really good!).

The roxygen2 package will be used in the next section, when you build the final npar package. To learn more about roxygen2, see Hadley Wickham’s description at http://mng.bz/K26J.

21.4 Building the package

It’s finally time to build the package. (Really, I promise.) The developer’s bible for creating packages is Writing R Extensions by the R Core Team (http://cran.r-project.org/ doc/manuals/R-exts.pdf). Friedrich Leishch also has produced a nice tutorial on creating packages (http://mng.bz/Ks84).

In this section, you’ll follow a streamlined process for building a package. Specifically, you’ll use Hadley Wickham’s roxygen2 package to simplify documentation creation. I’m building the package on a Windows machine, but the steps will work on Mac and Linux platforms as well:

1Install the necessary tools. Download and install the roxygen2 packages using install.packages("roxygen2", depend=TRUE). If you’re using a Windows platform, you’ll also need to install Rtools.exe (http://cran.r-project.org/bin/

windows/Rtools) and MiKTeX (http://miktex.org). If you’re using a Mac, install MacTeX (www.tug.org/mactex). Rtools, MiKTeX, and MacTeX are applications rather than packages. Therefore, you’ll need to install them outside of R.

npar) instead of just its name (npar).

3Generate the documentation. Load the roxygen2 package, and use the roxygenize() function to process the documentation headers in each code file:

>library(roxygen2)

>roxygenize("npar")

Updating namespace directives

Writing oneway.Rd

Writing plot.oneway.Rd

Writing print.oneway.Rd

Writing summary.oneway.Rd

Writing life.Rd

Writing npar-package.Rd

The roxygenize() function creates a new subdirectory, called man, that contains the .Rd documentation file for each function. The markup from the comments at the top of each code file is used to build these documentation files. roxygenize() also adds information to the DESCRIPTION file and creates a NAMESPACE file. The NAMESPACE file that is created for npar is as follows.

Listing 21.10 Contents of the NAMESPACE file

S3method(plot,oneway)

S3method(print,oneway)

S3method(summary,oneway)

export(oneway)

This creates a folder call npar.Rcheck in the current working directory. The folder contains the file 00.check.log, which describes the results of the checks. There must be no errors or warnings if you want to contribute the package to CRAN.

The directory also contains a file called npar-EX.R containing the code from any examples listed in the documentation. The text output produced by executing the example code is contained in the file npar-EX.out. If the examples created graphs (true in this case), they’re placed in npar-Ex.pdf.

6 Create a PDF manual (optional). Executing the statement

system("R CMD Rd2pdf npar")

generates a PDF reference manual like those you see on CRAN. If you ran step 5, you already have this document in the npar.Rcheck folder.

7 Install the package locally (optional). Executing

system("R CMD INSTALL npar")

installs the package on your machine and makes it available for use. Another way to install the package locally is to use

install.packages(paste(getwd(),"/npar_1.0.tar.gz",sep=""), repos=NULL, type="source")

You can see that the package has been installed by typing library(). After you type library(npar), the package will be available for use.

During the development cycle, you may want to delete a package from your local machine so that you can install a new version. In this case, use

detach(package:npar, unload=TRUE) remove.packages("npar")

to get a fresh start.

8Upload the package to CRAN (optional). If you would like to share your package with others by adding it to the CRAN repository, follow these three steps:

■Read the CRAN Repository Policy (http://cran.r-project.org/web/packages/ policies.html).

■Make sure the package passes all checks in step 5 without errors or warnings. Otherwise the package will be rejected.

■Submit the package. To do so via web form, use the submission form at http://cran.r-project.org/submit.html. You’ll be sent an automated confirmation email that needs to be accepted.

To do so via FTP, upload the packageName_version.tar.gz file via anonymous FTP to ftp://cran.r-Project.org/incoming. Then send a plain-text email to CRAN@R-project.org from the maintainer email address listed in the package. Use the subject line “CRAN submission PACKAGE VERSION” without the quotes, where PACKAGE and VERSION are the package name and the version,