Default Function Arguments

As we alluded to in the Functions Section, the Usage section of an R documentation file provides two very important pieces of information about a function’s arguments.

  1. The order in which the arguments are specified in the function definition.
  2. The default values of arguments for which defaults are defined.

Argument Ordering

When you call an R function, you do not have to explicitly write out the argument names, if you supply the argument values in the order that the arguments are specified in the function definition. That’s a mouthful, so let’s look at the matrix() function for a concrete example.

matrix R Documentation

Matrices

Description

matrix creates a matrix from the given set of values.

as.matrix attempts to turn its argument into a matrix.

is.matrix tests if its argument is a (strict) matrix.

Usage

matrix(data = NA, nrow = 1, ncol = 1, byrow = FALSE,
       dimnames = NULL)

as.matrix(x, ...)
## S3 method for class 'data.frame'
as.matrix(x, rownames.force = NA, ...)

is.matrix(x)

Arguments

The usage section of matrix()’s help file tells use that the function takes five arguments:

  1. data
  2. nrow
  3. ncol
  4. byrow
  5. dimnames

Furthermore, we see that these five arguments are specified in the order shown above.

If we explicitly write out the names for all the arguments in our function call, we can specify the argument values in any order. Hence, the following three lines will produce equivalent results, for example.

matrix(data = 1:6, nrow = 3, ncol = 2, byrow = FALSE, dimnames = NULL)
1 4
2 5
3 6 
matrix(nrow = 3, ncol = 2, data = 1:6,byrow = FALSE, dimnames = NULL)
1 4
2 5
3 6 
matrix(byrow = FALSE, data = 1:6, nrow = 3, ncol = 2, dimnames = NULL)
1 4
2 5
3 6

If we provide the argument values in the order they are specified in the function definition, we do not need to write out the argument names. So, the following function call will produce the same result as the three above.

matrix(1:6, 3, 2, FALSE, NULL)
1 4
2 5
3 6

We can also mix these two approaches, but we have to provide all unnamed argument values first, and provide them in the correct order. The following function calls will also produce the same results as above.

matrix(1:6, 3, 2, FALSE, dimnames = NULL)
1 4
2 5
3 6 
matrix(1:6, 3, 2, byrow = FALSE, dimnames = NULL)
1 4
2 5
3 6 
matrix(1:6, 3, dimnames = NULL, byrow = FALSE, ncol = 2)
1 4
2 5
3 6

We cannot, however, switch the order of any unnamed argument values. The following code will not reproduce the matrix created above.

## Flip the 'nrow' and 'ncol' arguments
matrix(1:6, 2, 3, FALSE, dimnames = NULL)
1 3 5
2 4 6

Default Values

When the Usage section shows a value assigned to a function argument, the value shown is the default value for that function argument. For the matrix() function, all five arguments have default values.

  1. data = NA
  2. nrow = 1
  3. ncol = 1
  4. byrow = FALSE
  5. dimnames = NULL

When a function argument has a defined default value, we do not need to specify a value for that argument in our function call: if we don’t provide an argument value, the argument takes the default value shown in the documentation.

So, we could technically call the matrix() function without specifying any arguments.

matrix()
NA

Though, the results are rather boring. Since our function call is entirely parameterized by the default arguments, we get a \(1 \times 1\) matrix containing a single missing datum.

In practice, we will almost always specify some argument values, but we will frequently accept some of the default values, as well. The following is a typical example of calling the matrix() function.

matrix(1:12, nrow = 4)
1 5 9
2 6 10
3 7 11
4 8 12

In the above function call, I’ve employed two common shortcuts:

  1. I didn’t name the first argument.
  2. I only specified values for the two arguments that I wanted to adjust.
Back to top