Creating a package in R

Everyone comes to one point and think that it is the right time to create a package. I have seen people create separate packages for their projects. In this document I will show you some basic tools that you will require to create a new package.

Before we move into creating a package, let us first understand the files that are created in a complete package.

- data
- inst
- man
- R
- vignettes
- DESCRIPTION
- NAMESPACE

There are couple of packages that help us while writing a package. They are devtools and roxygen2.

Let us install these two packages first.

install.packages("devtools")
install.packages("roxygen2")

Once you have installed the packages, let us create a package creation process.

We will use Rstudio to create the package skeleton at first. 1. Create a new project in R and then choose to create a package. 2. After choosing to create a package, Rstudio will create a project with all the necessary file to create a package.

Now, the following folders will be created.

DESCRITPTION
man
NAMESPACE
R

Data

If you want to include dataset into your package, then you can create a new folder named data into your project.

I would recommend saving the data into R native format .rda and use save command in R while saving the data. For example:

save(test, file = "test.rda")
# To create a help file on that rda file use prompt
prompt(test)

## Created file named 'test.Rd'.
## Edit the file and move it to the appropriate directory.

Help file created by prompt function for the data frame test

\name{test}
\alias{test}
\docType{data}
\title{
%%   ~~ data name/kind ... ~~
}
\description{
%%  ~~ A concise (1-5 lines) description of the dataset. ~~
}
\usage{data("test")}
\format{
  A data frame with 6 observations on the following 24 variables.
  \describe{
    \item{\code{info}}{a factor with levels \code{REACH}}
    \item{\code{rch}}{a numeric vector}
    \item{\code{gis}}{a numeric vector}
    \item{\code{mon}}{a numeric vector}
    \item{\code{area_km2}}{a numeric vector}
    \item{\code{sed_in_tons}}{a numeric vector}
    \item{\code{sed_out_tons}}{a numeric vector}
    \item{\code{sand_in_tons}}{a numeric vector}
    \item{\code{sand_out_tons}}{a numeric vector}
    \item{\code{silt_in_tons}}{a numeric vector}
    \item{\code{silt_out_tons}}{a numeric vector}
    \item{\code{clay_in_tons}}{a numeric vector}
    \item{\code{clay_out_tons}}{a numeric vector}
    \item{\code{smag_in_tons}}{a numeric vector}
    \item{\code{smag_out_tons}}{a numeric vector}
    \item{\code{lag_in_tons}}{a numeric vector}
    \item{\code{lag_out_tons}}{a numeric vector}
    \item{\code{gra_in_tons}}{a numeric vector}
    \item{\code{graout_tons}}{a numeric vector}
    \item{\code{ch_bnk_tons}}{a numeric vector}
    \item{\code{ch_bed_tons}}{a numeric vector}
    \item{\code{ch_dep_tons}}{a numeric vector}
    \item{\code{fp_dep_tons}}{a numeric vector}
    \item{\code{tss_mgL}}{a numeric vector}
  }
}
\details{
%%  ~~ If necessary, more details than the __description__ above ~~
}
\source{
%%  ~~ reference to a publication or URL from which the data were obtained ~~
}
\references{
%%  ~~ possibly secondary sources and usages ~~
}
\examples{
data(test)
## maybe str(test) ; plot(test) ...
}
\keyword{datasets}

As you can see, the prompt function automatically created a help file named test.Rd and it has created fields for all the variables that are in the data. In the items displayed in help file shown above, we can change the description of the individual variables. The help file should be eventually saved on man folder. test.rda file should be saved in data folder.

Functions

All the functions written should be placed in R folder. For example, you want to include some additional files that are not function, but are acutal analysis that you performed, then you could create a inst folder and create sub-folders.

Using devtools

Document the package

library(devtools)
document(pkg-name)
# If you have created a project for package, you can simply use
document()

You will get information such as following

> document()
Updating pkg-name documentation
Loading pkg-name
Writing NAMESPACE
Writing test-function.Rd

Build the package
Now, after we have finished documenting the package, it is time to build a package from the files, that we have created so far.

build()
# build() command in devtools is equivalent to CMD build

Check the package In order to check, if the package we have created is error-free, we should always use the check function

check()

If you get any error / warnings / note, R-studio will give you information where the details are stored so it will help users to fix the issues.

Install the package

Now, that you have finished creating a package, it is the time to install the package into R so that you could use all the functions / data stored in the package.

R creates the package in *.gz format. So, find out the location where you pkg.gz is stored.

# Package location: C:/Users/DSI/Documents/pkg/pkg_0.1.tar.gz
install.packages("C:/Users/DSI/Documents/pkg/pkg_0.1.tar.gz",
                 repos = NULL, type = "source")

Loading the package
library(pkg)

View Help files in package

In order to view the help files in the package, use the following query: ??pkg

After use the `??pkg code, you can see all the vignettes and help pages for the package can be viewed.

I hope this document helped you somewhat to create a new package in R.

Creating a package in R

Janesh Devkota

December 22, 2016

Using devtools

Install the package