updateObject             package:Biobase             R Documentation

_U_p_d_a_t_e _a_n _o_b_j_e_c_t _t_o _i_t_s _c_u_r_r_e_n_t _c_l_a_s_s _d_e_f_i_n_i_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     These generic functions return an instance of 'object' updated to
     its current class definition (or to the class definition of
     'template', in the case of 'updateObjectTo').

     Updating objects is primarily useful when an object has been
     serialized (e.g., stored to disk) for some time (e.g., months),
     and the class definition has in the mean time changed. Because of
     the changed class definition, the serialized instance is no longer
     valid.

     'updateObject' requires that the class of the returned object be
     the same as the class of the argument 'object', and that the
     object is valid (see 'validObject'). By default, 'updateObject'
     has the following behaviors:

     '_u_p_d_a_t_e_O_b_j_e_c_t(_A_N_Y, ..., _v_e_r_b_o_s_e=_F_A_L_S_E)' By default, 'updateObject'
          uses heuristic methods to determine whether the object should
          be the `new' S4 type (introduced in R 2.4.0), but is not. If
          the heuristics indicate an update is required,  the
          'updateObjectFromSlots' function tries to update the object.
          The default method returns the original S4 object or the
          successfully updated object, or issues an error if an update
          is required but not possible. The optional named argument
          'verbose' causes a message to be printed describing the
          action. Arguments '...' are passed to
          'link{updateObjectFromSlots}'.

     '_u_p_d_a_t_e_O_b_j_e_c_t(_l_i_s_t, ..., _v_e_r_b_o_s_e=_F_A_L_S_E)' Visit each element in
          'list', applying 'updateObject(list[[elt]], ...,
          verbose=verbose)'.

     '_u_p_d_a_t_e_O_b_j_e_c_t(_e_n_v_i_r_o_n_m_e_n_t, ..., _v_e_r_b_o_s_e=_F_A_L_S_E)' Visit each element
          in 'environment', applying 'updateObject(environment[[elt]],
          ..., verbose=verbose)'

     'updateObjectTo' requires that the class of the returned object be
     the same as the class of the 'template' argument, and that the
     object is valid. Usually, updating proceeds by modifying slots in
     'template' with information from 'object', and returning
     'template'. Use 'as' to coerce an object from one type to another;
     'updateObjectTo' might be useful to update a virtual superclass.
     By default, 'updateObjectTo' has the following behavior:

     '_u_p_d_a_t_e_O_b_j_e_c_t_T_o(_A_N_Y-_o_b_j_e_c_t,_A_N_Y-_t_e_m_p_l_a_t_e)' Attempt
          'as(ANY-object,class(ANY-template))'.

     Sample methods are illustrated below.

     'updateObjectFromSlots(object, objclass = class(object), ...,
     verbose=FALSE)' is a utility function that identifies the
     intersection of slots defined in the 'object' instance and
     'objclass' definition. The corresponding elements in 'object' are
     then updated (with 'updateObject(elt, ..., verbose=verbose)') and
     used as arguments to a call to 'new(class, ...)', with '...'
     replaced by slots from the original object. If this fails,
     'updateObjectFromSlots' then tries 'new(class)' and assigns slots
     of 'object' to the newly created instance.

     'getObjectSlots(object)' extracts the slot names and contents from
     'object'. This is useful when 'object' was created by a class
     definition that is no longer current, and hence the contents of
     'object' cannot be determined by accessing known slots.

_U_s_a_g_e:

     updateObject(object, ..., verbose=FALSE)
     updateObjectTo(object, template, ..., verbose=FALSE)
     updateObjectFromSlots(object, objclass=class(object), ..., verbose=FALSE)
     getObjectSlots(object)

_A_r_g_u_m_e_n_t_s:

  object: Object to be updated, or for slot information to be extracted
          from.

template: Instance representing a template for updating object.

objclass: Optional character string naming the class of the object to
          be created.

 verbose: A logical, indicating whether information about the update
          should be reported. Use 'message' to report this.

     ...: Additional arguments, for use in specific update methods

_V_a_l_u_e:

     'updateObject' returns a valid instance of 'object'.
     'updateObjectTo' returns a valid instance of 'template'.
     'updateObjectFromSlots' returns an instance of class 'objclass'.
     'getObjectSlots' returns a list of named elements, with each
     element corresponding to a slot in 'object'.

_A_u_t_h_o_r(_s):

     Biocore team

_S_e_e _A_l_s_o:

     'Versions-class'

_E_x_a_m_p_l_e_s:

     ## update object, same class
     data(sample.ExpressionSet)
     obj <- updateObject(sample.ExpressionSet)

     ## generally, use 'as' to coerce objects between classes
     data(sample.eSet)
     obj <- as(sample.eSet, "MultiSet")

     setClass("UpdtA", representation(x="numeric"), contains="data.frame")
     setMethod("updateObject", signature(object="UpdtA"),
               function(object, ..., verbose=FALSE) {
                   if (verbose) message("updateObject object = 'A'")
                   object <- callNextMethod()
                   object@x <- -object@x
                   object
     })

     a <- new("UpdtA", x=1:10)
     ## See steps involved
     updateObject(a)

     removeClass("UpdtA")
     removeMethod("updateObject", "UpdtA")