Today's Question:  What does your personal desk look like?        GIVE A SHOUT

Write Your Own R Packages

  sonic0002        2019-10-19 07:20:52       2,506        0    

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.

To test the package, we can restart the R session and use our favorite library command.

When we type ?show_quantiles, we can see the help information on the side panel.

(Optional) Step 5: Push package to Git

If you push the code to the git, we actually can install from cloud, so that sharing with others become easier. I uploaded my code to GitHub, so other people can use devtools to install this package as well.

The source code is available here on GitHub.

Reference

Notes: The post is authorized to be republished here by Chaoran Liu, who is a very experienced data scientist working in Singapore. The original post can be found here. To read more article from him, please refer to Chaoran's Data Story.

DATA SCIENCE  DATA ENGINEERING  R PROGRAMMING 

Share on Facebook  Share on Twitter  Share on Weibo  Share on Reddit 

  RELATED


  0 COMMENT


No comment for this article.