updateObject {Biobase} | R Documentation

## Update an object to its current class definition

### Description

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:

`updateObject(ANY, ..., verbose=FALSE)`
  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}`.
`updateObject(list, ..., verbose=FALSE)`
  Visit each element in `list`, applying `updateObject(list[[elt]], ..., verbose=verbose)`.
`updateObject(environment, ..., verbose=FALSE)`
  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:

`updateObjectTo(ANY-object,ANY-template)`
  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.

### Usage

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

### Arguments

`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

### Value

`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`.

### Author(s)

Biocore team

### See Also

`Versions-class`

### Examples

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

    ## Not run:
    ## generally, use 'as' to coerce objects between classes
    data(sample.exprSet)
    obj <- as(sample.exprSet, "ExpressionSet")
    ## End(Not run)

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

[Package Biobase version 1.14.1 Index]