\HeaderA{relist}{Allow Re-Listing an unlisted() Object}{relist}
\aliasA{as.relistable}{relist}{as.relistable}
\aliasA{is.relistable}{relist}{is.relistable}
\methaliasA{relist.default}{relist}{relist.default}
\methaliasA{relist.factor}{relist}{relist.factor}
\methaliasA{relist.list}{relist}{relist.list}
\methaliasA{relist.matrix}{relist}{relist.matrix}
\aliasA{unlist.relistable}{relist}{unlist.relistable}
\keyword{list}{relist}
\keyword{manip}{relist}
\begin{Description}\relax
\code{relist()} is an S3 generic function with a few methods in order
to allow easy inversion of \code{\LinkA{unlist}{unlist}(obj)} when that is used
with an object \code{obj} of (S3) class \code{"relistable"}.
\end{Description}
\begin{Usage}
\begin{verbatim}
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)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{flesh}] .....
\item[\code{skeleton}] .........
\item[\code{x}] an \R{} object, typically a list (or vector).
\item[\code{recursive}] logical.  Should unlisting be applied to list
components of \code{x}?
\item[\code{use.names}] logical.  Should names be preserved?
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Some functions need many parameters, which are most easily represented in
complex structures.  Unfortunately, many mathematical functions in \R,
including \code{\LinkA{optim}{optim}} and \code{\LinkA{nlm}{nlm}} can only operate on
functions whose domain is
a vector.  \R{} has \code{\LinkA{unlist}{unlist}()} to convert complex objects into a
vector representation.  \code{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 \code{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
\begin{alltt}
      list(mean=c(0, 1), vcov=cbind(c(1, 1), c(1, 0))).
\end{alltt}
However, \code{\LinkA{optim}{optim}} cannot operate on functions that take lists as input; it
only likes numeric vectors.  The solution is conversion:
\begin{alltt}
        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)
\end{alltt}
\code{relist} takes two parameters: skeleton and flesh.  Skeleton is a sample
object that has the right \code{shape} but the wrong content.  \code{flesh}
is a vector with the right content but the wrong shape.  Invoking
\begin{alltt}
    relist(flesh, skeleton)
\end{alltt}
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
\code{unlist(as.relistable(obj))}
then the skeleton attribute is automatically set.

As long as \code{skeleton} has the right shape, it should be a precise inverse
of \code{\LinkA{unlist}{unlist}}.  These equalities hold:
\begin{alltt}
   relist(unlist(x), skeleton) == x
   unlist(relist(y, skeleton)) == y

   x <- as.relistable(x)
   relist(unlist(x)) == x
\end{alltt}
\end{Details}
\begin{Value}
.....................
\end{Value}
\begin{Author}\relax
R Core, based on a code proposal by Andrew Clausen.
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{unlist}{unlist}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
 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))
\end{ExampleCode}
\end{Examples}

