relist                 package:utils                 R Documentation

_A_l_l_o_w _R_e-_L_i_s_t_i_n_g _a_n _u_n_l_i_s_t_e_d() _O_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_n:

     '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"'.

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

   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?

_D_e_t_a_i_l_s:

     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


_V_a_l_u_e:

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

_A_u_t_h_o_r(_s):

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

_S_e_e _A_l_s_o:

     'unlist'

_E_x_a_m_p_l_e_s:

      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))

