Session details

Objectives

  1. To learn how functions are structured and created.
  2. To learn and apply the typical workflow for creating functions in packages (and in general).
  3. To properly document and name functions so you don’t forget what they do! 😜

At the end of this session you will be able:

  • Create a function with several arguments.
  • Add and fill out roxygen documentation to the function.
    • Using the “Code”->“Insert Roxygen Skeleton” (Ctrl-Shift-Alt-R)
    • Then creating the documentation using `devtools::
  • Cycle between testing the function out in the @example section and developing the function.
    • Using devtools::load_all() (Ctrl-Shift-L).
    • Run the code in the @example by typing Ctrl-Enter.
    • Repeat until the function does what you want!

Ultimately, I hope you will try to create a function from your own code by the end of this session!

Resources for learning and help

Initial setup

First we need to create a package layout and create an R script. See the Package Creation session for more details on this.

  1. Create a package using usethis::create_package("<pkgname>")
  2. Add an R script using usethis::use_r("<scriptname>.R").

All actions in R are functions

The + is a function, mean() is a function, [] is a function… everything that does something is called a function in R. So to add 1 with 1:

… is a function that takes 1 and adds 1 to it. It is actually a short form for:

When creating a function, there is always the basic structure of:

  1. Name of the function (e.g. mean).
  2. The function call using function() being assigned <- to the name. This tells R that the name is a function object… that it does some action.
  3. The arguments within the function call, function(arg1, arg2, arg3). These are the options given to the function (e.g. sum(arg1, arg2)).
  4. The body of the function, that takes the arguments, if any, does some action, and finishes by outputting some result or object at the end (using return()).

There is no minimum or maximum number of arguments you can provide for a function. E.g. you can have zero arguments or you can have 100s. To keep things sane, try to keep the number of arguments low, like not more than 4 or 5.

So, the structure is:

… and an example:

You can use the new function by running the above code and writing out your new function, with arguments to give it.

The function name is fairly good… add_nums can be read as “add numbers”. But we need to also add some formal documentation to the function. Using the “Insert Roxygen Skeleton” in the “Code” menu list (or by typing Ctrl-Shift-Alt-R) you can add template documentation right above the function. It looks like:

In the Title area, this is where you type out a brief sentence or several words that describe the function. Creating a new paragraph below this line allows you to add a more detailed description. The other items are:

  • @param num lines are to describe what each argument is for.
  • @return describes what output the function provides. Is it a data.frame? A plot? What else does the output give?
  • @export this is to tell R that this function should be accessible to the user of your package. Keep it in for now.
  • @examples lines below this are used to show examples of how to use the function. This is also the area where you write and test that the function does what you want. You can run code here as if it was regular R code and not a commented out code by using Ctrl-Enter.

Now, when we run devtools::document() (or Ctrl-Shift-D), a file will be added to the man/ folder. Now, when you type out ?add_nums in the console, the help documentation will pop up on the “Help” tab.

Ok, let’s get to something a bit more interesting. A common thing that people do (at least I do) is to create a similar plot on different variables and datasets. So this is a great example of using a function to simplify your code. We can also cover… package/function dependencies! Since we will use ggplot2 to make the plot, we need some way to tell R that the functions come from ggplot2… It’s very bad practice to use library() in your function and in your package. A function from usethis comes to the rescue! Use usethis::use_package("ggplot2") in the console. Some text will appear saying that “ggplot2 has been added to DESCRIPTION” and that “please refer to functions using ggplot2::fun”. So let’s do that!

Ok, we have the base for making a scatter plot. But! There are few things to talk about here first. First, ggplot2 will be confused by the x = xvar since it will think1 you are asking for the xvar column in the dataset. So, we need to change aes to aes_string to force ggplot2 to read xvar as a character string that is the name of the column you want to plot. Next, it is useful in many cases to put a dot before your function arguments to differentiate your function arguments from other R objects. Let’s also add the Roxygen documentation. So:

Now we do devtools::load_all() (Ctrl-Shift-L) and run the code in the example (Ctrl-Enter). A quick note: Running code in the @examples section only works if you are in an R package project (the RStudio .Rproj file). If you are not in an R package, you can instead include the code to run the function below your new function, like so:

Now, if we want to add some theme items, all graphs created from this function will get the new theme and appearance!

If you want to make sure that who ever uses your function will not use a wrong argument, you can use “defensive programming” via the stopifnot() function. This forces the code to only work if xvar and yvar are character (e.g. "this") argument.

Exercise: Make your own function!

Using this workflow, try to create, document, and test your own function! If you have some code that you already use repeatedly by copy and pasting, try to convert that code into a function. If you don’t have your own code, try converting these pieces of code into their own function:

  1. The reason it won’t work is because ggplot2 is using what is called non-standard evaluation (NSE; check out here or here for more indepth look at what non-standard evaluation is). Because ggplot2 uses NSE, you will have to do things slightly differently, hence using aes_string.↩

This work is licensed under a Creative Commons Attribution 4.0 International License. See the licensing page for more details about copyright information.