Calling Functions and Reading Help

Anatomy of a function call

A function call is a name followed by parentheses, with the inputs, called arguments, separated by commas. round(3.14159, 2) passes two arguments. Every argument has a name inside the function, and R matches what you pass to those names in one of two ways: by position, in the order the function lists them, or by name, when you write name = value. Named arguments can appear in any order.

round(3.14159, 2)
#> [1] 3.14
round(3.14159, digits = 2)
#> [1] 3.14
round(digits = 2, x = 3.14159)
#> [1] 3.14
seq(1, 10, 2)
#> [1] 1 3 5 7 9
seq(from = 1, to = 10, by = 2)
#> [1] 1 3 5 7 9
seq(1, 10, length.out = 4)
#> [1]  1  4  7 10

The convention most R users follow is to pass the main input, the data, by position and everything else by name. seq(1, 10, 2) works, but seq(1, 10, by = 2) tells the reader what the 2 means, and it will still work if the function's argument order ever changes. The last call shows why names matter: length.out is not the third argument, so it can only be reached by name.

Seeing which arguments exist

args() prints a function's argument list together with its default values. An argument with a default is optional; one without must be supplied.

args(round)
#> function (x, digits = 0, ...) 
#> NULL
args(mean)
#> function (x, ...) 
#> NULL

round takes x and an optional digits that defaults to 0, which is why round(2.7) gives a whole number. The three dots mean the function accepts further named arguments and passes them on; for mean, that is where na.rm lives, and the help page lists it.

The na.rm argument

NA is R's marker for a missing value. Most summary functions refuse to guess: if any element is missing, the result is NA. To compute on the values that are present you must say so explicitly with na.rm = TRUE. This design is deliberate. A silent average over an incomplete set of readings would hide a data problem; an NA forces you to notice it and decide.

x <- c(3.2, 4.8, NA, 5.1)
mean(x)
#> [1] NA
mean(x, na.rm = TRUE)
#> [1] 4.366667
max(x, na.rm = TRUE)
#> [1] 5.1

Reading a help page

Type ?mean or help("mean") to open the documentation. Every help page has the same sections. Usage shows the call with its defaults. Arguments explains each one; this is where you will find that na.rm is a logical value meaning remove missing values before computing. Value tells you what comes back. Examples at the bottom are runnable, and example(mean) runs them for you. If you do not know the function's name, ??"standard deviation" searches all installed help pages for the phrase.

A few text functions

Functions are not only for numbers. These four come up constantly when labelling data.

nchar("statistics")
#> [1] 10
paste("Hello", "R")
#> [1] "Hello R"
paste0("id_", 1:3)
#> [1] "id_1" "id_2" "id_3"
toupper("r basics")
#> [1] "R BASICS"

paste() joins with a space, paste0() with nothing, and both are vectorised: one prefix against a vector of numbers yields a vector of labels through recycling.