Extract or Replace Parts of an Object - Generic Operators

DESCRIPTION:

Extract or replace parts of a vector, list, or array. These functions (except $ and $<-) are S Version 3 generic operators; see the Methods help file 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 "anova" , "data.frame" , "factor" , "model.matrix" , "smooth" , and "tree" .

USAGE:

x[i]  
x[i, j, ...]  
x[i, j, ..., drop=T]  
x[<args>] <- value 
x[[i]]
x[[i, j, ...]]  
x[[<args>]] <- value  
x$name

REQUIRED ARGUMENTS:

x
any S-PLUS object.
i, j, ...
subscript expressions used to identify the elements to extract or replace. The expressions may 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).
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.

OPTIONAL ARGUMENTS:

drop
a logical flag. 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=F] produces a 5 by 1 matrix. Setting drop=FALSE is most useful in functions where consistency is important; the expression M[,j,drop=F] always produces a two-dimensional matrix regardless of the length of j. The behavior may differ for other objects. For example, for a data frame, when drop is not supplied, subscripting a single row returns a data frame (like drop=F) but subscripting a single column returns a vector. Explicitly setting drop=T and subscripting one row returns a list. Explicitly setting drop=F and subscripting one column returns a data frame. The class of the result may differ from the class of the original object, particularly when drop=T.
value
the replacement value for the relevent piece of the object.

VALUE:

The extraction functions [, [[ , and $ return the designated elements or properties of the object x .

SIDE EFFECTS:

The replacement functions [<- and [[<- replace the designated elements or properties of the object x.

DETAILS:

For a vector x, if i is empty, all of x is extracted or replaced without affecting the attributes of x. S-PLUS drops all zero indices before suscripting.

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 ( "" for characters) 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 NULL 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.

BACKGROUND:

The subscript operator [ is designed to subscript vectors, matrices, and arrays using integers, logical values, or character values as subscripts. The list subscript operator [[ is designed to subscript lists and the component operator is designed to subscript list-like objects with named components, such as data frames. Any S-PLUS expression that evaluates to an appropriate subscript value can be included in the square brackets. For detailed information on subscripting data frames, see the [.data.frame help file. For additional background information and examples beyond what is given here, see the chapter "Writing Functions in S-PLUS" in the S-PLUS Programmer's Guide.

A vector subscript corresponds to an element's position or index in the vector. For example, the sixth element in a vector x has a subscript (or index) of 6. You can subscript a data vector by providing a set of indices that correspond to the elements you wish to keep. If y is a vector of indices, x[y] returns the elements in x that correspond to the indices.

Subscripting Vectors with Integers

If you supply a set of positive integers to subscript a vector, S-PLUS interprets the integers 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) , S-PLUS returns NA to indicate a missing value. If you supply a set of negative integers to subscript a vector, S-PLUS interprets them as the indices of the elements you want to exclude from the result. You cannot combine positive and negative integers to subscript a vector.

Subscripting Vectors with Logical Values

If you supply a set of logical values to subscript a vector, S-PLUS interprets the TRUE values 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 S-PLUS recycles the values in a short logical vector so that its length matches a longer vector. No values are returned for indices greater than length(x) .

Subscripting 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.

Subscripting 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 S-PLUS does not recognize it as matrix.

S-PLUS 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.

Subscripting 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:

, , , , , , , , , .

EXAMPLES:

# Return x values not equal to 999.999.
x[x!=999.999]

# Sort x by increasing values of y.
x[order(y)]

# Return all but the first and third elements in x. 
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[2,3] <- 8.4
# Change missing values to 0.
x[which.na(x)] <- 0

# Print the row for Alabama.
state.x77["Alabama", ]

# Create an array with dimension 5x3x2.
A <- array(1:30, c(5, 3, 2) )
# Return A. 
A[]
# Return a scalar, 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)]