Extract or Replace Parts of a Data Frame

Description

Extract or replace subsets of data frames.

Usage

## S3 method for class 'data.frame'x[i, j, drop = ]## S3 replacement method for class 'data.frame'x[i, j] <- value## S3 method for class 'data.frame'x[[..., exact = TRUE]]## S3 replacement method for class 'data.frame'x[[i, j]] <- value## S3 replacement method for class 'data.frame'x$name <- value

Arguments

Details

Data frames can be indexed in several modes. When[ and[[ are used with a single vector index (x[i] orx[[i]]), they index the data frame as if it were a list. Inthis usage adrop argument is ignored, with a warning.

There is nodata.frame method for$, sox$nameuses the default method which treatsx as a list (with partialmatching of column names if the match is unique, seeExtract). The replacement method (for$) checksvalue for the correct number of rows, and replicates it if necessary.

When[ and[[ are used with two indices (x[i, j]andx[[i, j]]) they act like indexing a matrix:[[ canonly be used to select one element. Note that for each selectedcolumn,xj say, typically (if it is not matrix-like), theresulting column will bexj[i], and hence rely on thecorresponding[ method, see the examples section.

If[ returns a data frame it will have unique (and non-missing)row names, if necessary transforming the row names usingmake.unique. Similarly, if columns are selected columnnames will be transformed to be unique if necessary (e.g., if columnsare selected more than once, or if more than one column of a givenname is selected if the data frame has duplicate column names).

Whendrop = TRUE, this is applied to the subsetting of anymatrices contained in the data frame as well as to the data frame itself.

The replacement methods can be used to add whole column(s) by specifyingnon-existent column(s), in which case the column(s) are added at theright-hand edge of the data frame and numerical indices must becontiguous to existing indices. On the other hand, rows can be addedat any row after the current last row, and the columns will bein-filled with missing values. Missing values in the indices are notallowed for replacement.

For[ the replacement value can be a list: each element of thelist is used to replace (part of) one column, recycling the list asnecessary. If columns specified by number are created, the names(if any) of the corresponding list elements are used to name thecolumns. If the replacement is not selecting rows, list values cancontainNULL elements which will cause the correspondingcolumns to be deleted. (See the Examples.)

Matrix indexing (x[i] with a logical or a 2-column integermatrixi) using[ is not recommended. For extraction,x is first coerced to a matrix. For replacement, logicalmatrix indices must be of the same dimension asx.Replacements are done one column at a time, with multiple typecoercions possibly taking place.

Both[ and[[ extraction methods partially match rownames. By default neither partially match column names, but[[will ifexact = FALSE (and with a warning ifexact = NA). If you want to exact matching on row names usematch, as in the examples.

Value

For[ a data frame, list or a single column (the latter twoonly when dimensions have been dropped). If matrix indexing is used forextraction a vector results. If the result would be a data frame anerror results if undefined columns are selected (as there is no generalconcept of a 'missing' column in a data frame). Otherwise if a singlecolumn is selected and this is undefined the result isNULL.

For[[ a column of the data frame orNULL(extraction with one index)or a length-one vector (extraction with two indices).

For$, a column of the data frame (orNULL).

For[<-,[[<- and$<-, a data frame.

Coercion

The story over when replacement values are coerced is a complicatedone, and one that has changed duringR's development. This sectionis a guide only.

When[ and[[ are used to add or replace a whole column,no coercion takes place butvalue will bereplicated (by calling the generic functionrep) to theright length if an exact number of repeats can be used.

When[ is used with a logical matrix, each value is coerced tothe type of the column into which it is to be placed.

When[ and[[ are used with two indices, thecolumn will be coerced as necessary to accommodate the value.

Note that when the replacement value is an array (including a matrix)it isnot treated as a series of columns (asdata.frame andas.data.frame do) butinserted as a single column.

Warning

The default behaviour when only onerow is left is equivalent tospecifyingdrop = FALSE. To drop from a data frame to a list,drop = TRUE has to be specified explicitly.

Arguments other thandrop andexact should not be named:there is a warning if they are and the behaviour differs from thedescription here.

See Also

subset which is often easier for extraction,data.frame,Extract.

Examples

sw <- swiss[1:5, 1:4]  # select a manageable subsetsw[1:3]      # select columnssw[, 1:3]    # samesw[4:5, 1:3] # select rows and columnssw[1]        # a one-column data framesw[, 1, drop = FALSE]  # the samesw[, 1]      # a (unnamed) vectorsw[[1]]      # the samesw$Fert      # the same (possibly w/ warning, see ?Extract)sw[1,]       # a one-row data framesw[1,, drop = TRUE]  # a listsw["C", ] # partially matchessw[match("C", row.names(sw)), ] # no exact matchtry(sw[, "Ferti"]) # column names must match exactlysw[sw$Fertility > 90,] # logical indexing, see also ?subsetsw[c(1, 1:2), ]        # duplicate row, unique row names are createdsw[sw <= 6] <- 6  # logical matrix indexingsw## adding a columnsw["new1"] <- LETTERS[1:5]   # adds a character columnsw[["new2"]] <- letters[1:5] # dittosw[, "new3"] <- LETTERS[1:5] # dittosw$new4 <- 1:5sapply(sw, class)sw$new  # -> NULL: no unique partial matchsw$new4 <- NULL              # delete the columnswsw[6:8] <- list(letters[10:14], NULL, aa = 1:5)# update col. 6, delete 7, appendsw## matrices in a data frameA <- data.frame(x = 1:3, y = I(matrix(4:9, 3, 2)),                         z = I(matrix(letters[1:9], 3, 3)))A[1:3, "y"] # a matrixA[1:3, "z"] # a matrixA[, "y"]    # a matrixstopifnot(identical(colnames(A), c("x", "y", "z")), ncol(A) == 3L,          identical(A[,"y"], A[1:3, "y"]),          inherits (A[,"y"], "AsIs"))## keeping special attributes: use a class with a## "as.data.frame" and "[" method;## "avector" := vector that keeps attributes.   Could provide a constructor##  avector <- function(x) { class(x) <- c("avector", class(x)); x }as.data.frame.avector <- as.data.frame.vector`[.avector` <- function(x,i,...) {  r <- NextMethod("[")  mostattributes(r) <- attributes(x)  r}d <- data.frame(i = 0:7, f = gl(2,4),                u = structure(11:18, unit = "kg", class = "avector"))str(d[2:4, -1]) # 'u' keeps its "unit"