as.data.list: Coercion to and from data lists

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

Description

These functions coerce lists and data frame objects to data lists and vice versa.

Usage

as.data.list(x, ...)

is.data.list(x)

is.4th.corner(x)

data.list.mold(x)

## Default S3 method:
as.data.list(x, dimids, match.dimids,
check = TRUE, drop = TRUE,...)

## S3 method for class 'data.list'
as.data.frame(x, row.names = NULL, 
optional = FALSE, scheme = "repeat", mold, ...)

## S3 method for class 'data.list'
as.matrix(x, ...)

## S3 method for class 'data.list'
as.list(x, drop.attr = TRUE, 
factorsTOstrings = FALSE, ...)

Arguments

x	An object. Either a data.list, data.frame, or list.
mold	A list typically obtained as output from data.list.mold. If missing, then mold is automatically created. See details.
dimids	See data.list for an explanation.
match.dimids	See data.list for an explanation.
check	See data.list for an explanation.
drop	If TRUE, single dimension data lists are coerced to data frames (i.e. their replication dimensions are 'dropped').
row.names	Passed to the default method after some processing.
optional	Passed to the default method after some processing.
scheme	Type of coercion. Currently, only "repeat" is allowed but others may follow.
drop.attr	Should the attributes of the data list be dropped?
factorsTOstrings	Should factors be converted to character strings?
...	Additional arguments (passed to the default method in as.data.frame.data.list).

Details

Ultimately, all functions that create data.list objects (i.e. data.list; dlcast; read.multitable; variable; variableGroup) are wrappers for as.data.list. From a practical perspective the as.data.list function is very similar to data.list, with the following principal differences:

• The as.data.list function requires that multiple objects be organised in a list (x) whereas data.list uses a ... argument.

• Like data.frame, data.list automatically names variables as character versions of the names passed to ..., whereas variables must be named explicitly with as.data.list.

The is.data.list function tests if an object inherits from class data.list.

The is.4th.corner function tests if an object is both a data list and has all the properties of a data set with a fourth corner problem.

By default, as.data.frame.data.list works in two steps. First, a mold of the coercion process is created with data.list.mold. The mold is a list of vectors, each with length equal to the number of rows in the coerced data frame. Each vector is associated with a particular variable in x and contains indices that point to the elements of that variable. Second, the mold is 'filled with' (i.e. used to subscript) x thereby producing the coerced data frame.

If data lists are to be iteratively coerced to data frames (e.g. repeated random subscripting and coercion), then speed can be enhanced by creating a mold explicitly with data.list.mold and then passing it to as.data.frame.data.list through the mold argument. Because the mold will be the same for any data list of the same 'shape', the mold only needs to be created once before the iterations thereby eliminating the need to iteratively create the mold.

The as.matrix method for data lists returns either a single matrix (if all variables are numeric or all variables are either factors or character); otherwise, two matrices are returned, one with the numeric and one with the factor variables respectively. The matrices are returned by first coercing to data frames and then to matrices. This method was created as a result of a suggestion by Philip Dixon.

The as.list.data.list function is equivalent to unclass if drop.attr = FALSE, otherwise (i.e. drop.attr = TRUE) the "match.dimids", "bm", and "repdim" attributes are dropped from x and the "subsetdim" attributes are dropped from each variable in x.

Value

The coerced object.

See Also

as.data.frame; as.list; as.matrix; variablize; data.list; dlcast; read.multitable.

Examples

data(fake.community)
fake.community

## testing for data list
is.data.list(fake.community)			# TRUE
is.data.list(fake.community$abundance)	# FALSE
is.array(fake.community$abundance)	# TRUE

## this example illustrates the main difference between
## \code{data.list} and \code{as.data.list}. compare with 
## the similar example in \code{\link{data.list}}. notice
## the naming problems with the latter method.
a1 <- matrix(runif(50), 10, 5)
a2 <- matrix(runif(50), 10, 5)
a3 <- matrix(runif(50), 10, 5)
a <- list(a1, a2, a3)
b <- runif(10)
c <- letters[1:5]
data.list(a, b, c)
as.data.list(list(a, b, c))

## coercing to a data frame with explicit mold creation
fake.mold <- data.list.mold(fake.community)
fake.mold
as.data.frame(fake.community)
as.data.frame(fake.community, mold = fake.mold)

## we can coerce a similar data list faster using this
## \code{fake.mold} object
fc.rnd <- fake.community
fc.rnd$abundance <- fc.rnd$abundance[sample(6), , ]
as.data.frame(fc.rnd,mold = fake.mold)

## unless drop=FALSE, simple data lists are immediately
## coerced into data frames -- simple data don't require
## data lists
x <- runif(10)
as.data.list(x)
as.data.list(x, drop = FALSE)

## different ways to coerce a data list to a list.
## each way can produce slightly different results.
as.list(fake.community)
as.list(fake.community, drop.attr = FALSE)
unclass(fake.community)
lapply(fake.community, I)
	
is.4th.corner(fake.community) ## FALSE	
dl <- dropdl(fake.community[,1,])
is.4th.corner(dl) ## TRUE
is.4th.corner(dl[1:3]) ## FALSE

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