Writing functions

mean(c(1, NA, 3), na.mr = TRUE) returns NA, with no error and no warning: the misspelt argument was accepted and ignored. Functions are how R code is reused, and the way a function takes its arguments decides whether a slip like that fails loudly or passes in silence.

On runs of R 4.6.1 you will define functions with defaults and clear return values, predict how R matches the arguments of a call, check inputs at the top with stopifnot() and match.arg(), pass extra arguments through ..., and predict when an argument is computed, which R does only when the function first uses it.

A function returns the value of its last expression

mean_of(c(4, 8, 9)) returns 7. A function is made with function(arguments) body and stored under a name like any other value, and the help page ?function gives the rule for its result: when the end of the body is reached without a call to return(), the value of the last evaluated expression is returned. Step through one call, and one more that changes its argument:

The run defines five small functions and calls each:

from session import run, version

version()
# R reads anatomy.R as if each line were typed at the console.
run("""
R --vanilla --quiet -f anatomy.R
""")

# R version 4.6.1 -- "Happy Hop"
$ R --vanilla --quiet -f anatomy.R
> # A function returns the value of its last expression.
> mean_of <- function(x) {
+   total <- sum(x)
+   total / length(x)
+ }
> mean_of(c(4, 8, 9))
[1] 7
> # return() leaves early, here for an empty input.
> mean_safe <- function(x) {
+   if (length(x) == 0) return(NA_real_)
+   sum(x) / length(x)
+ }
> mean_safe(numeric(0))
[1] NA
> # Several results come back as one object, such as a named vector.
> describe <- function(x) c(n = length(x), mean = mean(x), max = max(x))
> describe(c(4, 8, 9))
   n mean  max 
   3    7    9 
> # invisible() returns a value without printing it.
> log_line <- function(text) {
+   line <- paste("Note:", text)
+   invisible(line)
+ }
> log_line("check row 12")
> saved <- log_line("check row 12")
> saved
[1] "Note: check row 12"
> # Changing an argument inside changes a local copy only.
> double_it <- function(v) {
+   v <- v * 2
+   v
+ }
> marks <- c(1, 2, 3)
> double_it(marks)
[1] 2 4 6
> marks
[1] 1 2 3

• return() is for leaving early. mean_safe() returns NA_real_ at once for an empty input, so the formula below it never divides by zero; the normal result is still its last line.
• Several results come back as one object. A function returns one value, so describe() returns a named vector, n, mean and max; a list does the same for results of different types.
• invisible() returns without printing. log_line("check row 12") printed nothing at the console, yet saved received the line. Use it for functions whose main job is a side effect, such as writing a file, so that the console stays quiet while the value is still there for whoever wants it.
• Arguments are local. double_it(marks) doubled its own v; marks was still 1 2 3 afterwards. A function changes nothing outside itself unless its result is assigned, marks <- double_it(marks).

The help page adds that \(x) x + 1 is a short form of function(x) x + 1, handy for the small functions passed to other functions in the next module.

Arguments match by exact name, then partial name, then position

fit(1:5, tr = 0.3) sets trim to 0.3, although the call never spells trim out. The R Language Definition describes how a call’s arguments are matched to a function’s formal arguments in three passes: first supplied names that equal a formal name exactly, then supplied names that are the start of exactly one formal name, then the unnamed values, by position, into the formals not yet matched. Arguments nobody supplied take their defaultsdefault: The value written for an argument in a function's definition, as in digits = 2, used when a call gives none. R computes it inside the function, when the argument is first used.. Step through the three passes:

The run tries the same function with names in different places, then the cases that stop:

from session import run, version

version()
# R reads matching.R as if each line were typed at the console.
run("""
R --vanilla --quiet -f matching.R
""")

# R version 4.6.1 -- "Happy Hop"
$ R --vanilla --quiet -f matching.R
> fit <- function(data, weights = NULL, trim = 0) {
+   sprintf("n = %d, weights: %s, trim = %.1f",
+     length(data), if (is.null(weights)) "none" else "given", trim)
+ }
> # Exact names first, then partial names, then positions.
> fit(1:5, trim = 0.1)
[1] "n = 5, weights: none, trim = 0.1"
> fit(trim = 0.1, 1:5)
[1] "n = 5, weights: none, trim = 0.1"
> fit(1:5, NULL, 0.2)
[1] "n = 5, weights: none, trim = 0.2"
> fit(1:5, tr = 0.3)
[1] "n = 5, weights: none, trim = 0.3"
> # A start that fits two names is an error.
> f <- function(value, verbose = FALSE) value
> try(f(v = 1))
Error in f(v = 1) : argument 1 matches multiple formal arguments
> # Arguments that match nothing are errors too.
> try(fit(1:5, colour = "red"))
Error in fit(1:5, colour = "red") : unused argument (colour = "red")
> # mean() takes na = TRUE for na.rm = TRUE, by partial matching.
> mean(c(1, NA, 3), na = TRUE)
[1] 2
> # This option makes R warn whenever it matches a name partially.
> options(warnPartialMatchArgs = TRUE)
> mean(c(1, NA, 3), na = TRUE)
[1] 2
Warning message:
In mean.default(c(1, NA, 3), na = TRUE) :
  partial argument match of 'na' to 'na.rm'

The first four calls all worked. A name can come before the value it skips, as fit(trim = 0.1, 1:5) shows, because names are matched before positions. f(v = 1) stopped, because v is the start of both value and verbose, and an argument that matches no formal at all, colour = "red", stopped with “unused argument”. mean() accepted na = TRUE as na.rm = TRUE by the same partial matching, and with options(warnPartialMatchArgs = TRUE) R said so.

Check the inputs at the top with stopifnot() and match.arg()

summarise_vec(c("62", "71")) stops at once with “x must be numeric”, the sentence written in the check. Each check at the top of a function turns a confusing failure deep inside it into a message that names the problem. The help page of stopifnot() says it stops at the first expression that is not all TRUE, and that names given to its arguments are used instead of the default message; R 4.0.0 added those names. match.arg(type) checks a choice against the vector of choices in the argument’s default, c("t", "normal"), accepts an abbreviation and returns the full name, and with no choice given returns the first. Step through the calls of the run:

The run builds the function, calls it twice with good input and once for each check:

from session import run, version

version()
# R reads validate.R as if each line were typed at the console.
run("""
R --vanilla --quiet -f validate.R
""")

# R version 4.6.1 -- "Happy Hop"
$ R --vanilla --quiet -f validate.R
> summarise_vec <- function(x, type = c("t", "normal"), level = 0.95) {
+   stopifnot(
+     "x must be numeric" = is.numeric(x),
+     "x needs at least 2 values" = length(x) >= 2,
+     "level must be one number between 0 and 1" =
+       length(level) == 1 && level > 0 && level < 1
+   )
+   type <- match.arg(type)
+   n <- length(x)
+   m <- mean(x)
+   se <- sd(x) / sqrt(n)
+   q <- if (type == "t") qt((1 + level) / 2, df = n - 1) else qnorm((1 + level) / 2)
+   round(c(n = n, mean = m, sd = sd(x), lower = m - q * se, upper = m + q * se), 2)
+ }
> marks <- c(62, 71, 55, 80, 67, 74)
> summarise_vec(marks)
    n  mean    sd lower upper 
 6.00 68.17  8.89 58.84 77.49 
> summarise_vec(marks, "norm")
    n  mean    sd lower upper 
 6.00 68.17  8.89 61.06 75.28 
> # Each check names its own problem.
> try(summarise_vec(c("62", "71")))
Error in summarise_vec(c("62", "71")) : x must be numeric
> try(summarise_vec(62))
Error in summarise_vec(62) : x needs at least 2 values
> try(summarise_vec(marks, level = 95))
Error in summarise_vec(marks, level = 95) : 
  level must be one number between 0 and 1
> try(summarise_vec(marks, level = NA))
Error in summarise_vec(marks, level = NA) : 
  level must be one number between 0 and 1
> try(summarise_vec(marks, "bootstrap"))
Error in match.arg(type) : 'arg' should be one of “t”, “normal”
> # several.ok = TRUE keeps the choices that match; "all" (R 4.6.0) refuses any that do not.
> match.arg(c("mean", "sdd"), c("n", "mean", "sd"), several.ok = TRUE)
[1] "mean"
> try(match.arg(c("mean", "sdd"), c("n", "mean", "sd"), several.ok = "all"))
Error in match.arg(c("mean", "sdd"), c("n", "mean", "sd"), several.ok = "all") : 
  'arg' should be one of “n”, “mean”, “sd”

The good calls give a 95 % interval of 58.84 to 77.49 with the t distribution and 61.06 to 75.28 with the normal, narrower because the normal ignores that the standard deviation was estimated from only six marks. level = NA stopped at the third check too: the expression gives NA, and stopifnot() treats anything but TRUE as a failure. length(level) == 1 comes first in that check because && needs single values, and the help page of stopifnot() adds that each expression must give TRUE itself: a positive number is not TRUE there, although if () would accept it.

The last two lines of the run show the difference. For a choice that may take several values, several.ok = TRUE returned only "mean" for c("mean", "sdd"), silently dropping the typo, while several.ok = "all" stopped and listed the valid choices.

The dots argument passes extra arguments on, typos too

show_dots(1, 2, digits = 3) reported 2 extra arguments: ......: The dots argument of a function: it collects every argument that matches no other name, so the function can pass them on, as mean(x, ...) does. ...length() counts them and ...names() names them. collects every argument that matches no other name, and the help page ?dots lists the tools to read it: ...length() counts them, ...names() gives their names, "" for an unnamed one, and ..1 is the first. The usual use is to pass them on, as avg <- function(x, ...) mean(x, ...) does. Follow a misspelt argument down that path:

The run shows the tools, the pass-through, the typo and two ways to catch it:

from session import run, version

version()
# R reads dots.R as if each line were typed at the console.
run("""
R --vanilla --quiet -f dots.R
""")

# R version 4.6.1 -- "Happy Hop"
$ R --vanilla --quiet -f dots.R
> # ... collects every argument that matches no other name.
> show_dots <- function(x, ...) {
+   cat("extra arguments:", ...length(), "\n")
+   print(...names())
+   if (...length() > 0) print(..1)
+ }
> show_dots(1, 2, digits = 3)
extra arguments: 2 
[1] ""       "digits"
[1] 2
> # Pass them on to another function.
> avg <- function(x, ...) mean(x, ...)
> avg(c(1, NA, 3), na.rm = TRUE)
[1] 2
> # A misspelt name lands in ... and is ignored without an error.
> avg(c(1, NA, 3), na.mr = TRUE)
[1] NA
> mean(c(1, NA, 3), na.mr = TRUE)
[1] NA
> # chkDots() warns about arguments that a function takes in ... but never uses.
> first_of <- function(x, ...) {
+   chkDots(...)
+   x[1]
+ }
> first_of(c(7, 8), na.mr = TRUE)
[1] 7
Warning message:
In first_of(c(7, 8), na.mr = TRUE) :
 extra argument ‘na.mr’ will be disregarded 
> # Names after ... must be spelt in full: se is not sep.
> paste("a", "b", se = "-")
[1] "a b -"
> paste("a", "b", sep = "-")
[1] "a-b"
> # missing() tells whether a caller gave an argument.
> share_of <- function(x, total) {
+   if (missing(total)) total <- sum(x)
+   round(x / total, 2)
+ }
> share_of(c(2, 3, 5))
[1] 0.2 0.3 0.5
> share_of(c(2, 3, 5), total = 20)
[1] 0.10 0.15 0.25

avg() with na.rm = TRUE returned 2, and with na.mr = TRUE it returned NA: the typo travelled through two ... and was dropped by mean.default(), as it was when mean() was called directly. chkDots(), for a function that takes ... but uses none of it, turned the same typo into a warning, “extra argument ‘na.mr’ will be disregarded”. paste("a", "b", se = "-") shows the other rule of ...: the R Language Definition says partial matching applies only to the formals before ..., so se was not taken as sep and became a third string to paste.

missing(total) is TRUE when the caller gave no total, so share_of() divides by the sum by default and by 20 when told. A default, total = sum(x), would do the same here; missing() is the tool when “not given” must mean something no single default can express.

Arguments are computed lazily, when first used

f(1) returns 4, where function(x, y = x * 2) seems to promise 2. The R Language Definition calls this lazy evaluationlazy evaluation: R's rule that a function's argument is computed only when the body first uses it, not when the function is called, so an argument that is never used is never computed.: arguments are not evaluated until they are needed. Each argument waits as a promisepromise: What R passes in place of an argument until it is used: the argument's expression and the environment to compute it in. The first use computes it, and later uses reuse the value., the expression and the environment to compute it in, and a default is computed inside the function the first time the body uses it. In f(), the body changes x to 2 before it reads y, so x * 2 is 4. Step through it:

The run shows the four consequences:

from session import run, version

version()
# R reads lazy.R as if each line were typed at the console.
run("""
R --vanilla --quiet -f lazy.R
""")

# R version 4.6.1 -- "Happy Hop"
$ R --vanilla --quiet -f lazy.R
> # A default is computed when the argument is first used, inside the function.
> f <- function(x, y = x * 2) {
+   x <- x + 1
+   y
+ }
> f(1)
[1] 4
> # So a default may use a variable the body creates first.
> with_tax <- function(amount, rate = standard_rate) {
+   standard_rate <- 0.18
+   amount * (1 + rate)
+ }
> with_tax(100)
[1] 118
> with_tax(100, rate = 0.05)
[1] 105
> # An argument the body never uses is never computed.
> g <- function(x, unused) x * 10
> g(5, stop("this never runs"))
[1] 50
> # An argument is computed once, then its value is reused.
> noisy <- function() {
+   cat("computing the argument\n")
+   3
+ }
> twice <- function(v) v + v
> twice(noisy())
computing the argument
[1] 6
> # force() computes an argument at once.
> h <- function(x) {
+   force(x)
+   "not reached"
+ }
> try(h(stop("computed by force()")))
Error in force(x) : computed by force()

• A default can use what the body creates. with_tax(100) used standard_rate, a variable the body sets before it reads rate, and returned 118.
• An argument the body never uses is never computed, so g(5, stop("this never runs")) returned 50.
• A promise is computed once. twice(noisy()) read v twice, and “computing the argument” printed once.
• force() computes an argument at once. In h(), the error came from force(x) on the first line, not later.

Laziness rarely matters for arguments a function uses straight away. It matters when a function creates another function that keeps an argument for later, which is the subject of the next lesson, and when an argument’s expression has a side effect, such as printing or reading a file, that the caller expects to happen.

Practise: predict, then check

Work out each result on paper first; the run below is the answer key.

from session import run, version

version()
# R reads practice.R as if each line were typed at the console.
run("""
R --vanilla --quiet -f practice.R
""")

# R version 4.6.1 -- "Happy Hop"
$ R --vanilla --quiet -f practice.R
> add <- function(a, b = a + 1) a + b
> add(2)
[1] 5
> add(2, 10)
[1] 12
> pick <- function(type = c("low", "high")) match.arg(type)
> pick()
[1] "low"
> pick("h")
[1] "high"
> k <- function(x, ...) ...length()
> k(1, 2, 3)
[1] 2

The default b = a + 1 made add(2) 2 + 3, and a given b replaced it; match.arg() returned the first choice when none was given and expanded "h" to "high"; and x took the 1, so ... held two arguments.

Finish with the adaptive questions. They begin with your weakest concept of this lesson, and every choice says why it is right or what it misses:

Interview questions

Warm-up: what does lazy evaluation of arguments mean in R?

When a function is called, R does not compute its arguments first. Each argument is passed as a promise, its expression together with the environment it comes from, and the promise is computed the first time the function’s body uses the argument; after that its value is reused. A default is computed in the same way, but inside the function, so it can refer to other arguments or to variables the body creates before it reads the argument. Three consequences follow: an argument that is never used is never computed, so f(5, stop("x")) can succeed; a default such as y = x * 2 sees x as it is when y is first read; and an argument’s side effects happen at that moment, not at the call. force(x) computes an argument at once.

Key takeaways

• A function returns the value of its last expression; return() leaves early, several results come back as one named vector or list, invisible() returns without printing, and arguments are local copies.
• R matches arguments by exact name, then by the start of a name, then by position, and unsupplied ones take their defaults; a start that fits two names, or a name that fits none, stops the call.
• Check inputs in the first lines with stopifnot(), whose argument names become the messages, and choices with match.arg(), which expands abbreviations and lists the valid choices when one is wrong.
• ... passes any argument on without checking it, so a misspelt name can be swallowed; arguments after ... must be named in full, and missing() tells whether an argument was given.
• Arguments are promises, computed in the function the first time they are used and only once, so a default sees the body’s changes and an unused argument is never computed.