R Functions Tutorial: Writing, Scoping, Vectorizing, and More!

Writing R Functions

While R has some very cool and complex generic functions, there isn’t always going to be a built-in function for generating the output we want. Writing custom functions is an important part of programming, including programming in R.

As with vectorization, writing our own functions can streamline and speed up our code! As a general rule, if we find ourselves doing the same (or a similar) thing over and over, it might be time to write a function.

Syntax

To create a new R function we need to think about 4 major things:

• the name of the function
• the arguments (inputs) the function will take
• the code the function will run
• the output the function will return for the user

To see these four things in action, let’s write our own function to see whether the job descriptions in our data set mention a PhD.

We’ll start by giving it a clear name: phdFinder(). We’ll create a variable called phdFinder to store our function. To create a function, we use function(){}.

phdFinder <- function(){

}

Above, the parentheses are empty, but that’s where we will list the names for any arguments (inputs) that our function will need to run. Arguments are used to pass R objects/variables from outside the function into the function.

When choosing our arguments, it helps to ask: “which variables might be different each time this function is run?”. If a variable is likely to change, it should probably be specified as an argument rather than hard-coded inside the code the function will run.

In our function, the only thing that will be different is job description, so we’ll add a variable called description as an argument.

phdFinder <- function(description){
}

Next, we need to consider the code that the function will run. This is what we want the function to do to the argument or arguments we’ve passed it. For now, we’ll assume that we’re only looking for the string “PhD”, and that any other capitalization like “PHD” won’t count, so we’ll want the code inside our function to look at each description it gets passed to see if it finds that string.

grepl() is a built-in R function looks for a smaller string of characters (like “PhD”) inside a larger one (like our description). It will return TRUE if “PhD” is in the description, and FALSE if it was not. Let’s add this to our function code, and assign the result of its assessment to a variable called mentioned.

phdFinder <- function(description){
  mentioned <- grepl("PhD",description)
}

The last thing we need to think about is what we want our function to return. Here, we want it to return mentioned, which will tell the user whether each description includes “PhD” (in which case mentioned will be TRUE) or not (in which case mentioned will be FALSE.

By default, R will return the value of the last statement we ran. phdFinder() only has one statement, so by default our function will return mentioned, with no extra work necessary! But if we wanted to explicitly tell R what to return, we could use the return() function.

If we do use return(), though, we need to be careful. The return() function tells R that the function is done running. So once that code runs, the function will stop.

To demonstrate this, let’s add a return() line and then add a couple of print statements after it.

phdFinder <- function(description){
  print("checking...")
  mentioned <-  grepl("PhD",description)
  return(mentioned)
  print("YOU SEARCHED FOR A PHD!")
}

Note that running this code produces no output — the print statement is never run, because R stops executing the function at return(mentioned).

Using R Functions

Now that we’ve written our custom function, let’s try it out! We didn’t just write it for kicks and giggles. Let’s take a look at the first job description in our original data set (stored as the data frame df) and check to see whether or not that job requires a PhD.

phdFinder(df[1,"description"])
## [1] "checking..."
## [1] FALSE

It looks like there’s no mention of a PhD in that job description. That’s great news if we want a job that doesn’t require one.

Notice again that only the first print statement ran, not the second. As mentioned before, once the return() function is called, none of the following code will run.

We can also use our phdFinder() function on the entire column of descriptions at once. Yup, it’s automatically vectorized!

Let’s create a new column in df called phd and store the results of calling phdFinder() on df$description there.

df$phd <- phdFinder(df$description)
head(df$phd)

print(sum(df$phd)/length(df$phd))
## [1] "checking..."
## [1] FALSE FALSE FALSE FALSE  TRUE FALSE
## [1] 0.2415279

24% of the job descriptions in our data frame mention PhDs, which is useful information. If we know a job is looking for someone with a PhD, it tells us a little about how to market ourselves, even if we don’t have one.

In the real world, we’d probably want to write some additional code to account for variant spellings like “PHD”, “Ph.D”, “phd”, etc., before we draw any serious conclusions from this data.

We skipped that step in the code we’ve written here to make what’s going on with our functions a bit easier to understand, but if you want to get more practice writing functions, rewriting our function with more complex code that accounts for these variants would be a great next step! Hint: you might want to start by looking into functions called tolower() and gsub().

Writing Good R Functions

Now that we know a little bit about how to write an R function, it’s time we had the talk. The talk about how to write good R functions.

First of all, we should write R functions as if someone else is going to be using them, because often they will be! But even if no one else is going to be using our code, we might want to re-use it later, so writing readable code is always a good idea.

Variable Names and Comments

Part of writing readable code means choosing argument and variable names that make sense. Don’t just use random letters (something I might be guilty of doing sometimes), use something meaningful.

For example, above we chose the variable name mentioned because this variable tells us whether “PhD” was mentioned. We could have called it x or weljhf, but by calling it mentioned we help ourselves and others better understand what’s being stored in that variable.

Similarly, giving our function a descriptive name like phdFinder() can help communicate what the function does. If we called this function something more cryptic, like function_47() or pf(), someone else reading our code would have a hard time figuring out what it does at a glance.

Scoping

Another thing to think about is scope. We can think of our global R environment — our entire program — as a room that holds all the objects, variables, functions, etc. that we have used.

This includes objects we’ve loaded as part of loading a library(). When we use a variable x, R will look around the room we’re in to find the value of x (we can check what’s in our environment using ls()).

When we write and run a function, R creates a new, temporary environment for the function. This is sort of like having a box in our room. The “box” holds all the objects we’ve created, changed, and used inside the function. But once the function is finished running, that box disappears.

Let’s look at a few examples to get a better idea of how this works. We’ll run a few different snippets of code. In each case, we’ll create an object (either a vector or a data frame) and pass it to our function, square, which returns the square of the number or numbers we passed it.

Note in the code below how the value of the variable x changes depending on whether it’s outside the function (a global variable) or whether it’s inside the function. The value of x can be reassigned within the function, but since the function environment is temporary and stops existing after the function is run, the global value of x doesn’t change:

x <- 10
print(paste("Outside the function, x is...", x))

square <- function(y){
  x <- y**2
  print(paste("Inside the function, x is...", x))
}

square(x)
print(paste("Outside the function, x is...", x))
## [1] "Outside the function, x is... 10"
## [1] "Inside the function, x is... 100"
## [1] "Outside the function, x is... 10"
x <- c(1,2,3)
print(paste("Outside the function, x is...", x[1],x[2],x[3]))

square <- function(y){
  x <- y**2
  print(paste("Inside the function, x is...",  x[1],x[2],x[3]))
}

square(x)
print(paste("Outside the function, x is...",  x[1],x[2],x[3]))
## [1] "Outside the function, x is... 1 2 3"
## [1] "Inside the function, x is... 1 4 9"
## [1] "Outside the function, x is... 1 2 3"
x <- data.frame(a = c(1,2,3))
print("Outside the function, x is...")
print(x)

square <- function(y){
  x$square <- x$a**2
  print("Inside the function, x is...")
  print(x)
}

square(x)
print("Outside the function, x is...")
print(x)
## [1] "Outside the function, x is..."
##   a
## 1 1
## 2 2
## 3 3
## [1] "Inside the function, x is..."
##   a square
## 1 1      1
## 2 2      4
## 3 3      9
## [1] "Outside the function, x is..."
##   a
## 1 1
## 2 2
## 3 3

To write good R functions, we need to think about where the objects we’re working with are. If there’s something outside the function environment that we want to use inside it, we can bring it in by passing it as an argument to our function.

If we don’t, R will look outside the “box” and search for the variable in the global environment (the “room”). But in order to make our function as generalizable as possible, and to avoid any issues with naming two variables the same thing, it’s a good idea to explicitly give our R function the objects it needs to run by passing them as arguments.

Getting Things Inside A Function

Let’s take a look at what happens when we call a global variable inside a function without explicitly passing it as an argument. To do this, we’ll create a new function called wordFinder(), similar to our phdFinder().

We’ll write this function to make it look for the variable my_test_word in each job description. But my_test_word doesn’t exist inside the function environment, because it isn’t passed in as an argument, nor created inside the function. So what will happen?

Once R searches this local environment and comes up empty, it will search the global environment for my_test_word. Since my_test_word exists in the global environment, R will use that inside the function.

my_test_word <- "python" #R uses "python" for my_test_word because it can't find my_test_word in the local function environment

wordFinder <- function(description){
  print(paste("checking for...", my_test_word))
  mentioned <-  grepl(my_test_word,description)
  return(mentioned)
  
}

wordFinder(df[1,"description"])
## [1] "checking for... python"
## [1] FALSE

What if we define my_test_word twice, both inside and outside the function? Let’s give it a shot!

Outside the function, in the global environment, we’ll give my_test_word the value 'python'. Inside the function, we’ll assign it the value 'data'.

Since we already know that R searches the function environment before the global environment, we might predict that R will use 'data' as the value of my_test_word, since that’s the value that’s assigned inside the function. Indeed, that’s what happens:

my_test_word <- "python" 

wordFinder <- function(description){
  my_test_word <- "data" #R uses "data" for my_test_word because it searches the local environment first
  print(paste("checking for...", my_test_word))
  mentioned <-  grepl(my_test_word,description)
  return(mentioned)
  
}

wordFinder(df[1,"description"])
## [1] "checking for... data"
## [1] TRUE

When we run this code block, we can see that R uses 'data' (the value of my_test_word inside the function) rather than 'python'. When my_test_word was referenced in grepl(), R first searched the local function environment and found my_test_word. So it didn’t need to search the global environment at all.

This is important to keep in mind when writing functions: R will only search the global environment for a variable if it doesn’t find that variable in the function environment (either as an argument or as a variable defined within the function itself).

Getting Things Out of a Function

It’s nice that R tidies up for us by removing the local function environment after a function has run, but what if we want to keep something a value generated inside a function after the function has run?

We can keep things created or changed inside the function by returning them. When we return a variable from a function, it allows us to store it in the global environment (if we so choose).

In wordFinder(), we return mentioned. Since R removed the local function environment, mentioned doesn’t exist anymore. When we try to print it out, we get an error.

my_test_word <- "python" 

wordFinder <- function(description){
  my_test_word <- "data" #R uses "data" for my_test_word because it searches the local environment first
  print(paste("checking for...", my_test_word))
  mentioned <-  grepl(my_test_word,description)
  return(mentioned)
  
}

wordFinder(df[1,"description"])
print(mentioned)
## Error in print(mentioned): object 'mentioned' not found
## [1] "checking for... data"
## [1] TRUE

However, since wordFinder() returns the value of mentioned, we can store it in our global environment by assigning the output of our function to a variable. Now we can use that value outside the function.

my_test_word <- "python" 

wordFinder <- function(description){
  my_test_word <- "data" #R uses "data" for my_test_word because it searches the local environment first
  print(paste("checking for...", my_test_word))
  mentioned <-  grepl(my_test_word,description)
  return(mentioned)
  
}

mentioned2 <- wordFinder(df[1,"description"])
print(mentioned2)
## [1] "checking for... data"
## [1] TRUE

Now we’ve got the value from inside the function preserved outside of it.

In Review:

Functions in R have a lot of uses, so let’s debrief with a few bullet points:

• R functions are pieces of code that take inputs, called arguments, and turn them into outputs.
• Arguments go inside a function’s parentheses both when we define a function and anytime we call a function.
• Outputs are the objects that are returned by the function.
• By default R will return the value of the last statement in the function. Everything else that may have been changed or created in the function will disappear once the function is done running unless we intentionally take steps to preserve it.
• R Functions are made to be used over and over. This saves us time, space, and makes our code look better.
• R Functions are often vectorized, which means that we can run the function for each item in a vector, like a column of data in a data frame, all in one go! This often saves a lot of time.
• Generic R Functions are functions that run differently based on the class of the object passed to it as an argument.
• Writing good R functions means thinking of others (and our future selves) and to make our functions easy to understand.

Now that you’ve got a solid understanding of the fundamentals of R functions, add to your skillset with Dataquest’s free, interactive R courses. Our Intermediate course will take you even deeper into the world of functions, all while letting you write code from right in your browser.