RPR-Functions

R Functions

 

Keywords:  Anatomy of a function: arguments, parameters and values; the concept of functional programming.

 

 

 

Abstract

In this unit we discuss the "anatomy"" of R functions: arguments, parameters and values, and how R's treatment of functions supports "functional programming".

 

This unit ...

Prerequisites

You need to complete the following units before beginning this one:

• RPR-Control_structures

 

Objectives

This unit will ...

• ... introduce the basic pattern of R functions;
• ... discuss arguments and parameters;
• ... show how to retrieve the source code from within a function;
• ... practice writing your own functions.

 

Outcomes

After working through this unit you ...

• ... know how to pass parameters into functions and assign the returned values;
• ... can read, analyze, and write your own functions.

 

Deliverables

• Time management: Before you begin, estimate how long it will take you to complete this unit. Then, record in your course journal: the number of hours you estimated, the number of hours you worked on the unit, and the amount of time that passed between start and completion of this unit.
• Journal: Document your progress in your Course Journal. Some tasks may ask you to include specific items in your journal. Don't overlook these.
• Insights: If you find something particularly noteworthy about this unit, make a note in your insights! page.

 

Evaluation

Evaluation: NA

This unit is not evaluated for course marks.

 

Contents

Functions

R is considered an (impure) functional programming language and thus the focus of R programs is on functions. The key advantage is that this encourages programming without side-effects and this makes it easier to reason about the correctness of programs. Function parameters are instantiated for use inside a function as the function's arguments, and a single result is returned. The return values can either be assigned to a variable, or used directly as the argument of another function. This means functions can be nested, and intermediate assignment is not required.

Functions are either built-in (i.e. available in the basic R installation), loaded via specific packages, or they can be easily defined by you (see below). In general a function is invoked through its name, followed by one or more arguments in parentheses, separated by commas. Whenever I refer to a function, I write the parentheses to identify it as such and not a constant or other keyword eg. log(). Here are some examples for you to try and play with:

cos(pi) #"pi" is a predefined constant.
sin(pi) # Note the rounding error. This number is not really different from zero.
sin(30 * pi/180) # Trigonometric functions use radians as their argument - this conversion calculates sin(30 degrees)
exp(1) # "e" is not predefined, but easy to calculate.
log(exp(1)) # functions can be arguments to functions - nested functions are evaluated from the inside out.
log(10000) / log(10) # log() calculates natural logarithms; convert to any base by dividing by the log of the base. Here: log to base 10.
exp(complex(r=0, i=pi)) #Euler's identity

There are several ways to populate the argument list for a function and R makes a reasonable guess what you want to do. Arguments can either be used in their predefined order, or assigned via an argument name. Let's look at the complex() function to illustrate this. Consider the specification of a complex number in Euler's identity above. The function complex() can work with a number of arguments that are explained in the documentation (see: ?complex). Its signature includes length.out, real, imaginary, and some more.

complex(length.out = 0, real = numeric(), imaginary = numeric(), modulus = 1, argument = 0)

The length.out argument creates a vector with one or more complex numbers. If nothing else is specified, this will be a vector of complex zero(s). If there are two, or three arguments, they will be placed in the respective slots. However, since the arguments are named, we can also define which slot of the argument list they should populate.

Consider the following to illustrate this:

complex(1)    # parameter is in the first slot -> length.out
complex(4)
complex(1, 2) # imaginary part missing
complex(1, 2, 3) # one complex number with real and imaginary parts defined
complex(4, 2, 3) # four complex numbers
complex(real = 0, imaginary = pi) # defining values via named parameters
complex(imaginary = pi, real = 0) # same thing - if names are used, order is not important
complex(re = 0, im = pi) # names can be abbreviated ...
complex(r = 0, i = pi)   # ... to the shortest string that is unique among the named parameters,
                         # but this is _poor_ practice, strongly advises against.
complex(i = pi, 1, 0) # Think: what have I done here? Why does this work?
exp(complex(i = pi, 1, 0)) # (The complex number above is the same as in Euler's identity.)

Task:
A frequently used function is seq().

• Read the help page about seq()
• Use seq() to generate a sequence of integers from -5 to 3. Pass arguments in default order, don't use argument names.
• Use seq() to generate a sequence of numbers from -2 to 2 in intervals of 1/3. This time, use argument names.
• Use seq() to generate a sequence of 30 numbers between 1 and 100. Pass the arguments in the following order: length.out, to, from.

 

On missing parameters

If a parameter is missing several things can happen. Let's illustrate wih a little function that returns the golden-ratio pair to a number, either the smaller, or the larger one.

goldenRatio <- function(x, smaller) {
  phi <- (1 + sqrt(5)) / 2
  if (smaller == TRUE) {
    return(x / phi)
  } else {
    return(x * phi)
  }
}

• If there's no way to recover, executing the function will throw an error:

goldenRatio(1)
# Error in goldenRatio(1) : argument "smaller" is missing, with no default

• If the function has a default parameter defined, it is used :

goldenRatio <- function(x, smaller = TRUE) {
  phi <- (1 + sqrt(5)) / 2
  if (smaller == TRUE) {
    return(x / phi)
  } else {
    return(x * phi)
  }
}

goldenRatio(1)
# [1] 0.618034

• Alternatively, the function body can check whether a parameter is missing with the missing() function, and then react accordingly:

goldenRatio <- function(x, smaller) {
  if (missing(smaller)) {
    smaller <- TRUE
  }
  phi <- (1 + sqrt(5)) / 2
  if (smaller == TRUE) {
    return(x / phi)
  } else {
    return(x * phi)
  }
}

goldenRatio(1)
# [1] 0.618034

goldenRatio(1, smaller = FALSE)
# [1] 1.618034

Why is this useful, if you could just define a default? Because the parameter can then be the result of a (complex) computation, based on other parameters.

 

Reading functions

 

Basic R

If the function is a normal R function, like the ones we have defined above, you can read the function code when type its name without parantheses:

goldenRatio

# function(x, smaller) {
#  if (missing(smaller)) {
#    smaller <- TRUE
#  }
#  phi <- (1 + sqrt(5)) / 2
#  if (smaller == TRUE) {
#    return(x / phi)
#  } else {
#    return(x * phi)
#  }
#}

But that strictly only works for functions which have been written in basic R code.

S3 methods

You might also get a line saying UseMethod(<function name>). Then you are looking at a "method" from R's S3 object oriented system - such a function is also called a "generic", because it dispatches to more specific code, depending on the type of the parameter it is being given. Use methods() to see which specific methods are defined, and then use getAnywhere(<function.class>) to get the code.

seq

# function (...)
# UseMethod("seq")
# <bytecode: 0x103f3f9c8>
# <environment: namespace:base>

methods(seq)

# [1] seq.Date    seq.default seq.POSIXt
# see '?methods' for accessing help and source code

getAnywhere(seq.default)

# Lots of code ...

 

Primitives

You might also get a line saying .Call(C_<function name> <arguments>). Then you are looking at a primitive - a function that has been compiled in the C programming language, for efficiency.

runif

# function (n, min = 0, max = 1)
# .Call(C_runif, n, min, max)
# <bytecode: 0x103a5b098>
# <environment: namespace:stats>

To read the C source code, just do a Google search for the function name in the repository where the R sources are kept:

• site:https://svn.r-project.org/R/trunk/src runif

This search finds runif.c (have a look).

 

Writing your own functions

R is a "functional programming language" and working with R will involve writing your own functions. This is easy and gives you access to flexible, powerful and reusable solutions. You have to understand the "anatomy" of an R function however.

• Functions are assigned to function names. They are treated like any other R object and you can have vectors of functions, and functions that return functions etc.
• Data gets into the function via the function's parameters.
• Data is returned from a function via the return() statement. One and only one object is returned. However the object can be a list, and thus contain values of arbitrary complexity. This is called the "value" of the function. Well-written functions have no side-effects like changing global variables.

# the function definition pattern:

<myName> <- function(<myArguments>) {
  # <documentation!>
	result <- <do something with the parameters>
	return(result)
}

In this pattern, the function is assigned to the name - any valid name in R. Once it is assigned, it the function can be invoked with myName(). The parameter list (the values we write into the parentheses following the function name) can be empty, or hold a list of variable names. If variable names are present, you need to enter the corresponding parameters when you execute the function. These assigned variables are available inside the function, and can be used for computations. This is called "passing variables into the function".

Task:

Quick Exercise

This exercise is similar to the while loop exercise. The only difference is to put the code into a function. Write a function countDown() so that you can start the countdown call from any number. For example calling countDown(5) should give:

[1]  "5"          "4"          "3"          "2"          "1"          "0"          "Lift Off!"

Solution ... No peeking!

countDown <- function(n) {
  start <- n
  countdown <- start
  txt <- as.character(start)

  while (countdown > 0) {
    countdown <- countdown - 1
    txt <- c(txt, countdown)
  }
  txt <- c(txt, "Lift Off!")
  return(txt)
}

# Try it ...
countDown(7)

 

The scope of functions is local: this means all variables within a function are lost upon return, and global variables are not overwritten by a definition within a function. However variables that are defined outside the function are also available inside.

We can use loops and control structures inside functions. For example the following creates a vector containing n Fibonacci numbers.

fibSeq <- function(n) {
   if (n < 1) { return( 0 ) }
   else if (n == 1) { return( 1 ) }
   else if (n == 2) { return( c(1, 1) ) }
   else {
      v <- numeric(n)
      v[1] <- 1
      v[2] <- 1
      for ( i in 3:n ) {
         v[n] <- v[n-2] + v[n-1]
      }
      return( v )
   }
}

 

Here is another example to play with: a function that calculates how old you are. In days. This is neat - you can celebrate your 10,000 birthday - or so.

Task:
Copy, explore and run ...

Define the function ...

# A lifedays calculator function

myLifeDays <- function(birthday) {
  if (missing(birthday)) {
    print ("Enter your birthday as a string in \"YYYY-MM-DD\" format.")
    return()
  }
  bd <- strptime(birthday, "%Y-%m-%d") # convert string to time
  now <- format(Sys.time(), "%Y-%m-%d") # convert "now" to time
  diff <- round(as.numeric(difftime(now, bd, unit="days")))
  print(sprintf("This date was %d days ago.", diff))
}

Use the function (example)

   myLifeDays("1932-09-25")  # Glenn Gould's birthday

Here is a good opportunity to practice programming: modify this function to accept a second argument. When a second argument is present (e.g. 10000) the function should print the calendar date on which the input date will be the required number of days ago. Then you could use it to know when to celebrate your 10,000^th life-day, or your 777^th anniversary or whatever.

 

 

Further reading, links and resources

 

Notes

 

Self-evaluation

 

 

---

 

If in doubt, ask! If anything about this learning unit is not clear to you, do not proceed blindly but ask for clarification. Post your question on the course mailing list: others are likely to have similar problems. Or send an email to your instructor.

---

 

About ...
 
Author:

Boris Steipe <boris.steipe@utoronto.ca>

Created:

2017-08-05

Modified:

2017-09-10

Version:

1.0

Version history:

• 1.0 Completed to first live version
• 0.1 Material collected from previous tutorial

---

This copyrighted material is licensed under a Creative Commons Attribution 4.0 International License. Follow the link to learn more.