R: Extract or Replace Parts of an Object

Extract {base}

R Documentation

Extract or Replace Parts of an Object

Description

Operators acting on vectors, arrays and lists to extract or replace subsets.

Usage

x[i]
x[i, j, ... , drop = TRUE]
x[[i]]
x[[i, j, ...]]
x$name

Arguments

x

object from which to extract elements or in which to replace elements.

i, j, ..., name

elements to extract or replace. i, j are numeric or character or empty whereas name must be character or an (unquoted) name. Numeric values are coerced to integer as by as.integer.

For [-indexing only: i, j, ... can be logical vectors, indicating elements/slices to select. Such vectors are recycled if necessary to match the corresponding extent. When indexing arrays, i can be a (single) matrix with as many columns as there are dimensions of x; the result is then a vector with elements corresponding to the sets of indices in each row of i.

i, j, ... can also be negative integers, indicating elements/slices to leave out of the selection.

drop

For matrices, and arrays. If TRUE the result is coerced to the lowest possible dimension (see examples below). This only works for extracting elements, not for the replacement forms.

Details

These operators are generic. You can write methods to handle subsetting of specific classes of objects, see InternalMethods as well as [.data.frame and [.factor. The descriptions here apply only to the default methods.

The most important distinction between [, [[ and $ is that the [ can select more than one element whereas the other two select a single element. $ does not allow computed indices, whereas [[ does. x$name is equivalent to x[["name"]] if x is recursive (see is.recursive) and NULL otherwise.

The [[ operator requires all relevant subscripts to be supplied. With the [ operator an empty index (a comma separated blank) indicates that all entries in that dimension are selected.

If one of these expressions appears on the left side of an assignment then that part of x is set to the value of the right hand side of the assignment.

Indexing by factors is allowed and is equivalent to indexing by the numeric codes (see factor) and not by the character values which are printed (for which use [as.character(i)]).

When operating on a list, the [[ operator gives the specified element of the list while the [ operator returns a list with the specified element(s) in it.

As from R 1.7.0 [[ can be applied recursively to lists, so that if the single index i is a vector of length p, alist[[i]] is equivalent to alist[[i1]]...[[ip]] providing all but the final indexing results in a list.

The operators $ and $<- do not evaluate their second argument. It is translated to a string and that string is used to locate the correct component of the first argument.

When $<- is applied to a NULL x, it coerces x to list(). This is what happens with [[<- is y is of length greater than one: if y has length 1 or 0, x is coerced to a zero-length vector of the type of value,

As from R 1.9.0 both $ and [[ can be applied to environments. Only character arguments are allowed and no partial matching is done (this is in contrast to the behavior for lists). The semantics of these operations is basically that of get(i, env=x, inherits=FALSE). If no match is found then NULL is returned. The assignment versions, $<- and [[<-, can also be used. Again, only character arguments are allowed and no partial matching is done. The semantics in this case are those of assign(i, value, env=x, inherits=FALSE). Such an assignment will either create a new binding or change the existing binding in x.

NAs in indexing

When subscripting, a numerical, logical or character NA picks an unknown element and so returns NA in the corresponding element of a logical, integer, numeric, complex or character result, and NULL for a list.

When replacing (that is using subscripting on the lhs of an assignment) NA does not select any element to be replaced. As there is ambiguity as to whether an element of the rhs should be used or not (and R handled this inconsistently prior to R 2.0.0), this is only allowed if the rhs value is of length one (so the two interpretations would have the same outcome).

References

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

Examples

x <- 1:12; m <- matrix(1:6,nr=2); li <- list(pi=pi, e = exp(1))
x[10]                 # the tenth element of x
x <- x[-1]	      # delete the 1st element of x
m[1,]                 # the first row of matrix m
m[1, , drop = FALSE]  # is a 1-row matrix
m[,c(TRUE,FALSE,TRUE)]# logical indexing
m[cbind(c(1,2,1),3:1)]# matrix index
m <- m[,-1]	      # delete the first column of m
li[[1]]               # the first element of list li
y <- list(1,2,a=4,5)
y[c(3,4)]             # a list containing elements 3 and 4 of y
y$a                   # the element of y named a

## non-integer indices are truncated:
(i <- 3.999999999) # "4" is printed
(1:5)[i]  # 3

## recursive indexing into lists
z <- list( a=list( b=9, c='hello'), d=1:5)
unlist(z)
z[[c(1, 2)]]
z[[c(1, 2, 1)]]  # both "hello"
z[[c("a", "b")]] <- "new"
unlist(z)

## check $ and [[ for environments
e1 <- new.env()
e1$a <- 10
e1[["a"]]
e1[["b"]] <- 20
e1$b
ls(e1)

[Package base version 2.0.0 ]