Technical Article => Programming => R

Introduction

A set of user-defined functions (UDF) or utility functions are helpful to simplify our code and avoid repeating the same typing for daily analysis work. Previously, I saved all my R functions to a single R file. Whenever I want to use them, I can simply source the R file to import all functions. This is a simple but not perfect approach, especially when I want to check the documentation of certain functions. It was quite annoying that you can’t just type ?func to navigate to the help file. So, this is the main reason for me to write my own util package to wrap all my UDFs with a neat documentation.

Prerequisite

In order to write your R packages, you need packages of devtools and roxygen2 for the minimal.

devtools: for development actions, such as document, install, build and test

roxygen2: for R package documentation

Installing them is easy.

# install the pre-requisite install.packages(c('devtools','roxygen2'))

Step 1: Create A New R Project for Package

The first step is to create a new project in your R-studio by [File] > [New Project…]

Choose a [New Project].

Choose [R Packages using devtools].

Fill in your package name and location.

Step 2: Fill in DESCRIPTION

Once the project is created, we should get files organized as following:

R folder: is the place to put R functions

man folder: is the manual/document for functions

DESCRIPTION: general information for this package

NAMESPACE: exported functions for this package

Let’s fill in the DESCRIPTION file for general information for this package.

Step 3: Write Your R Functions & Documents

Now this is core part of your R package. Define your first simple function, maybe for example quantiles for a data-frame.

show_quantile <- function(df, q = seq(0,1,0.1)){ res <- list() for(v in colnames(df)){ if(is.numeric(df[,v])){ res[[v]] <- quantile(df[,v],q) } } return(res) }

The beautiful part comes here, you can use '# symbol to decorate the document for the functions.

first line: title of the function

third line: description of the function

@param: document for the arguement

@return: document for the return

@export: indicator whether to export to NAMESPACE

@examples: define the examples and test code

@importFrom: import function from other package

more details is here on roxygen2.

And the resulting R code looks like this:

#' show_quantile (title) #' #' calculate the quantiles for all numeric columns (description) #' #' @param df dataframe that quantile function performed on (function arguement) #' @param q quantiles, defaults to 0 to 1, with step of 0.1 (function arguement) #' @return list (return) #' @export (add this, if you want the functions availabe in NAMESPACE) #' @examples (define the examples/test code) #' data(iris) #' show_quantile(iris) show_quantile <- function(df, q = seq(0,1,0.1)){ res <- list() for(v in colnames(df)){ if(is.numeric(df[,v])){ res[[v]] <- quantile(df[,v],q) } } return(res) }

Document the package by typing devtools::document()

Step 4: Install and Test

Run devtools::install() to install the package and we can observe that the package is already available from R-studio under the packages tab.