relist {utils}R Documentation

Allow Re-Listing an unlisted() Object

Description

relist() is an S3 generic function with a few methods in order to allow easy inversion of unlist(obj) when that is used with an object obj of (S3) class "relistable".

Usage

relist(flesh, skeleton)
## Default S3 method:
relist(flesh, skeleton = attr(flesh, "skeleton"))
## S3 method for class 'factor':
relist(flesh, skeleton = attr(flesh, "skeleton"))
## S3 method for class 'list':
relist(flesh, skeleton = attr(flesh, "skeleton"))
## S3 method for class 'matrix':
relist(flesh, skeleton = attr(flesh, "skeleton"))

as.relistable(x)
is.relistable(x)

## S3 method for class 'relistable':
unlist(x, recursive = TRUE, use.names = TRUE)

Arguments

flesh .....
skeleton .........
x an R object, typically a list (or vector).
recursive logical. Should unlisting be applied to list components of x?
use.names logical. Should names be preserved?

Details

Some functions need many parameters, which are most easily represented in complex structures. Unfortunately, many mathematical functions in R, including optim and nlm can only operate on functions whose domain is a vector. R has unlist() to convert complex objects into a vector representation. relist(), it's methods and the functionality mentioned here provide the inverse operation to convert vectors back to the convenient structural representation. This allows structured functions (such as optim()) to have simple mathematical interfaces.

For example, a likelihood function for a multivariate normal model needs a variance-covariance matrix and a mean vector. It would be most convenient to represent it as a list containing a vector and a matrix. A typical parameter might look like

      list(mean=c(0, 1), vcov=cbind(c(1, 1), c(1, 0))).
However, optim cannot operate on functions that take lists as input; it only likes numeric vectors. The solution is conversion:
        ipar <- list(mean=c(0, 1), vcov=cbind(c(1, 1), c(1, 0)))
        initial.param <- as.relistable(ipar)

        ll <- function(param.vector)
        {
           param <- relist(param.vector)
           -sum(dnorm(x, mean = param$mean, vcov = param$vcov,
                      log = TRUE))
           ## NB: dnorm() has no vcov... you should get the point
        }

        optim(unlist(initial.param), ll)
relist takes two parameters: skeleton and flesh. Skeleton is a sample object that has the right shape but the wrong content. flesh is a vector with the right content but the wrong shape. Invoking
    relist(flesh, skeleton)
will put the content of flesh on the skeleton. You don't need to specify skeleton explicitly if the skeleton is stored as an attribute inside flesh. In particular, flesh was created from some object obj with unlist(as.relistable(obj)) then the skeleton attribute is automatically set.

As long as skeleton has the right shape, it should be a precise inverse of unlist. These equalities hold:

   relist(unlist(x), skeleton) == x
   unlist(relist(y, skeleton)) == y

   x <- as.relistable(x)
   relist(unlist(x)) == x

Value

.....................

Author(s)

R Core, based on a code proposal by Andrew Clausen.

See Also

unlist

Examples

 ipar <- list(mean=c(0, 1), vcov=cbind(c(1, 1), c(1, 0)))
 initial.param <- as.relistable(ipar)
 ul <- unlist(initial.param)
 relist(ul)
 stopifnot(identical(relist(ul), initial.param))

[Package utils version 2.6.2 Index]