Extract.data.list: Extract or replace parts of a data list

In stevencarlislewalker/multitable: Simultaneous Manipulation of Multiple Arrays of Data

Description

Operators acting on data list objects to extract or replace parts.

Usage

## S3 method for class 'data.list'
x[..., drop = TRUE, vextract = TRUE]
## S3 replacement method for class 'data.list'
x$i <- value
## S3 replacement method for class 'data.list'
x[[i, match.dimids, shape, drop = TRUE]] <- value

Arguments

x	A data.list object.
i	Subscript or variable name.
value	Replacement value.
...	Vectors to subscript the data list.
drop	If TRUE, single dimension data lists that result from subscripting are coerced to data frames (i.e. their replication dimensions are 'dropped').
vextract	If TRUE, variable extraction is done whenever only a single argument is passed to .... If FALSE, variable extraction is not allowed. Sometimes it is useful to set vextract = FALSE whenever single-dimension data lists are expecting dimension-wise subscripting.
match.dimids	A character vector supplying the dimids (ids of the replication dimensions) that value is replicated along, iff i is a variable name that does not yet exist in the data list, x. Ignored if shape is provided.
shape	A single character string giving the name of an already existing variable in x, whose dimensions will be used for the new variable, i.

Details

The [.data.list method of extraction can be used in two main ways: (1) to extract parts of the replication dimensions of all of the variables in the data list (modeled after the method for arrays and matrices, Extract), and (2) to extract some of the variables while keeping their replication dimensions unaltered (modeled after the method for lists, Extract).

In array-like extraction, each replication dimension of the data list is subscripted as an element in a comma-separated list passed to .... In intuitive terms, all variables in the data list will be subsequently subscripted along the appropriate replication dimensions; in technical terms, there is a two-step process for each variable where (1) the subscripts for the dimensions that this variable is not replicated along are deleted and then (2) the remaining subscripts are used to index that variable. This kind of subscripting is one of the major advantages of the data list concept; because the vectors, matrices, and arrays in a data list are related via dimension sharing, they can all be subscripted in a single line. To emphasize an important point, the main difference between subscripting arrays and array-like subscripting of data lists is that the latter does not allow any dimensions to be either reduced to length zero or be dropped. In general, the differences between these two types of subscripting are (compare with sections 3.4.1 and 3.4.2 in the R language definition),

Integer

The special zero index is not allowed with data lists. This is because it creates dimensions with zero length, which leads to non-sensical data frames that are generated by as.data.frame.data.list. Similarly, any subscripting with negative integers that results in some zero-length dimensions, also causes an error.

Other numeric

Identical to array-like subscripting, with truncation towards zero to integers.

Logical

Identical to array-like subscripting. Note that logical vectors longer than the dimension to be subscripted result in an error, unless there is only a single dimension in the data list – in which case, extra NA elements are added as needed (i.e. just as with subscripting of vectors and one-dimensional arrays).

Character

Identical to array-like subscripting.

Factor

Factor subscripting is not allowed with data lists.

Empty

Unlike array-like subscripting, x[] does not drop any attributes but rather simply returns x.

NULL

NULL subscripting is not allowed with data lists, for the same reason that zero subscripting is not allowed.

Matrix

Matrices are currently not valid subscripting objects but this could change in the future.

In list-like extraction, only a single subscript vector is used. A data list with the extracted variables is returned whenever a single subscript vector is used and the input data list has more than one dimension of replication. By default, a one-dimensional data list is also extracted in a list-like manner whenever a single subscript vector is used; however, this behaviour can be changed by setting vextract = FALSE, which leads to (one-dimensional-)array-like subscripting. Whenever the resulting data list is composed of variables that are replicated along fewer dimensions than the original data list, those dimensions are dropped without exception. If the resulting data list is only replicated along a single dimension, it is coerced to a data frame by default unless drop = FALSE. If no variables remain in the resulting data list, then an error is thrown.

The $<-.data.list and [[<-.data.list methods of replacement work very much like the default methods $<- and [[<- for lists, except that they ensure that a valid data list object is returned. One technical difference between the default and data.list methods for $<- is that new variables cannot be added by passing a new name to i. However new variables can be added to an existing data list using [[<-.data.list. Adding new variables in this way is only slightly more complicated than adding new variables to a data frame; when adding to a data list, one must specify the dimensions of replication of the new variable in one of two ways. Perhaps the easiest way is via the shape argument, which expects the name of an existing variable; the dimensions of the new variable are then assumed to be identical to the dimensions of the old variable specified via shape, and if this is not the case an error is thrown. The other way to specify dimensions is via the match.dimids argument, which accepts a character vector supplying the ids of the replication dimensions of the new variable. Note that match.dimids is ignored if shape is also provided. Setting drop = FALSE in `[[<-`.data.list ensures that the output will be a data list (i.e. the replication dimensions will not be dropped to create a data frame even if the resulting data list has only a single dimension). To make use of the default replacement methods for lists, simply unclass the data list object as in unclass(x)[...], unclass(x)$i <- value, and unclass(x)[[i]] <- value.

See Also

data.list for creating new data lists and as.data.frame.data.list for coercing data lists to data frames.

Examples

data(fake.community)
fake.community

## array-like extraction
fake.community[1:3, , ]
fake.community["arctic", c("2009", "2008"), c(TRUE, TRUE, FALSE)]

## list-like extraction
fake.community["abundance"]
fake.community["body.size"]
fake.community["body.size", drop = FALSE]
fake.community[c("abundance", "body.size")]
fake.community[1:3]

## assignment
fake.community$abundance  <- log1p(fake.community$abundance)
fake.community[[6]] <- NULL
fake.community$body.size <- fake.community$precipitation <- NULL
fake.community

## adding a new variable to an existing data list
fake.community[["newvar", match.dimids = "years"]] <- letters[1:3]
fake.community[["reallynewvar", shape = "metabolic.rate"]] <- runif(3)
fake.community[["sites", match.dimids = "sites"]] <- 
	dimnames(fake.community)[[1]]
fake.community

stevencarlislewalker/multitable documentation built on May 30, 2019, 4:44 p.m.