Extract {base} | R Documentation

## Extract or Replace Parts of an Object

### Description

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

### Usage

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

### Arguments

`x` | object from which to extract element(s) or in which to replace element(s).
`i, j, ..., name` | indices specifying elements to extract or replace. `i, j` are `numeric` or `character` vectors or empty (missing) or `NULL` whereas `name` must be a character string or an (unquoted or backtick quoted) name. Numeric values are coerced to integer as by `as.integer`. For extraction with `[[` and `$` character strings are normally (see under Environments) partially matched to the `names` of the object if exact matching does not succeed. 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. `i, j, ...` can also be negative integers, indicating elements/slices to leave out of the selection. When indexing arrays by `[` a single argument `i` can be a 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`. An index value of `NULL` is treated as if it were `integer(0)`.
`drop` | For matrices and arrays. If `TRUE` the result is coerced to the lowest possible dimension (see the examples). This only works for extracting elements, not for the replacement.

### Details

These operators are generic. You can write methods to handle indexing of specific classes of objects, see InternalMethods as well as `[.data.frame` and `[.factor`. The descriptions here apply only to the default methods. Note that separate methods are required for the replacement functions `[<-`, `[[<-` and `$<-` for use when indexing occurs on the assignment side of an expression.

The most important distinction between `[`, `[[` and `$` is that the `[` can select more than one element whereas the other two select a single element.

The default methods work somewhat differently for atomic vectors, matrices/arrays and for recursive (list-like, see `is.recursive`) objects. `$` returns `NULL` except for recursive objects, and is only discussed in the section below on recursive objects.

Indexing can occur on the right-hand-side of an expression for extraction, or on the left-hand-side for replacement. When an index expression 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. In this case no partial matching of indices is done. The left-hand-side is coerced as needed to accept the values.

### Atomic vectors

The usual form of indexing is `"["`. `"[["` can be used to select a single element, but `"["` can also do so (but will not partially match a character index).

The index object `i` can be numeric, logical, character or empty. 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)]`).

An empty index selects all values: this is most often used to replace all the entries but keep the `attributes`.

### Matrices and arrays

Matrices and arrays are vectors with a dimension attribute and so all the vector forms of indexing can be used with a single index. The result will be an unnamed vector unless `x` is one-dimensional when it will be a one-dimensional array.

The most common form of indexing a k-dimensional array is to specify k indices to `[`. As for vector indexing, the indices can be numeric, logical, character, empty or even factor. An empty index (a comma separated blank) indicates that all entries in that dimension are selected. The argument `drop` applies to this form of indexing.

A third form of indexing is via a numeric matrix with the one column for each dimension: each row of the index matrix then selects a single element of the array, and the result is a vector. Negative indices are not allowed in the index matrix. `NA` and zero values are allowed: rows of an index matrix containing a zero are ignored, whereas rows containing an `NA` produce an `NA` in the result.

A vector obtained by matrix indexing will be unnamed unless `x` is one-dimensional when the row names (if any) will be indexed to provide names for the result.

### Recursive (list-like) objects

Indexing by `[` is similar to atomic vectors and selects a list of the specified element(s).

Both `[[` and `$` select a single element of the list. The main difference is that `$` does not allow computed indices, whereas `[[` does. `x$name` is equivalent to `x[["name"]]`.

`[` and `[[` are sometimes applied to other recursive objects such as calls and expressions. Pairlists are coerced to lists for extraction by `[`, but all three operators can be used for replacement.

`[[` 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.

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

### Environments

Both `$` and `[[` can be applied to environments. Only character arguments are allowed and no partial matching is done. The semantics of these operations are those 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. 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 extracting, a numerical, logical or character `NA` index 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. (It returns `00` for a raw result.]

When replacing (that is using indexing 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).

### Argument matching

Note that these operations do not match their index arguments in the standard way: argument names are ignored and positional matching only is used. So `m[j=2,i=1]` is equivalent to `m[2,1]` and not to `m[1,2]`.

This may not be true for methods defined for them; for example it is not true for the `data.frame` methods described in `[.data.frame`.

To avoid confusion, do not name index arguments (but `drop` must be named).

### Note

S uses partial matching when extracting by `[` (Becker et al p. 358) whereas R does not.

The documented behaviour of S is that an `NA` replacement index ‘goes nowhere’ but uses up an element of `value` (Becker et al p. 359). However, that is not the current behaviour of S-PLUS.

### References

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

### See Also

`list`, `array`, `matrix`.

`[.data.frame` and `[.factor` for the behaviour when applied to data.frame and factors.

`Syntax` for operator precedence, and the R Language reference manual about indexing details.

### 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.3.1 Index]