Accessing Help Files

The simplest way to access a function’s help file is to prepend the function name (without parentheses) with the ? character. The following code will pull up the documentation for the lm() function.

Reading

R4DS 8: Getting Help

?lm

You can achieve the same effect by providing the function name to the help() function.

help(lm)
help("lm")

A function’s help file comes from the package that provides the function. So, you typically cannot access the help file for a function until you’ve loaded the package that provides that function.

For example, the following code will produce an error because we’re trying to access the documentation for arrange(), but we haven’t yet loaded the dplyr package that provides the arrange() function.

?arrange
No documentation for 'arrange' in specified packages and libraries:
you could try '??arrange'

We can still access the help files for functions provided by an unloaded package, though. We just have to tell R which package provides the function (and, hence, where to look for the help file). To do so, either use the namespace resolution operator, ::, or provide a value for the package argument in the help() function.

The following two code chunks should run without errors, because we’ve told R to search for the arrange() documentation in the dplyr package

Practice

Access the help file for the vector() function.

  1. How many arguments does the vector() function take?
  2. What is the default value of the mode argument?

The vector() function is provided by the base package, which is loaded every time you start R. So, you should be able to access the help file without loading any additional packages.

According to the Usage section of vector()’s documentation,

  1. The vector() function takes 2 arguments: mode and length.
  2. The default argument for mode is “logical”.
?vector
vector R Documentation

Vectors - Creation, Coercion, etc

Description

A vector in R is either an atomic vector i.e., one of the atomic types, see ‘Details’, or of type (typeof) or mode list or expression.

vector produces a ‘simple’ vector of the given length and mode, where a ‘simple’ vector has no attribute, i.e., fulfills is.null(attributes(.)).

as.vector, a generic, attempts to coerce its argument into a vector of mode mode (the default is to coerce to whichever vector mode is most convenient): if the result is atomic (is.atomic), all attributes are removed. For mode="any", see ‘Details’.

is.vector(x) returns TRUE if x is a vector of the specified mode having no attributes other than names. For mode="any", see ‘Details’.

Usage

vector(mode = "logical", length = 0)
as.vector(x, mode = "any")
is.vector(x, mode = "any")

Arguments

Details

The atomic modes are "logical", "integer", "numeric" (synonym "double"), "complex", "character" and "raw".

If mode = "any", is.vector may return TRUE for the atomic modes, list and expression. For any mode, it will return FALSE if x has any attributes except names. (This is incompatible with S.) On the other hand, as.vector removes all attributes including names for results of atomic mode.

For mode = "any", and atomic vectors x, as.vector(x) strips all attributes (including names), returning a simple atomic vector.
However, when x is of type "list" or "expression", as.vector(x) currently returns the argument x unchanged, unless there is an as.vector method for class(x).

Note that factors are not vectors; is.vector returns FALSE and as.vector converts a factor to a character vector for mode = "any".

Value

For vector, a vector of the given length and mode. Logical vector elements are initialized to FALSE, numeric vector elements to 0, character vector elements to "", raw vector elements to nul bytes and list/expression elements to NULL.

For as.vector, a vector (atomic or of type list or expression). All attributes are removed from the result if it is of an atomic mode, but not in general for a list or expression result. The default method handles 24 input types and 12 values of type: the details of most coercions are undocumented and subject to change.

For is.vector, TRUE or FALSE. is.vector(x, mode = "numeric") can be true for vectors of types "integer" or "double" whereas is.vector(x, mode = "double") can only be true for those of type "double".

Methods for as.vector()

Writers of methods for as.vector need to take care to follow the conventions of the default method. In particular

  • Argument mode can be "any", any of the atomic modes, "list", "expression", "symbol", "pairlist" or one of the aliases "double" and "name".

  • The return value should be of the appropriate mode. For mode = "any" this means an atomic vector or list or expression.

  • Attributes should be treated appropriately: in particular when the result is an atomic vector there should be no attributes, not even names.

  • is.vector(as.vector(x, m), m) should be true for any mode m, including the default "any".

    Currently this is not fulfilled in R when m == "any" and x is of type list or expression with attributes in addition to names — typically the case for (S3 or S4) objects (see is.object) which are lists internally.

Note

as.vector and is.vector are quite distinct from the meaning of the formal class "vector" in the methods package, and hence as(x, "vector") and is(x, "vector").

Note that as.vector(x) is not necessarily a null operation if is.vector(x) is true: any names will be removed from an atomic vector.

Non-vector modes "symbol" (synonym "name") and "pairlist" are accepted but have long been undocumented: they are used to implement as.name and as.pairlist, and those functions should preferably be used directly. None of the description here applies to those modes: see the help for the preferred forms.

References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

See Also

c, is.numeric, is.list, etc.

Examples

df <- data.frame(x = 1:3, y = 5:7)
## Error:
try(as.vector(data.frame(x = 1:3, y = 5:7), mode = "numeric"))

x <- c(a = 1, b = 2)
is.vector(x)
as.vector(x)
all.equal(x, as.vector(x)) ## FALSE


###-- All the following are TRUE:
is.list(df)
! is.vector(df)
! is.vector(df, mode = "list")

is.vector(list(), mode = "list")
Back to top