Self-written function help

[This article was first published on Deciphering life: One bit at a time :: R, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Self-written function help

I have noted at least one instance (and there are probably others) about how Python's docStrings are so great, and wouldn't it be nice to have a similar system in R. Especially when you can have your new function tab completion available depending on your development environment.

This is a false statement, however. If you set up your R development environment properly, you can have these features available in R. It will take a little bit of work, however.

This approach heavily depends on devtools and roxygen2.

RStudio

I do recommend using the RStudio IDE, as much of what I am discussing is very much integrated into the IDE itself. However, much of what I discuss is applicable regardless of what development environment you use.

Packages

First off, you probably want to put your functions into packages. Really, it's not that hard. A DESCRIPTION file, NAMESPACE, and an R directory with your function definitions. If you are using RStudio, then you can create a new project as a package. Alternatively, you can set up a new package directory using package.skeleton.

If you are using RStudio, I recommend setting your package options:

  • Generate package documentation with roxygen
    • Select all the options (especially regenerate Rd files on Build & Reload)

Whenever you make changes to your package functions, you simply commit (you are using version control, right??), and then Build & Reload (if using RStudio) or install() if using devtools.

Roxygen Documentation

For documentation that lives with your functions, I heavily recommend roxygen. Although the normal way to document stuff in R is through the use of Rd files, roxygen allows you to put the following in your R\functions.r file:

#' this is a silly function
#' @param input1 this is an input to our function
#' @param input2 this is another input
#' @return some value
#' @export
sillyFunction <- function(input1, input2){
  FunctionBody
}

When you do Build & Reload (or install), the required Rd file will be generated automatically, and upon Reloading the package, you will have full access to your documentation, and tab completion of your new function, along with descriptions of the parameters if you are using RStudio. Note, if you are not using RStudio, then you should do document to re-generate Rd files prior to doing install.

This particular workflow is how I now work in R, for almost every project that includes any self written functions, including analysis projects. Why I use this (and not another format such as ProjectTemplate) is another post, hopefully soon.

To leave a comment for the author, please follow the link and comment on their blog: Deciphering life: One bit at a time :: R.

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)