Writing and calling functions

Reading:

• Matloff Section 1.3, 7.3-7.6 (7.6 is presented rather formally), 7.12, 7.13

• If you want more detail on environments: Advanced R by Hadley Wickham has a good chapter on them. That chapter makes a distinction between a function’s enclosing environment and its binding environment, but for the purposes of this class we are going to assume those are always the same.

• More relevant for next time: Clean Code by Robert Martin, Chapter 3.

Today: Nuts and bolts, technical aspects of functions in R.

Next time: More practical advice on how to write functions, best practices, etc.

Why write functions?

• Make your code more readable.

What is a function?

• A way of turning some inputs into some outputs.

Function creation

Syntax for function creation:

f <- function(argument) {
    body
}

• arguments are variables used by the function.

• body is the code you want to execute.

Arguments: formal and actual

• Formal argument: the variable name used in the function definition.

• Actual argument: the actual value of the variable used when the function is called.

Idea: You want to be able to evaluate the function for any possible actual argument value, and the formal argument is a placeholder.

So for example, if we return to our steak-cooking example from a couple lectures ago, we might define the following function:

steak_directions <- function(temp, steak_type) {
    if(steak_type == "rare" && temp > 115) {
        return("take your steak off!")
    } else if(steak_type == "med_rare" && temp > 125) {
        return("take your steak off!")        
    } 
    "you can keep cooking"
}

We can see the arguments and body of the function using formals and body, respectively.

formals(steak_directions)

## $temp
## 
## 
## $steak_type

body(steak_directions)

## {
##     if (steak_type == "rare" && temp > 115) {
##         return("take your steak off!")
##     }
##     else if (steak_type == "med_rare" && temp > 125) {
##         return("take your steak off!")
##     }
##     "you can keep cooking"
## }

Function arguments

Once you have a function, you call it by specifying the values for all of the arguments. The values can be specified in two ways:

• By position: first argument is assigned to the first variable in the function definition, second argument to the second variable in the function definition, and so on

• By name: arguments are specified by name instead of being inferred based on position.

The two can be combined.

Default arguments

When you define a function, you can set default values for any/all of the arguments.

When you call such a function, if you don’t specify a value for that argument, it will automatically go to the default value.

Return values

When a function is called, the commands in the body of the function are executed, and a value is returned.

The return value is either:

• The value of last command executed, or

• A value set explicitly using the return syntax.

The commands in the body of the function are executed until a return statement is encountered or the the end of the body is reached, whichever comes first.

Invisible return

Invisible return is a bit R-specific:

• If you use invisible instead of return in a function definition, the result will be discarded unless it is assigned.

• This is not usually something that you will use, but some of the built-in functions use invisible returns.

Another example: compare the two versions of oddcount:

oddcount <- function(x) {
    k <- 0
    for(n in x) {
        if (n %% 2 == 1) k <- k + 1
    }
    return(k)
}
oddcount(x = c(0, 5))

## [1] 1

oddcount <- function(x) {
    k <- 0
    for(n in x) {
        if (n %% 2 == 1) k <- k + 1
    }
}
oddcount(x = c(0, 5))
oddcount_output <- oddcount(x = c(0, 5))
oddcount_output

## NULL

Return values can be anything

• If you want to return multiple related pieces of information, you can put them in a list or other type of object.

g <- function() {
    t <- function(x) x^2
    return(t)
}
g

## function() {
##     t <- function(x) x^2
##     return(t)
## }

g()

## function(x) x^2
## <environment: 0x127433420>

formals(g)

## NULL

formals(g())

## $x

body(g)

## {
##     t <- function(x) x^2
##     return(t)
## }

body(g())

## x^2

Environments and scope

When you call a function, the commands in the function body are executed, but not in exactly the same way they would be if you simply ran them one at a time in an interactive R session.

The commands are executed in the function’s execution environment.

Environments

Ok, so what is an environment?

• An environment binds names to values.

For example, have you ever wondered how R finds functions?

The function lm is not in the global environment, as we can see if we just call ls:

ls()

## [1] "corner"           "g"                "multiplot"        "oddcount"        
## [5] "oddcount_output"  "square"           "square_invisible" "steak_directions"
## [9] "xsquared"

But we are able to access it and, for instance, ask what its arguments are:

head(formals(lm))

## $formula
## 
## 
## $data
## 
## 
## $subset
## 
## 
## $weights
## 
## 
## $na.action
## 
## 
## $method
## [1] "qr"

Functions live in environments corresponding to the package they are defined in. For lm, this is stats.

environment(lm)

## <environment: namespace:stats>

Package environments are all ancestral to the global environment, so when R found that lm wasn’t defined in the global environment, it looked through the packages until it found lm defined in stats.

Function environments

w <- 12
f <- function(y) {
    d <- 8
    h <- function() {
        return(d * (w + y))
    }
    cat("h's enclosing environment: ", "\n")
    print(environment(h))
    cat("parent of h's enclosing environment:", "\n")
    print(parent.env(environment(h)))
    output <- h()
    return(output)
}
f(1)

## h's enclosing environment:  
## <environment: 0x127df38c8>
## parent of h's enclosing environment: 
## <environment: R_GlobalEnv>

## [1] 104

environment(f)

## <environment: R_GlobalEnv>

This perhaps seems overly baroque, but the take-home points about environments (and the reason why they are set up the way they are) are:

• Commands called in the body of the function usually have access to values of the variables in that function plus variables at higher levels.

• Variables defined in the body of a function go away after the function exits.

Side effects

A function has a side effect if it does anything other than compute a return value, for instance, if it changes the values of other variables in the environment it is defined in, or adds variables to the environment.

We generally don’t want functions to have side effects, because they make code more confusing and more difficult to test.

In R, functions can have side effects, but it is discouraged by both the language itself and by programming norms.