S4 Classes and Methods

setClass() defines a class: its name and its slots, a named character vector in which each element is the class the slot must hold. The six slots of Book are the six columns of the books table, in the same order, with the same types as book() produces. new() creates an instance and @ reads or writes a slot; slot() does the same by name. The slots and contains arguments of setClass() must be supplied by name, the help page says, for back compatibility with other arguments that are no longer recommended.

Rscript attaches the methods package, so none of these scripts calls library(methods). That has been the case since R 3.5.0, whose NEWS says that when no default packages are specified, Rscript now uses the same default packages as R (before, it left methods out), and that setting the environment variable R_SCRIPT_LEGACY to yes restores the previous behaviour.

Source: R documentation: setClass

The default show() method prints the class name and every slot (the blank lines belong to the output). str() has an S4 layout, Formal class 'Book' [package ".GlobalEnv"] with 6 slots, and the class of the object carries a package attribute naming where the class was defined, here the global environment. typeof() is "S4": the object is neither a list nor an atomic vector, it is a bare object with attributes, and each slot is stored as an attribute. A class that contains a basic type behaves differently, which is explored in the section on S3 classes. isS4() tells an S4 object from an S3 one; is.object() is TRUE for both because both have a class attribute (the first is documented with isS4 and the second with is.object).

A class definition is a promise about the shape of every instance, and R enforces the promise at the points where an object is made or a slot is assigned. Each message below is the real text of R 4.6.1. Two of them are easy to meet in practice: the slot types are strict, so year = 2021 (a double) is refused where year = 2021L is accepted, and the same check runs when a slot is assigned with @<-.

Source: R documentation: slotOp

The first message (invalid name for slot of class) comes from new(), the second from reading with @, the third from writing with @<-. The two "wrong class" messages differ: new() reports the failure as an invalid object (invalid class “Book” object: invalid object for slot "year" in class "Book": got class "character", should be or extend class "integer") because it ends in validObject(), whereas an assignment reports assignment of an object of class “character” is not valid for @‘year’ in an object of class “Book”; is(value, "integer") is not TRUE. The last message is a reminder of the rule for unnamed arguments of new(): they must be objects of a superclass, which is how new("AudioBook", a_book, narrator = ...) copies the slots of a Book (shown later).

There is a documented way around the class check of an assignment: slot<- has a check argument, and check = FALSE skips it. The result is an object that no longer fits its class, which validObject() reports when it is called.

Source: R documentation: slot

A class is also an object, and a handful of functions ask the session about it. getClass() (or showClass()) prints the slots and the inheritance; slotNames() and getSlots() return them; isVirtualClass() says whether instances can exist; isClass() says whether a class is defined; and setClass() returns a generator function, invisibly, which is a shorthand for new("Book", ...). The help page of setClass() recommends assigning the generator to the name of the class, and notes that a call through the generator records the package of the class, which removes any ambiguity if two packages define classes with the same name.

Source: R documentation: isVirtualClass and showClass

Slots that were not given take the default of their class, which for the vector classes is the empty vector, and an object with unset slots is a valid object as far as R is concerned: new("Book") ran without complaint although a book without a title makes no sense. A slot is also copied on assignment (S4 objects have the same value semantics as vectors, unlike Reference Class or R6 objects), and identical() compares two S4 objects slot by slot. The help for getClass() is getClass.

A prototype gives the slots their default values, and a prototype of NA values is the usual choice for a record like a book. The help page of setClass() says that a more flexible approach than prototype= is an initialize() method, and recommends setValidity() rather than the validity= argument for "clearer code"; both arguments still work and are used below.

representation() is the older spelling of slots= and contains=: the first argument is a named vector of slot classes, and an unnamed element is a superclass. The slots argument of setClass() was added in R 3.0.0 (the NEWS calls it clearer and less ambiguous than representation), and the current help page lists representation, access, version and S3methods as deprecated since R 3.0.0. It still works, and older code and tutorials use it everywhere, which is why it is shown here; new code uses slots= and contains=. The same script shows two related facts: prototype() is the matching helper of representation(), and a subclass may redefine an inherited slot only with a subclass of the inherited class.

Source: R documentation: representation and prototype

The second chunk of the script shows that an unnamed character vector as slots defines slots of the unrestricted class "ANY". That is rarely what a class should do, since the point of slots is the type, but it is the shortest way to a throwaway class.

Source: R documentation: setClass

new() ends by calling validObject(), so the objects created in the next chunk are checked: the first passes, the next three are refused with the real messages. When several rules fail the message has one numbered line per problem, each repeated with the invalid class "Book" object: prefix (here shown with writeLines()), and a violation of the length rule is reported by the same method.

Source: R documentation: validObject

The checking stops at the edge of new(). A slot assignment with @<- checks that the value has the class the slot declares, and nothing else, so b@year <- 3000L is accepted silently and b@year is 3000; the invalid state is found only when something calls validObject() again. validObject(object, test = TRUE) returns the problems as a character vector instead of signalling an error, which is the form to use in code that wants to decide for itself. This is the most frequent surprise for people who come from a language where a setter validates: in S4 the validation is explicit, and the place for a validating setter is an accessor function (see the accessor section).

Source: R documentation: validObject

A subtler case is new("Book") with no data arguments. The default initialize() method calls validObject() only when there are arguments to initialize, so an empty new() returns the prototype without checking it. The object it returns has NA for the title and is invalid by the rules above, which validObject(empty, test = TRUE) confirms. This is not a bug but a design choice that matters elsewhere: R itself builds empty objects (to convert an object to a superclass, for example), and those objects must not trigger errors. It is also why a constructor function should always pass at least the required slots.

Source: R documentation: validObject, getValidity and setValidity

validObject() works bottom up, as the help page puts it: it checks the slots against their classes, then the superclasses (running the validity method of each one, from the most distant), then the validity method of the object’s own class. The method of a superclass is called with the object converted to that superclass, and methods "do not have to check validity of superclasses": validObject() calls them. If the slots or a superclass produce errors, the class’s own method is not called at all, which is easy to see with the AudioBook subclass defined in the inheritance section. The complete = TRUE argument additionally calls validObject() recursively on the object in each slot, which matters for a slot that itself holds S4 objects, such as the list of books in a shelf.

new("Book", ...) begins by copying the prototype of the class and then calls the generic function initialize(.Object, ...) with that copy and the other arguments. The default method fills the slots from the named arguments, treats unnamed arguments as objects from a superclass whose slots are copied, and calls validObject() (the details are in the help page ?new, and the methods for the basic classes are in ?initialize-methods). A class-specific method is the place to compute slot values from arguments that are not slots, or to normalise input before it is validated. The help page of new() states two rules for such methods: include ... among the formal arguments, and pass the arguments on with callNextMethod(), "which helps the definition of future subclasses of your class".

The initialize method for Book mirrors the S3 constructor book() of the scenario: it trims the title, author and genre, normalises the ISBN with normalise_isbn(), and converts the year and pages to integers, so new("Book", year = 2019) works where the plain default would reject a double. The arguments are modified in a list, and the list is handed to the next method, the default one, with do.call(callNextMethod, ...); the default method then fills the slots and runs validObject(), which is why normalisation comes before validation. The comparison with book() at the end of the chunk is slot by slot, and all six are identical.

Source: R documentation: new and initialize

The method also has to survive being called with no arguments, as in new("Book"), which is why it only touches the arguments that exist. A method that insists on an argument fails in places far from its definition (see the pitfalls section for the real error).

The generator returned by setClass() and the call new("Book", ...) both work, but a hand-written constructor function is the usual public interface of a class: the function has the name of the class, documented arguments with defaults, and one place to convert and check the input (the generator of setClass() is the simplest form of the same idea). Here Book() has the same arguments and defaults as book(), and R itself reports a missing title with the ordinary argument "title" is missing, with no default error because the argument has no default.

Source: R documentation: setClass, value

The function is deliberately thin. The conversion and validation live in initialize() and the validity method, so a call to new("Book", ...) and a call to Book(...) behave the same, and a subclass constructor can reuse the logic by calling new() with its own class name.

A generic function is an ordinary function whose body calls standardGeneric("name"); it dispatches to the method that matches the classes of the arguments. setGeneric(name, def) creates it and returns the name. A method is a function stored in the generic’s method table under a signature, the classes of some of the formal arguments; setMethod(name, signature, definition) stores it. The definition must have the formal arguments of the generic (... may stand for extra ones), and by default every formal argument except ... is in the signature. The call to setGeneric() is optional when the function already exists, but it is the way to declare a new one.

Source: R documentation: setGeneric

The generic pages_per_year() is called on a Book, and the method divides the pages by the age of the book on shelf_today (at least one year). A book without a year has no age and the result is NA. A call on an object of no suitable class fails with unable to find an inherited method for function ... for signature ..., and since R 4.4.0 the message names the signature argument (x = "character"), a change recorded in the NEWS as including "the signature argument names" in the dispatch error. A missing argument is dispatched as the class "missing", which is why the zero-argument call reports x = "missing".

What a generic does when no method matches depends on how it was made. If setGeneric() is given an existing function (setGeneric("describe")), that function becomes the default method, the one for the class "ANY", and it keeps working for every class without a method. If it is given a definition that is more than a call to standardGeneric(), that definition is the default method. If the definition only calls standardGeneric(), there is no default method and a call with an unsupported class fails with the dispatch error seen above; the help page of setGeneric() recommends, when no general default makes sense, a default method that signals an error with a message that explains why a specific method is needed. And setGeneric("nchar") on a function of another package creates a copy of the function in the current environment, whose default method is the original, which masks the original for code that runs from there; the original keeps running inside base, which is the situation that the R Internals manual describes as "somewhat problematic" for functions in base namespaces. In a package that is why methods for existing functions are exported with exportMethods() and not by exporting a new function.

Source: R documentation: setGeneric, Basic Use

Source: R documentation: setGeneric, Specialized Local Generics

Source: R Internals: Mechanics of S4 dispatch

The arguments valueClass, signature and group of setGeneric() change the generic in ways that are rarely needed (valueClass checks the class of the result, signature limits the arguments that take part in dispatch, group makes the generic a member of a group generic); the pitfalls section shows the effect of the first two.

The method that decides how an S4 object looks at the console is show(), a generic from the methods package. The autoprinter calls it for any S4 object, print() of an S4 object calls it too, and an object inside a list is displayed by it. An S3-style print.Book() is not used by the autoprinter of an S4 object (a script in the S3 section shows it), so a print method is the wrong tool; setMethod("show", "Book", ...) is the right one. The only argument of the generic is called object, and a method uses the same name. This show() prints the same line as format.book() of the scenario, prefixed with <Book> where the S3 version prints <book>.

Source: R documentation: show

is(object, "Class") asks whether the object belongs to the class, including through inheritance; with one argument it lists the object’s class and all its superclasses, nearest first. extends("AudioBook", "Book") asks the same about two class names, existsMethod() asks whether a method is defined for exactly that signature, and hasMethod() also counts inherited ones. The base function inherits() knows about S4 inheritance too, so inherits(ab, "Book") is TRUE; is() also understands the relations between basic types and class unions, which inherits() does not (is(1L, "numeric") is TRUE, inherits(1L, "numeric") is FALSE). The method table has no entry for pages_per_year on AudioBook yet, so existsMethod() is FALSE and hasMethod() is TRUE, and the call itself dispatches to the Book method.

Source: R documentation: is and extends

as(object, "Class") converts an object to another class. Going up the inheritance tree is automatic: as(ab, "Book") returns a plain Book with the extra slots dropped. With strict = FALSE, an object that already is a Book is returned unchanged, still an AudioBook, which is cheaper and is what method code uses when it only needs the superclass behaviour. A virtual superclass such as Item has no instances, and as(ab, "Item") returns a Book. Conversions that are not inheritance need a setAs() method, shown with S3 below.

Source: R documentation: as

getClass() and showClass() print the position of a class in the hierarchy: the slots, what the class extends (and at what distance) and its known subclasses. The distance is the number of generations between the classes, and method selection prefers the smaller distance. A class has the implicit superclass "ANY", at a larger distance than any real class.

Source: R documentation: showClass

A method for a subclass often needs the superclass behaviour plus a change. callNextMethod() with no arguments calls the next method with the current arguments; the help page says the next method sees the same actual arguments as the current one, as x = x in the call, so a local modification of x before the call is seen by the next method. In the AudioBook method of pages_per_year() the pages are estimated from the running time when the book has none, and the Book method then does the division. The show() method of AudioBook prints the Book line by calling callNextMethod() and adds a line for the narrator.

Source: R documentation: callNextMethod

The callNextMethod() call has two forms, and the choice matters in initialize() methods. With no arguments it re-sends the current arguments. With arguments (callNextMethod(.Object, ...)) it sends those, and the dispatch is unchanged: the arguments "have no effect on selecting the next method". A further caveat is in the help page’s section "Ambiguous Selection": when a method for two arguments is reached through a group generic or a class with two parents, the next method may be ambiguous, and the method should call a specific function or re-call the generic instead.

When two methods are equally good, R does not fail: it picks one, and prints a note. The help page describes the rule. Each argument produces a list of candidate classes with their distances, a method is "best" if it has the least distance for every argument, and when several are best, "the first method lexicographically in the ordering" is selected and a message names the others. The page adds that this is a message, not a warning, because the end user usually cannot do anything about it; package authors are told to check their packages with testInheritedMethods(). The fix is always a method for the combination that is ambiguous (the last two calls of the chunk). The note is printed once for each combination of classes, then the selection is cached.

Source: R documentation: Methods_Details, Method Selection: Details

The note is worth recognising: it names the method that was chosen, the target signature of the call, and the other candidates. callNextMethod() can reintroduce the ambiguity, as the help page of callNextMethod() explains, so a method for the exact pair should avoid it and call a specific function instead.

A class that extends a basic type or an S3 class gets a data part, visible as the pseudo-slot .Data, and its objects have the type of the basic class. Tagged below contains "character": its objects have type character, length() and toupper() work on the data, and toupper() returns a Tagged again, with the slot kept. A class with only slots has type "S4". R 4.4.0 renamed the C-level type S4SXP to OBJSXP to allow other object systems to use the same type, as the R Internals manual describes it ("S4 and other objects which do not consist solely of a simple type"); typeof() still reports "S4" for an object with the S4 bit set and reports "object" for an object that has the type but not the bit, as the S7 0.2.2 object in the script does. In other words the type of a classical S4 object did not change in 4.4.0, only the name of the C type behind it.

Source: R Internals: SEXPTYPEs

The figure shows the classes of this page as a Mermaid class diagram. Item is the virtual root, Book implements it with its six slots and the two methods defined for it, AudioBook adds narrator and minutes, Shelf holds a list of books, and Loan uses the class unions characterOrNULL and DateOrNULL (shown as the one union characterOrNULL here, with the date one in the slot type). The stereotypes in double angle brackets are written as HTML entities in the source of the diagram, since the browser would otherwise take <<interface>>-style text for an HTML tag.

Source: R documentation: showClass

The R FAQ answer to "How can I debug S4 methods?" is trace() with signature=: the tracer is inserted in the method that will be dispatched for that signature. trace() accepts an expression or function to run on entry (tracer), prints the call unless print = FALSE, and untrace() with the same signature removes it. The NEWS of R 4.5.0 adds that debug() and debugonce() also accept a string naming an S4 generic, and fixes debugonce() with a signature= for a method with a simple body. The general debugging tools are in Debugging.

Source: R FAQ 8.5: How can I debug S4 methods?

Last, removing methods and classes is possible and useful in a long interactive session, but it is not something a package does. The last chunk removes a method (a later call on a pair that depended on it fails with the dispatch error), repeats the removal to show the warning, and removes the Shelf class.

Source: R documentation: removeMethod

The manual says that a package using formal classes and methods "should have" Depends: methods in its DESCRIPTION, together with import(methods) or importFrom(methods, ...) in the NAMESPACE; a footnote adds that Imports: methods may suffice but that package code is little exercised without the methods package on the search path and may not be fully robust to that. The NEWS agrees with both halves: R 4.4.0 made the methods package "more robust to not being attached" and made R CMD check note S4-style exports without a strong dependence on it, and R 4.5.0 changed an internal function of methods to use requireNamespace() instead of require(), so loading class definitions no longer attaches packages. The roxygen2 example below uses Imports: methods and @import methods, which is what the check package for this page used and installed without complaint; the manual’s Depends form is the conservative choice.

Class definitions are evaluated in the order of the files in R/, which is alphabetical by default, and a class must exist when a subclass, a slot or a method refers to it. That is what the Collate field of DESCRIPTION controls ("a Collate field can be used for controlling the collation order" says Writing R Extensions). A package that puts AudioBook in audiobook.R and Book in book.R is collated audiobook.R first and fails to install with the real message below; the cure is to list the files in dependency order. roxygen2 writes the field itself from @include tags (the roxygen2 section below shows it).

Source: Writing R Extensions: Namespaces with S4 classes and methods

With Collate: 'audiobook.R' 'book.R' in the same package, R CMD INSTALL stops while it prepares the package code for lazy loading, and the output ends with these lines (the temporary paths are left out):

Source: Writing R Extensions: The DESCRIPTION file

The same applies to files that define methods for a generic defined in another file: the generic has to come first. In a package with several files, a layout that many S4 packages use is AllClasses.R (every setClass() and setValidity()), AllGenerics.R (every setGeneric()), then one file of methods per class, with a Collate: field listing them in that order.

The NAMESPACE is where S4 differs most from plain packages, because classes and methods are not functions that export() can name. The directives from section 1.5.6 are:

Source: Writing R Extensions: Namespaces with S4 classes and methods

A NAMESPACE for the model is short. exportMethods(show) exports the show method for Book and AudioBook, and the manual’s remark that importMethodsFrom() also imports any generics defined in that namespace for the methods is what makes importMethodsFrom(shelfS4, pages_per_year) enough for a package that only extends the generic.

Source: Writing R Extensions: Namespaces with S4 classes and methods

Two points are easy to miss. A generic from another package should be imported and extended, not redefined: the manual advises using the generics that stats4 exports (coef, vcov, …​) in preference to importing coef from stats and creating a second generic, because "this enables multiple packages to unambiguously set methods on those generics". And methods for primitive functions (length, [[, +) are always exported by the machinery whether or not they appear in exportMethods(), as the R Internals manual says ("Methods for primitives which are internally S4 generic are always exported"), so the line for length above is for clarity.

R 4.1.0 made R CMD check warn when a package exports an S4 class or method that does not exist, and R 4.4.0 added the note about the dependence on methods already mentioned. A package whose tests pass can still be missing a class from exportClasses(), so the check that matters is loading it in a fresh session and trying new() on each class that is meant to be public (the model was loaded and checked this way).

roxygen2 generates all of this from comments (see its article "Documenting S4" for the full list of supported calls; it points out that, unlike S3 and S7 methods, all S4 methods must be documented). @slot name description documents a slot in the class’s help page, @export before setClass() writes exportClasses() and before setMethod() writes exportMethods(), @export before setGeneric() writes export(), @exportClass, @exportMethod, @importClassesFrom and @importMethodsFrom are the explicit forms, and @include other.R writes the Collate field. @import methods in a package-level block writes import(methods). The documentation of S4 classes follows the topic naming of the Rd conventions (Book-class for a class, show,Book-method for a method), so class?Book and methods?show find it. roxygen2 8.1.1, which wrote the files below in the check package, records its version in Config/roxygen2/version.

Source: roxygen2 package documentation: Documenting S4

The generated NAMESPACE (with the @import methods block in R/shelfS4-package.R) and the Collate: field that @include produced were these. The Collate: field lists book.R before audiobook.R because of the @include book.R tag, and the package-level file comes last.

Source: roxygen2 package documentation: Managing imports and exports

Documenting S4 classes and methods for R CMD check follows the conventions of Writing R Extensions section 2.1.3: an \alias of the form class-class for a class and generic,signature_list-method for a method (with ANY for unspecified arguments), \S4method{generic}{signature}(arguments) in a \usage section when a method’s usage needs to be spelled out, and promptClass() and promptMethods() to generate skeletons. A package with methods for functions defined elsewhere is responsible for documenting its methods but not the function or its default method.

Scripts run with Rscript have methods attached (since R 3.5.0, see the start of the page), so setClass() works without library(methods). When methods is not attached, as with --default-packages=base or with R_SCRIPT_LEGACY=yes set, the functions are not found by name, and the call has to go through the namespace: methods::setClass() works but new() and isVirtualClass() need the prefix too. Neither the commands nor the failures are specific to S4, but they are the first thing to check when a script fails with could not find function "setClass". The commands and outputs below were run on R 4.6.1.

Source: R documentation: Rscript

The option --default-packages, the environment variable R_SCRIPT_DEFAULT_PACKAGES and the environment variable R_DEFAULT_PACKAGES choose the packages loaded at start-up, in that order of precedence. The NEWS of R 4.4.0 and 4.5.0 made the machinery that finds class definitions less dependent on methods being on the search path, but a script that calls new() or setClass() by their short names still needs it attached. A script run by Rscript therefore needs no library(methods) line.

S4 is the system of the Bioconductor project (https://bioconductor.org/). Its core data structures are S4 classes, among them the packages S4Vectors (low-level classes for vector-like and table-like data that other packages build on), GenomicRanges (ranges on a genome) and SummarizedExperiment (a matrix of assays with row and column annotations). The style of those packages is the one of this page: a constructor function named like the class, accessor generics instead of direct slot access, validity methods and show methods. Reading their source is a good source of idioms; the packages of CRAN and the tidyverse that do not use S4 are equally valid R, and the choice of system is the subject of OOP Overview and Base Types.

The recommended package Matrix (version 1.7-5 ships with R 4.6.1) is the most widely used S4 package of the base distribution. Matrix::Matrix() returns an object of a class chosen from a hierarchy of virtual classes (Matrix, sparseMatrix, …​) and concrete ones such as dgCMatrix, a sparse double matrix in compressed column format, and the usual S4 tools apply to it. The script builds a 0/1 matrix of which member borrowed which book from the loans table and then asks it the class questions of this page. isVirtualClass("Matrix") is TRUE, is() follows the hierarchy (a dgCMatrix is a sparseMatrix is a Matrix), and slotNames("dgCMatrix") lists the compressed-column representation (i, p, x, Dim, Dimnames, factors).

Source: Matrix package documentation: Matrix-class