Methods               package:methods               R Documentation

_G_e_n_e_r_a_l _I_n_f_o_r_m_a_t_i_o_n _o_n _M_e_t_h_o_d_s

_D_e_s_c_r_i_p_t_i_o_n:

     This documentation section covers some general topics on how
     methods work and how the 'methods' package interacts with the rest
     of R.  The information is usually not needed to get started with
     methods and classes, but may be helpful for moderately ambitious
     projects, or when something doesn't work as expected.

     The section "How Methods Work" describes the underlying mechanism;
     "S3 Methods" gives the rules applied when S4 classes and methods
     interact with older S3 methods; "Method Selection and Dispatch"
     provides more details on how class definitions determine which
     methods are used; "Generic Functions" discusses generic functions
     as objects. For additional information specifically about class
     definitions, see 'Classes'.

_H_o_w _M_e_t_h_o_d_s _W_o_r_k:

     A generic function  has associated with it a collection of other
     functions (the methods), all of which have the same formal
     arguments as the generic.  See the "Generic Functions" section
     below for more on generic functions themselves.

     Each R package will include  methods metadata objects
     corresponding to each generic function  for which methods have
     been defined in that package. When the package is loaded into an R
     session, the methods for each generic function are _cached_, that
     is, stored in the environment of the generic function along with
     the methods from previously loaded packages.  This merged table of
     methods is used to dispatch or select methods from the generic,
     using class inheritance and possibly group generic functions (see
     'GroupGenericFunctions') to find an applicable method. See the
     "Method Selection and Dispatch" section below. The caching
     computations ensure that only one version of each generic function
     is visible globally; although different attached packages may
     contain a copy of the generic function, these behave identically
     with respect to method selection. In contrast, it is possible for
     the same function name to refer to more than one generic function,
     when these have different 'package' slots.  In the latter case, R
     considers the functions unrelated:  A generic function is defined
     by the combination of name and package.  See the "Generic
     Functions" section below.

     The methods for a generic are stored according to the
     corresponding 'signature' in the call to 'setMethod' that defined 
     the method.  The signature associates one class name with each of
     a subset of the formal arguments to the generic function.  Which
     formal arguments are available, and the order in which they
     appear, are determined by the '"signature"' slot of the generic
     function itself.  By default, the signature of the generic
     consists of all the formal arguments except ..., in the order they
     appear in the function definition.

     Trailing arguments in the signature of the generic will be
     _inactive_  if no method has yet been specified that included
     those arguments in its signature. Inactive arguments are not
     needed or used in labeling the cached methods.  (The distinction
     does not change which methods are dispatched, but ignoring
     inactive arguments improves the efficiency of dispatch.)

     All arguments in the signature of the generic function will be
     evaluated when the function is called, rather than using the
     traditional lazy evaluation rules of S.  Therefore, it's important
     to _exclude_ from the signature any arguments that need to be
     dealt with symbolically (such as the first argument to function
     'substitute').  Note that only actual arguments are evaluated, not
     default expressions. A missing argument enters into the method
     selection as class '"missing"'.

     The cached methods are stored in an environment object.  The names
     used for assignment are a concatenation of the class names for the
     active arguments in the method signature.

_S_3 _M_e_t_h_o_d_s:

     The functions for which S4 methods will be written often include
     some for which S3 methods exist, corresponding to S3 classes for
     the first formal argument of an S3 generic function or of a
     primitive function, or for either of the arguments in a call to
     one of the primitive binary operators. In the case of true
     functions, S3 methods will be dispatched by the original version
     of the function.  The usual way this happens is by the function
     becoming the default method for the S4 generic, implicitly by a
     call to 'setMethod' or explicitly by the call

     'setGeneric("f")'

     where the original 'f()' contained the call 'UseMethod("f")'. The
     S4 method selection code matches the classes of the arguments as
     described in the previous section. Matching will be applied for
     the class of S3 objects as well as S4 objects, but only the first
     string in an S3 class attribute is used. If no non-default S4
     method matches the call,  the default S4 method can then operate
     as an S3 generic to select S3 methods for 'f()'.

     Primitive functions and operators dispatch both S4 and S3 methods
     from the internal C code. The method selection mechanism works
     essentially the same way, with two exceptions. There is no
     explicit generic function, either S3 or S4, meaning that the
     selection of an S3 method if no S4 method is found is built in and
     not a result of an explicit default method. Also, the internal
     code does not look for S4 methods unless the first argument or one
     of the arguments to an operator is an S4 object. S4 methods can be
     defined for an S3 generic function and an S3 class. But if the
     function is a primitive, such methods will not be selected if the
     object in question is not an S4 object. In the examples below, for
     instance,  an S4 method for signature '"data.frame"' for function
     'f3()' would be called for the S3 object 'df1'. A similar S4
     method for primitive function '`[`' would be ignored for that
     object, but would be called for the S4 object 'mydf1' that
     inherits from '"data.frame"'. It's an unfortunate inconsistency,
     but enforced by the passion for efficiency in dispatching methods
     for primitives.

     The common case is that objects from S4 classes will use S4
     methods, except when the function's default definition is wanted. 
     For example, if an S4 class extends one of the basic object types
     the base code for that type may do what we want. Objects not from
     an S4 class will continue to follow S3 method selection.

     The rest of this section describes S3 method selection in two
     special cases. In one case, the S4 class contains an S3 class (and
     has ensured that objects have all the structure needed for the S3
     class). In the second case, S3 methods have been written for an S4
     class; that is, a function _f.class_, where _f_ is an S3 generic
     function and _class_ is the name of an S4 class, other than a
     registered S3 class. The first case is now supported and
     recommended, the second case is discouraged, but occasionally
     needed (see section 4 of the paper in the references).

     The following rules define selection of an S3 method for an S4
     object.  S4 objects are defined internally by a bit in the C
     structure.  In practice, any object generated from an S4 class
     will be an S4 object, as well as the result of most computations
     on such objects.  Older computations defined for non-S4 classes or
     object types may or may not return S4 objects when the arguments
     are such objects.

     An S3 method will be selected applying the following criteria in
     order:


        1.  the _class_ for the method matches the name of the S4 class
           exactly;

        2.  the object has a slot '".S3Class"' and _class_ is selected
           by S3 inheritance, treating that slot as the S3 class of the
           object;


     The second criterion will apply if either the S4 class contains an
     S3 class or the argument 'S3methods=TRUE' was given to 'setClass'
     for the class of the object or for one of its superclasses.

     If an S4 class extends an S3 class, and if no S4 methods take
     precedence, we expect that the correct S3 method for the inherited
     S3 class will be chosen. This will happen, so long as the S3 class
     has been registered by a call to 'setOldClass'. If so, the object
     from the S4 class will inherit a special slot that will be used as
     the class for S3 dispatch.  Effectively, this slot is a proxy for
     the class attribute expected by S3 dispatch.  It can even vary in
     its inheritance between objects, as happens with some S3 classes,
     such as 'POSIXt', if the replacement version of 'S3Class' is used
     to set it. If the class so selected is one of the basic S3
     classes, the object is converted to an S3 object with this vector
     as its class attribute.

     A second nonstandard situation arises when an S3 method has been
     explicitly written for an S4 class. Versions of R through 2.9.0
     did not recognize S4 inheritance in dispatching S3 methods, so
     that subclasses of the S4 class would not then inherit the S3
     method.  The version of R{} accompanying this documentation fixes
     this problem, to the extent practical, as follows. S3 method
     selection will resemble S4 selection for the same class _if_ the
     call to 'setClass' has included the argument 'S3methods = TRUE'.
     If not, the current behavior (R 2.9.1) is to select S3 methods
     defined for this class, but not for its subclasses  (largely for
     back compatibility; in future versions of R, S3 methods may be
     ignored for S4 classes unless 'S3methods' is set.) The
     implementation uses the same special slot as above for inheriting
     from an S3 class.  Subclasses of a class set this way will inherit
     the same special slot and the same S3 method selection. It's even
     possible to set the slot in individual objects, as above, but the
     possibilities for confusion are serious.

     Looking in the other direction, it remains true that S4 selection
     has no knowledge of S3 methods. This can cause problems when a
     class that expects to inherit the S3 method, '"classA"' in the
     example below, also inherits from another S4 class.  If that class
     inherits an S4 method for a function, no matter how indirectly,
     that S4 method will be selected for an object from '"classA"',
     even though there is a directly defined S3 method. The S3 method
     can only be accessed through the default S4 method. These problems
     are relatively unlikely to occur, but anyone defining a class that
     extends both S3 and S4 classes needs to be careful.

_M_e_t_h_o_d _S_e_l_e_c_t_i_o_n _a_n_d _D_i_s_p_a_t_c_h: _D_e_t_a_i_l_s:

     When a call to a generic function is evaluated, a method is
     selected corresponding to the classes of the actual arguments in
     the signature. First, the cached methods table is searched for an 
     exact match; that is, a method stored under the signature defined
     by the string value of 'class(x)' for each non-missing argument,
     and '"missing"' for each missing argument. If no method is found
     directly for the actual arguments in a call to a generic function,
     an attempt is made to match the available methods to the arguments
     by using the superclass information about the actual classes.

     Each class definition may include a list of  one or more
     _superclasses_ of the new class. The simplest and most common
     specification is by the 'contains=' argument in the  call to
     'setClass'. Each class named in this argument is a superclass of
     the new class. The S language has two additional mechanisms for
     defining superclasses. A call to  'setIs' can create an
     inheritance relationship that is not the simple one of containing
     the superclass representation in the new class. In this case,
     explicit methods are defined to relate the subclass and the
     superclass. Also, a call to 'setClassUnion' creates a union class
     that is a superclass of each of the members of the union. All
     three mechanisms are treated equivalently for purposes of method
     selection:  they define the _direct_ superclasses of a particular
     class. For more details on the mechanisms, see 'Classes'.

     The direct superclasses themselves may have superclasses, defined
     by any of the same mechanisms, and similarly for further
     generations.  Putting all this information together produces the
     full list of superclasses for this class. The superclass list is
     included in the definition of the class that is cached during the
     R session. Each element of the list describes the nature of the
     relationship (see 'SClassExtension' for details). Included in the
     element is a 'distance' slot giving a numeric distance between the
     two classes. The distance is the path length for the relationship:
     '1' for direct superclasses (regardless of which mechanism defined
     them), then '2' for the direct superclasses of those classes, and
     so on. In addition, any class implicitly has class '"ANY"' as a
     superclass.  The distance to '"ANY"' is treated as larger than the
     distance to any actual class. The special class '"missing"'
     corresponding to missing arguments has only '"ANY"' as a
     superclass, while '"ANY"' has no superclasses.

     When a class definition is created or modified, the superclasses
     are ordered, first by a stable sort of the all superclasses by
     distance. If the set of superclasses has duplicates (that is, if
     some class is inherited through more than one relationship), these
     are removed, if possible, so that the list of superclasses is
     consistent with the superclasses of all direct superclasses. See
     the reference on inheritance for details.

     The information about superclasses is summarized when a class
     definition is printed.

     When a method is to be selected by inheritance, a search is made
     in the table for all methods directly corresponding to a
     combination of either the direct class or one of its superclasses,
     for each argument in the active signature. For an example, suppose
     there is only one argument in the signature and that the class of
     the corresponding object was '"dgeMatrix"' (from the recommended
     package 'Matrix'). This class has two direct superclasses and
     through these 4 additional superclasses. Method selection finds
     all the methods in the table of directly specified methods labeled
     by one of these classes, or by '"ANY"'.

     When there are multiple arguments in the signature, each argument
     will generate a similar  list of inherited classes. The possible
     matches are now all the combinations of classes from each argument
     (think of the function 'outer' generating an array of all possible
     combinations). The search now finds all the methods matching any
     of this combination of classes. For each argument, the position in
     the list of superclasses of that argument's class defines which
     method or methods (if the same class appears more than once) match
     best. When there is only one argument, the best match is
     unambiguous. With more than one argument, there may be zero or one
     match that is among the best matches for _all_ arguments.

     If there is no best match, the selection is ambiguous and a
     message is printed noting which method was selected (the first
     method lexicographicaly in the ordering) and what other methods
     could have been selected. Since the ambiguity is usually nothing
     the end user could control, this is not a warning. Package authors
     should examine their package for possible ambiguous inheritance by
     calling 'testInheritedMethods'.

     When the inherited method has been selected, the selection is
     cached in the generic function so that future calls with the same
     class will not require repeating the search.  Cached inherited
     selections are not themselves used in future inheritance searches,
     since that could result in invalid selections. If you want
     inheritance computations to be done again (for example, because a
     newly loaded package has a more direct method than one that has
     already been used in this session), call 'resetGeneric'.  Because
     classes and methods involving them tend to come from the same
     package, the current implementation does not reset all generics
     every time a new package is loaded.

     Besides being initiated through calls to the generic function,
     method selection can be done explicitly by calling the function
     'selectMethod'.

     Once a method has been selected, the evaluator creates a new
     context in which a call to the method is evaluated. The context is
     initialized with the arguments from the call to the generic
     function. These arguments are not rematched.  All the arguments in
     the signature of the generic will have been evaluated (including
     any that are currently inactive); arguments that are not in the
     signature will obey the usual lazy evaluation rules of the
     language. If an argument was missing in the call, its default
     expression if any will _not_ have been evaluated, since method
     dispatch always uses class 'missing' for such arguments.

     A call to a generic function therefore has two contexts:  one for
     the function and a second for the method. The argument objects
     will be copied to the second context, but not any local objects
     created in a nonstandard generic function. The other important
     distinction is that the parent  ("enclosing") environment of the
     second context is the environment of the method as a function, so
     that all R programming techniques using such environments apply to
     method definitions as ordinary functions.

     For further discussion of method selection and dispatch,  see the
     first reference.

_G_e_n_e_r_i_c _F_u_n_c_t_i_o_n_s:

     In principle, a generic function could be any function that
     evaluates a call to 'standardGeneric()', the internal function
     that selects a method and evaluates a call to  the selected
     method.  In practice, generic functions are special objects that
     in addition to being from a subclass of class '"function"' also
     extend the class 'genericFunction'.  Such objects have slots to
     define information needed to deal with their methods.  They also
     have specialized environments, containing the tables used in
     method selection.

     The slots '"generic"' and  '"package"' in the object are the
     character string names of the generic function itself and of the
     package from which the  function is defined. As with classes,
     generic functions are uniquely defined in R by the combination of
     the two names. There can be generic functions of the same name
     associated with different packages (although inevitably keeping
     such functions cleanly distinguished is not always easy). On the
     other hand, R will enforce that only one definition of a generic
     function can be associated with a particular combination of
     function and package name, in the current session or other active
     version of R.

     Tables of methods for a particular generic function, in this
     sense, will often be spread over several other packages. The total
     set of methods for a given generic function may change during a
     session, as additional packages are loaded. Each table must be
     consistent in the signature assumed for the generic function.

     R distinguishes _standard_ and _nonstandard_ generic functions,
     with the former having a function body that does nothing but
     dispatch a method. For the most part, the distinction is just one
     of simplicity:  knowing that a generic function only dispatches a
     method call allows some efficiencies and also removes some
     uncertainties.

     In most cases, the generic function is the visible function
     corresponding to that name, in the corresponding package. There
     are two exceptions, _implicit_ generic functions and the special
     computations required to deal with R's _primitive_ functions.
     Packages can contain a table of implicit generic versions of
     functions in the package, if the package wishes to leave a
     function non-generic but to constrain what the function would be
     like if it were generic. Such implicit generic functions are
     created during the installation of the package, essentially by
     defining the generic function and possibly methods for it, and
     then reverting the function to its non-generic form. (See
     implicitGeneric for how this is done.) The mechanism is mainly
     used for functions in the older packages in R, which may prefer to
     ignore S4 methods. Even in this case, the actual mechanism is only
     needed if something special has to be specified. All functions
     have a corresponding implicit generic version defined
     automatically (an implicit, implicit generic function one might
     say). This function is a standard generic with the same arguments
     as the non-generic function, with the non-generic version as the
     default (and only) method, and with the generic signature being
     all the formal arguments except ....

     The implicit generic mechanism is needed only to override some
     aspect of the default definition. One reason to do so would be to
     remove some arguments from the signature. Arguments that may need
     to be interpreted literally, or for which the lazy evaluation
     mechanism of the language is needed, must _not_ be included in the
     signature of the generic function, since all arguments in the
     signature will be evaluated in order to select a method. For
     example, the argument 'expr' to the function 'with' is treated
     literally and must therefore be excluded from the signature.

     One would also need to define an implicit generic if the existing
     non-generic function were not suitable as the default method.
     Perhaps the function only applies to some classes of objects, and
     the package designer prefers to have no general default method. In
     the other direction, the package designer might have some ideas
     about suitable methods for some classes, if the function were
     generic. With reasonably modern packages, the simple approach in
     all these cases is just to define the function as a generic. The
     implicit generic mechanism is mainly attractive for older packages
     that do not want to require the methods package to be available.

     Generic functions will also be defined but not obviously visible
     for functions implemented as _primitive_ functions in the base
     package. Primitive functions look like ordinary functions when
     printed but are in fact not function objects but objects of two
     types interpreted by the R evaluator to call underlying C code
     directly. Since their entire justification is efficiency, R
     refuses to hide primitives behind a generic function object.
     Methods may be defined for most primitives, and corresponding
     metadata objects will be created to store them. Calls to the
     primitive still go directly to the C code, which will sometimes
     check for applicable methods. The definition of "sometimes" is
     that methods must have been detected for the function in some
     package loaded in the session and 'isS4(x)' is 'TRUE' for  the
     first argument (or for the second argument, in the case of binary
     operators). You can test whether methods have been detected by
     calling 'isGeneric' for the relevant function and you can examine
     the generic function by calling 'getGeneric', whether or not
     methods have been detected. For more on generic functions, see the
     first reference and also section 2 of _R Internals_.

_M_e_t_h_o_d _D_e_f_i_n_i_t_i_o_n_s:

     All method definitions are stored as objects from the
     'MethodDefinition' class. Like the class of generic functions,
     this class extends ordinary R functions with some additional
     slots: '"generic"', containing the name and package of the generic
     function, and two signature slots, '"defined"' and '"target"', the
     first being the signature supplied when the method was defined by
     a call to 'setMethod'. The  '"target"' slot starts off equal to
     the '"defined"' slot.  When an inherited method is cached after
     being selected, as described above, a copy is made with the 
     appropriate '"target"'  signature. Output from 'showMethods', for
     example, includes both signatures.

     Method definitions are required to have the same formal arguments
     as the generic function, since the method dispatch mechanism does
     not rematch arguments, for reasons of both efficiency and
     consistency.

_R_e_f_e_r_e_n_c_e_s:

     Chambers, John M. (2008) _Software for Data Analysis: Programming
     with R_ Springer.  (For the R version: see section 10.6 for method
     selection and section 10.5 for generic functions).

     Chambers, John M.(2009) _Developments in Class Inheritance and
     Method Selection_ <URL:
     http://stat.stanford.edu/~jmc4/classInheritance.pdf>.

     Chambers, John M. (1998) _Programming with Data_ Springer (For the
     original S4 version.)

_S_e_e _A_l_s_o:

     For more specific information, see 'setGeneric', 'setMethod', and
     'setClass'.

     For the use of ... in methods, see  dotsMethods.

_E_x_a_m_p_l_e_s:

     ## The rules for inheriting S3 methods.

     f3 <- function(x)UseMethod("f3") # an S3 generic to illustrate inheritance

     ## A class that extends a registered S3 class inherits that class' S3
     ## methods.  The S3 methods will be passed an object with the S3 class

     setClass("myFrame", contains = "data.frame",
         representation(date = "POSIXt", type = "character"))

     df1 <- data.frame(x = 1:10, y = rnorm(10), z = sample(letters,10))

     mydf1 <- new("myFrame", df1, date = Sys.time())

     ## "myFrame" objects inherit "data.frame" S3 methods; e.g., for `[`

     mydf1[1:2, ] # a data frame object (with extra attributes "date" and "type")



     ## Extending an S3 class with inconsistent (instance-based) inheritance
     setClass("myDateTime", contains = "POSIXt")

     now <- Sys.time() # class(now) is c("POSIXt", "POSIXct")
     nowLt <- as.POSIXlt(now)# class(nowLt) is c("POSIXt", "POSIXlt")

     mCt <- new("myDateTime", now)
     mLt <- new("myDateTime", nowLt)

     ## S3 methods will be selected using instance-based information

     f3.POSIXct <- function(x) "The POSIXct result"
     f3.POSIXlt <- function(x) "The POSIXlt result"

     stopifnot(identical(f3(mCt), f3.POSIXct(mCt)))
     stopifnot(identical(f3(mLt), f3.POSIXlt(mLt)))


     ## An S4 class that does not contain a registered S3 class or object type
     ## selects S3 methods according to its S4 "inheritance"
     ## but only if the class definition requests this via S3methods=TRUE
     ## ( from version 2.9.1 on)

     setClass("classA", contains = "numeric",
        representation(realData = "numeric"), S3methods = TRUE)

     Math.classA <- function(x) {(getFunction(.Generic))(x@realData)}

     x <- new("classA", log(1:10), realData = 1:10)

     stopifnot(identical(abs(x), 1:10))

     setClass("classB", contains = "classA")

     y <- new("classB", x)

     stopifnot(identical(abs(y), 1:10)) # (version 2.9.0 or earlier fails here)

     ## Note: with a class that tries to combine both S3 and S4 superclasses.
     ## The S3 inheritance is used and the S3 method for
     ## the S4 superclass will not be selected.

     setClass("classC", representation(x = "numeric"))

     # an S3 method for "[" (not a good idea, but it would work)
     `[.classc` <- function(x, ..., drop = TRUE) {x@x[...]}

     setClass("classD", contains = c("classC", "data.frame"))

     ## by the rule mentioned in the S3 method section, the
     ## S3 methods are selected from the S3 class defined; that is, "data.frame"
     ## If the user expected to inherit `[.classC`, no luck.
     xd <- new("classD", df1, x = 1:50)

     ## Note the error from `[.data.frame`
     try(xd[1:25])

