Subscript
Extract or Replace Parts of an Object

Description

Extracts or replaces parts of an object. Can apply to a vector, a list, an array, a factor, or a data frame.
These functions are generic operators. (See help for Methods for details.) Method functions can be written to handle specific S Version 3 classes of data. Classes that already have methods for these functions include:

Usage

x[i] 
x[i, j, ...]  
x[i, j, ..., drop = TRUE]
x[[..., exact = TRUE]] 
x[i, drop=FALSE] 
x[i, j, drop=<<see below>>]
x[<args>] <- value 
x[[i]] 
x[[i, j, ..., exact = TRUE]]  
x[[<args>]] <- value  
x[i, j] <- value
x[[i, j]] <- value
x[i] <- value 

x$name x$name <- value

Arguments

x an object. See Details for more information.
i, j, ... subscript expressions used to identify the elements to extract or replace. The expressions can be empty, which corresponds to all possible subscripts and therefore extracts/replaces the entire object (or the entire dimension of the object). The expressions may also be logical, numeric, or character. Numeric subscripts should be integers, such as the output from : (the sequence operator).
  • If x is a data frame:
    • If a single argument is given that is not a matrix or list (x[j] or x[[j]]), then x is treated as a frame or list and the index j is assumed to index the variables of the data frame.
    • If the subscripting appears to be a matrix (that is, x[i,j], x[i,], or x[,j], then i and j apply to the rows (observations) and columns (variables), respectively. The methods treat x as a matrix.
  • If x is a factor, then i is the index for extraction or replacement (either a numeric or logical). For the [[ form, the index must be a single integer value.
name a name or quoted string identifying the component to extract or replace. This is used when subscripting objects such as lists and data frames.
drop a logical flag. The class of the result might differ from the class of the original object, particularly when drop=TRUE.
  • For data frame, when drop is not supplied, subscripting a single row returns a data frame (like drop=FALSE) but subscripting a single column returns a vector. Explicitly setting drop=TRUE and subscripting one row returns a list. Explicitly setting drop=FALSE and subscripting one column returns a data frame.
  • For a factor, if TRUE, the unused levels of the factor are dropped. The default is FALSE.
  • For an ordinary matrix or array, if drop=TRUE, dimensions of length 0 or 1 are dropped from the return object. For example, assume you have a 5 by 10 matrix M. The expression M[,1] produces a vector of length 5 and M[,1,drop=FALSE] produces a 5 by 1 matrix. Setting drop=FALSE is most useful in functions where consistency is important; the expression M[,j,drop=FALSE] always produces a two-dimensional matrix regardless of the length of j.
exact a logical flag. If TRUE (the default), character indices match names or dimnames of the object. When exact=FALSE, partial matching is used.
ignore.row.names a logical flag intended to be used when extracting the same row more than once from a data.frame to make a new data.frame (for example, when doing resampling). A problem arises because the row names of a data.frame must be unique. If FALSE (the default), the row names for the ouput data.frame are based on those of the input, with digits appended to them as needed to make them unique (using the make.unique function). If TRUE, the row names for the output are the first nrow(output) whole numbers, converted to character strings; they are not based on the input row names. Using ignore.row.names=TRUE can save time when doing resampling on large data.frames.
value the replacement value for the relevant piece of the object.
  • For a data frame, unless value is a constant, we recommend that this argument be a data frame if you want to replace data in more than one variable. Also, the replacement value can be an atomic vector or a list. For double subscripts, value should not be a list or data frame.
  • For a factor, value can, but need not, be a factor. In any case, the values are interpreted in terms of the level set of the factor. Values not in the level set will generate NAs.

Details

All zero indices are dropped before subscripting.
If x is a data frame, the following operators apply: If x is a factor, the following operators apply: If x is a vector, list, or array, the following operators apply: If x is a factor, the [[ form selects a single element from the factor object, and the result is a factor object containing a single element from x with the same levels attribute as x.
If x is a vector, and if i is empty, all of x is extracted or replaced without affecting the attributes of x.
For extraction, the value of x[i] has the same mode as x and the same length as the number of indices. The elements of x[i] are the elements of x corresponding to the indices, except if the indices are greater than length(x) or are NA. In either exception, the returned elements are missing; that is, they are NA for an atomic mode and NULL for a non-atomic mode.
All attributes of x are discarded in the subset except the names attribute. The names attribute of x[i] is equal to names(x)[i].
The expression x\$name returns the name component of x. It is equivalent to x[["name"]] if x is recursive and an error otherwise. Partial matching is performed on the names of x for extractions. Thus to extract a component of a list, you only need to give enough of the name to make it unique. Replacement of the name component may coerce an object to a list.
For replacement, the length of x is set to the largest value in the indices, if that is bigger than the current length of x. If x and value do not have the same mode, then one of them is coerced to the common mode that can represent both without loss of information. This may mean that replacing elements of an object will change its mode. Arguments are passed to the subscript operators by position, not by name. The exception to this rule is drop. You must pass this argument by name. That is, x[2, , drop = TRUE] successfully extracts the second row of x and results in list. x[2, , TRUE] results in an error.
The drop argument is ignored if only a single subscript is given. For example, x[j, drop=TRUE] returns a data frame, not a vector.
When you replace one or more columns of a data frame, the engine checks that the new values have the right number of rows and, if possible, ensures that the assignment leaves the data frame in a valid state. With x[i,j] <- value, the characteristics of variables (that is, class, mode, dimension, attributes) in the result depend on the characteristics of the variables in both x and value. For the following, they depend solely on value: For data frames containing matrices, these operators handle column subscripts as if each matrix were a single column. For example, if Y has 3 elements where the third is a matrix with 5 columns, Y[,3] is dropped to a matrix with 5 columns and Y[,4] is undefined. With x[i,j] <- value, if x contains matrices, then both of the following are true:
There is a special case for x[j], where j is a matrix, and is one of the following: In either of these situations, all columns of x are coerced to a common data type and matrix variables are converted to multiple columns before subscripting with the matrix j.
Matrix subscripts are not allowed for the replacement operation x[j] <- value.
Attributes of x other than row.names and dup.row.names are lost if columns are subscripted (for example, x[j], x[,j], x[i,j]).
Value
Side Effects
The replacement functions [<- and [[<- replace the designated elements or properties of the object x.
Background
Vectors with Integers
If you supply a set of positive integers to subscript a vector, they are interpreted as the indices of the elements you want to keep. The indices do not need to be unique nor do they need to be given in increasing order. If the requested index for a vector x is greater than length(x), NA is returned to indicate a missing value.

If you supply a set of negative integers to subscript a vector, they are interpreted as the indices of the elements you want to exclude from the result. You cannot combine positive and negative integers to subscript a vector.

Vectors with Logical Values
If you supply a set of logical values to subscript a vector, the TRUE values are interpreted as the indices of the elements you want to keep. Logical index vectors are generally the same length as the vectors to be subscripted. However, this is not a strict requirement, as the values in a short logical vector are recycled so that its length matches a longer vector. No values are returned for indices greater than length(x).
Vectors with Character Values
When you supply a set of character values to subscript a vector, the values must be from the vector's names attribute. Thus, this subscripting technique requires the vector to have a non-null names attribute. You can use the names<- replacement function to assign names if necessary.
Matrices and Arrays
Subscripting data sets that are matrices or arrays is very similar to subscripting vectors. In fact, you can subscript them exactly like vectors if you keep in mind that arrays are stored in column-major order. You can think of the data values in an array as being stored in one long vector that has a dim attribute to specify the array's shape. Column-major order states that the data values fill the array so that the first index changes the fastest and the last index changes the slowest. For matrices, this means the data values are filled in column-by-column. When a matrix is subscripted in this way, the element returned is a single number without dimension attributes, so that is is no longer recognized as a matrix.

S also lets you use the structure of arrays to your advantage by allowing you to specify one subscript for each dimension. Since matrices have two dimensions, you can specify two subscripts inside the square brackets. The matrix subscripts correspond to the row and column indices, respectively.

As with vectors, array subscripts can be positive integers, negative integers, logical vectors, or character vectors if appropriate. To subscript matrices and arrays by supplying character subscripts, the supplied values must be from the array's dimnames attribute. If the subscript for a given dimension is omitted, all subscripts are assumed.

Arrays with Matrices
You can extract irregular subsets of arrays by supplying a subscript matrix representing the positions of the individual elements you wish to keep. For example, suppose M is a 3 by 4 matrix and we want to extract two elements from it: the element in row 1 and column 2, and the element in row 3 and column 3. We can do this directly with the command c(M[1,2], M[3,3]). More generally, we can do this by subscripting with a matrix:
    subscr.mat <- matrix(c(1,2,3,3), ncol=2, byrow=T);
    M[subscr.mat]
Warnings
Partial matching of abbreviated dimension names sometimes gives undesired results. To avoid partial matching, you can use the match function. For example, to prevent x["1"] from inadvertently returning x["10"] when there is no "1" in the names attribute, use x[match("1", names(x))].
To replace a component of a list, you must give the entire name of the component. If you abbreviate the name, a new component with the abbreviated name is added.
Subscripting coerces non-integer numeric subscripts to integers using as.integer. Because as.integer creates integers by truncating the numeric representation, this coercion can lead to unexpected results.
See Also
Subscript.data.frame, Methods, length, names, dim, dimnames, attr, attributes, Comparison, Syntax.
Examples
# Return x values not equal to 5.
x <- 1:12
x[x != 5]

# Sort x by increasing values of y. x <- 101:112 y <- 12:1 x[order(y)]

# Return all but the first and third elements in x. x <- 1:12 x[-c(1, 3)]

# Return list(2:3). list(1:10, 2:3)[2] # Return the vector 2:3. list(1:10, 2:3)[[2]]

# Change the value of a matrix element. x <- matrix(1:12, ncol=4) x[1,1] <- NA x[2,3] <- 8.4 # Change missing values to 0. x[is.na(x)] <- 0

# Create an array with dimension 5x3x2. A <- array(1:30, c(5, 3, 2)) # Return A. A[] # Return a numeric value, the first data value of A. A[1, 1, 1] A[1] # Return a (5,2,2) array. A[, 1:2, ] # Return the vector 4:30. A[A>3]

# Create a list of the numbers 1:4. al <- as.list(1:4) # Remove third component. # The length of al is reduced by 1. al[[3]] <- NULL # Replace 2nd and 3rd component by NULL. al[2:3] <- list(NULL)

# Use a matrix as a subscript. x <- matrix(1:12, 4) # Extract x[4,1], x[3,2], x[2,3]. x[cbind(4:2, 1:3)]

Package base version 6.0.0-69
Package Index