Prepare for a new package project

Step 1 – install necessary packages Update RStudio if it is very old. Start RStudio and install package roxygen2. This package simplifies package documentation.

install.packages("roxygen2")

Step 2 – create a new package From RStudio menu, click file then new project and choose to create project in a new directory. Select creating R package and name the package, for example, as mytoolbox and place it in the directory of our choice. RStudio automatically creates several subdirectories and files.

Step 3 – allow roxygen2 to take care of documentation From RStudio menu click build then configure build tools, verify package is selected in Project build tools, check the box for Generate documentation with roxygen, in the popup dialogue box check all boxes.

Step 4 – delete NAMESPACE file to clear way for roxygen2 to automatically generate this file. Otherwise we will get a warning when building the package.

Add functions to the package

Create a .R files for a function and save it in subdirectory /R. A good practice is to have only one function in a .R file. We can have as many files as needed for all functions under subdirectory /R.

The .R file, let’s call it mess_up_function.R, has two sections, as shown in the example code below. The first is the Roxygen comment section, of which each line starts with #'. Roxygen2 generates documentation of the function from these comments. Most tags in the comment section are self-explanatory, for example @para for parameters and @examples for examples. Pay attention to these three tags: 1) #' @export exports the function for package users. 2) #' @import package_name or #' @importFrom package_name function_1 function_2 are to import whole packages or selected functions, depending on how we use these packages in building our own package. Import the whole package if we use many functions in the package; import only selected functions if we know we only need them.

The second section is the R code where we define our function. This section is standard R code with one exception: never use library(pkg_name) or require(pkg_name) to load packages, as they may mess up with name space. Instead, use #' @import or #' @importFrom as discussed in the Roxygen comment section, or use pkg_name::func(). The later method takes extra 4 microseconds for each run, which is acceptable for processing small datasets.

#' mess up function (This is the title.)
#' 
#' @description This function mess up with two strings by extracting vowels from
#' the first string and attaching them to the second.
#'
#' @param string_1 the first string
#' @param string_2 the second string
#' 
#' @return a string 
#'
#' @examples
#' # example 1
#' mess_up("The United States", "Russia")
#' 
#' # example 2
#' mess_up("Barack Obama", "Donald Trump")

#' @export
#' 
#' @importFrom stringr str_extract_all


mess_up <- function(string_1, string_2){
    ## This function extract vowels from string_1 and place it 
    ## at the end of string_2
    vowels <- str_extract_all(string_1, "[AEIOUaeiou]")[[1]]
    vowels <- paste0(vowels, collapse = "")
    paste0(string_2, vowels, collapse = "")
}

Add a dataset to the package

# one .RData file has ONLY one dataset
save(my_dataset, file = "path_to_package/data/my_dataset.RData")

#' Here is the title of the dataset
#'
#' @description More description of the dataset is here
#'
#' @docType data
#'
#' @usage data("my_dataset")
#'
#' @format data.frame
#'
#' @keywords datasets
#'
#' @source This is a link to 
#' \href{http://www.xxx.xxx.com/xxx.csv}{the origin data}
#'

"my_dataset"

Set up the DESCRIPTION file

This file mostly provides general information of the package. Many of them we may not care if we just write the package for ourselves. But two items are important: 1) If we want to load our dataset whenever loading the package, keep LazyData: true. 2) Place all other packages used in the package under Imports. In case others want to install this package, these packages will be installed automatically.

Package: my_package_name
Type: Package
Title: Title of package 
Version: 0.1.2
Author: my name
Maintainer: my name <[email protected]>
Description: Give a little bit more detailed description of the package which can 
    span multiple lines. 
License: your_choice
Encoding: UTF-8
LazyData: true
Imports:
    stringr (>= 1.2.0), 
    ggplot2 (>= 2.0.0)

Build the package

The last step is to build the package, which is very easy in RStudio. From the menu select Build and then Build and Reload. RStudio will take care of all that follow. After the package is successfully built, we can use this package as any other package in our work with library(mytoolbox) and enjoy the easy access to our functions and datasets.