setClass function - RDocumentation (2024)

Class

character string name for the class.

slots

The names and classes for the slots in the new class. This argument must be supplied by name, slots=, in the call, for back compatibility with other arguments no longer recommended.

The argument must be vector with a names attribute, the names being those of the slots in the new class. Each element of the vector specifies an existing class; the corresponding slot must be from this class or a subclass of it. Usually, this is a character vector naming the classes. It's also legal for the elements of the vector to be class representation objects, as returned by getClass.

As a limiting case, the argument may be an unnamed character vector; the elements are taken as slot names and all slots have the unrestricted class "ANY".

contains

A vector specifying existing classes from which this class should inherit. The new class will have all the slots of the superclasses, with the same requirements on the classes of these slots. This argument must be supplied by name, contains=, in the call, for back compatibility with other arguments no longer recommended.

See the section ‘Virtual Classes’ for the special superclass "VIRTUAL".

prototype, where, validity, sealed, package

These arguments are currently allowed, but either they are unlikely to be useful or there are modern alternatives that are preferred.

prototype: supplies an object with the default data for the slots in this class. A more flexible approach is to write a method for initialize().

where: supplies an environment in which to store the definition. Should not be used: For calls to setClass() appearing in the source code for a package the definition will be stored in the namespace of the package.

validity: supplied a validity-checking method for objects from this class. For clearer code, use a separate call to setValidity().

sealed: if TRUE, the class definition will be sealed, so that another call to setClass will fail on this class name. But the definition is automatically sealed after the namespace is loaded, so explicit sealing it is not needed.

package: supplies an optional package name for the class, but the class attribute should be the package in which the class definition is assigned, as it is by default.

representation, access, version, S3methods

All these arguments are deprecated from version 3.0.0 of R and should be avoided.

representation is an argument inherited from S that included both slots and contains, but the use of the latter two arguments is clearer and recommended.

access and version are included for historical compatibility with S-Plus, but ignored.

S3methods is a flag indicating that old-style methods will be written involving this class; ignored now.

Basic Use: Slots and Inheritance

The two essential arguments other than the class name areslots and contains, defining the explicit slotsand the inheritance (superclasses). Together, these arguments defineall the information in an object from this class; that is, the namesof all the slots and the classes required for each of them.

The name of the class determineswhich methods apply directly to objects from this class. Thesuperclass information specifies which methods apply indirectly,through inheritance. See Methods_Details for inheritance in methodselection.

The slots in a class definition will be the union of all the slotsspecified directly by slots and all the slots in allthe contained classes.There can only be one slot with a given name.A class may override the definition of a slot with a given name, butonly if the newly specified class is a subclass of theinherited one.For example, if the contained class had a slot a with class"ANY", then a subclass could specify a with class"numeric",but if the original specification for the slot was class"character", the new call to setClass would generate an error.

Slot names "class" and "Class" are not allowed. There are other slot names with a special meaning; these names start with the "." character. To be safe, you should define all of your own slots with names starting with an alphabetic character.

Some inherited classes will be treated specially---object types, S3classes and a few special cases---whether inheriteddirectly or indirectly. See the next three sections.

Virtual Classes

Classes exist for which no actual objects can be created, the virtual classes.

The most common and useful form of virtual class is the class union, a virtual class that is defined in a call to setClassUnion() rather than a call to setClass(). This call lists the members of the union---subclasses that extend the new class. Methods that are written with the class union in the signature are eligible for use with objects from any of the member classes. Class unions can include as members classes whose definition is otherwise sealed, including basic R data types.

Calls to setClass() will also create a virtual class, either when only the Class argument is supplied (no slots or superclasses) or when the contains= argument includes the special class name "VIRTUAL".

In the latter case, a virtual class may include slots to provide some common behavior without fully defining the object---see the class '>traceable for an example. Note that "VIRTUAL" does not carry over to subclasses; a class that contains a virtual class is not itself automatically virtual.

Inheriting from Object Types

In addition to containing other S4 classes, a class definition cancontain either an S3 class (see the next section) or a built-in R pseudo-class---oneof the Robject types or one of the special R pseudo-classes "matrix" and"array".A class can contain at most one of the object types, directly or indirectly.When it does, that contained class determines the “data part”of the class.This appears as a pseudo-slot, ".Data" and can be treated as aslot but actually determinesthe type of objects from this slot.

Objects from the new class try to inherit the built inbehavior of the contained type.In the case of normal R data types, including vectors, functions andexpressions, the implementation is relatively straightforward.For any object x from the class,typeof(x) will be the contained basic type; and a specialpseudo-slot, .Data, will be shown with the corresponding class.See the "numWithId" example below.

Classes may also inherit from "vector", "matrix" or"array".The data part of these objects can be any vector data type.

For an object from any class that does not contain one of thesetypes or classes,typeof(x) will be "S4".

Some R data types do not behave normally, in the sense that they arenon-local references or other objects that are not duplicated.Examples include those corresponding to classes "environment", "externalptr", and "name".These can not be the types for objects with user-definedclasses (either S4 or S3) because setting an attribute overwrites theobject in all contexts.It is possible to define a class that inherits from such types,through an indirect mechanism that stores the inherited object in areserved slot, ".xData".See theexample for class "stampedEnv" below.An object from such a class does not have a ".Data" pseudo-slot.

For most computations, these classes behave transparently as if theyinherited directly from the anomalous type.S3 method dispatch and the relevant as.type()functions should behave correctly, but code that uses the type of theobject directly will not.For example, as.environment(e1) would work as expected with the"stampedEnv" class, but typeof(e1) is "S4".

Inheriting from S3 Classes

Old-style S3 classes have no formal definition. Objects are“from” the class when their class attribute contains thecharacter string considered to be the class name.

Using such classes with formal classes and methods is necessarily arisky business, since there are no guarantees about the content of theobjects or about consistency of inherited methods.Given that, it is still possible to define a class that inherits froman S3 class, providing that class has been registered as an old class(see setOldClass).

Broadly speaking, both S3 and S4 method dispatch try to behavesensibly with respect to inheritance in either system.Given an S4 object, S3 method dispatch and the inheritsfunction should use the S4 inheritance information.Given an S3 object, an S4 generic function will dispatch S4 methodsusing the S3 inheritance, provided that inheritance has been declared viasetOldClass. For details, see setOldClassand Section 10.8 of the reference.

Classes and Packages

Class definitions normally belong to packages (but can be defined inthe global environment as well, by evaluating the expression on thecommand line or in a file sourced from the command line).The corresponding package name is part of the class definition; thatis, part of the '>classRepresentation object holding thatdefinition. Thus, two classes with the same name can exist indifferent packages, for most purposes.

When a class name is supplied for a slot or a superclass in a call tosetClass, acorresponding class definition will be found, looking from thenamespace of the current package, assuming the call in question appears directly in the source for thepackage, as it should to avoid ambiguity.The class definitionmust be already defined in this package, in the imports directives ofthe package's DESCRIPTION andNAMESPACE files or in the basic classes defined by the methods package.(The ‘methods’ package must be included in the imports directivesfor any package that usesS4 methods and classes, to satisfy the"CMD check" utility.)

If a package imports two classes of the same name from separate packages, the packageSlotof the name argument needs to be set to the package name of theparticular class.This should be a rare occurrence.

Examples

Run this code

# NOT RUN {## A simple class with two slotstrack <- setClass("track", slots = c(x="numeric", y="numeric"))## an object from the classt1 <- track(x = 1:10, y = 1:10 + rnorm(10))## A class extending the previous, adding one more slottrackCurve <- setClass("trackCurve",slots = c(smooth = "numeric"),contains = "track")## an object containing a superclass objectt1s <- trackCurve(t1, smooth = 1:10)## A class similar to "trackCurve", but with different structure## allowing matrices for the "y" and "smooth" slotssetClass("trackMultiCurve", slots = c(x="numeric", y="matrix", smooth="matrix"), prototype = list(x=numeric(), y=matrix(0,0,0), smooth= matrix(0,0,0)))## A class that extends the built-in data type "numeric"numWithId <- setClass("numWithId", slots = c(id = "character"), contains = "numeric")numWithId(1:3, id = "An Example")## inherit from reference object of type "environment"stampedEnv <- setClass("stampedEnv", contains = "environment", slots = c(update = "POSIXct"))setMethod("[[<-", c("stampedEnv", "character", "missing"), function(x, i, j, ..., value) { ev <- as(x, "environment") ev[[i]] <- value #update the object in the environment x@update <- Sys.time() # and the update time x})e1 <- stampedEnv(update = Sys.time())e1[["noise"]] <- rnorm(10)# }# NOT RUN {<!-- %dont show --># }

Run the code above in your browser using DataLab