EVOLUTION-MANAGER
Edit File: S3Part.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: S4 Classes that Contain S3 Classes</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for S3Part {methods}"><tr><td>S3Part {methods}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2> S4 Classes that Contain S3 Classes</h2> <h3>Description</h3> <p>A regular (S4) class may contain an S3 class, if that class has been registered (by calling <code><a href="setOldClass.html">setOldClass</a></code>). The functions described here provide information about contained S3 classes. See the section ‘Functions’. </p> <p>In modern <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span>, these functions are not usually needed to program with objects from the S4 class. Standard computations work as expected, including method selection for both S4 and S3. To coerce an object to its contained S3 class, use either of the expressions: </p> <p><code>as(object, S3Class); as(object, "S3")</code> </p> <p>where <code>S3Class</code> evaluates to the name of the contained class. These return slightly different objects, which in rare cases may need to be distinguished. See the section “Contained S3 Objects”. </p> <h3>Usage</h3> <pre> S3Part(object, strictS3 = FALSE, S3Class) S3Class(object) isXS3Class(classDef) slotsFromS3(object) ## the replacement versions of the functions are not recommended ## Create a new object from the class or use the replacement version of as(). S3Part(object, strictS3 = FALSE, needClass = ) <- value S3Class(object) <- value </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>object</code></td> <td> <p>an object from some class that extends a registered S3 class, or a basic vector, matrix or array object type. </p> <p>For most of the functions, an S3 object can also be supplied, with the interpretation that it is its own S3 part. </p> </td></tr> <tr valign="top"><td><code>strictS3</code></td> <td> <p>If <code>TRUE</code>, the value returned by <code>S3Part</code> will be an S3 object, with all the S4 slots removed. Otherwise, an S4 object will always be returned; for example, from the S4 class created by <code><a href="setOldClass.html">setOldClass</a></code> as a proxy for an S3 class, rather than the underlying S3 object. </p> </td></tr> <tr valign="top"><td><code>S3Class</code></td> <td> <p>the <code><a href="../../base/html/character.html">character</a></code> vector to be stored as the S3 class slot in the object. Usually, and by default, retains the slot from <code>object</code>, but an S3 superclass is allowed. </p> </td></tr> <tr valign="top"><td><code>classDef</code></td> <td> <p>a class definition object, as returned by <code><a href="getClass.html">getClass</a></code>. </p> <p><em>The remaining arguments apply only to the replacement versions, which are not recommended.</em> </p> </td></tr> <tr valign="top"><td><code>needClass</code></td> <td> <p>Require that the replacement value be this class or a subclass of it.</p> </td></tr> <tr valign="top"><td><code>value</code></td> <td> <p>For <code>S3Part<-</code>, the replacement value for the S3 part of the object. </p> <p>For <code>S3Class<-</code>, the character vector that will be used as a proxy for <code>class(x)</code> in S3 method dispatch. </p> </td></tr> </table> <h3>Functions</h3> <p><code>S3Part</code>: Returns an object from the S3 class that appeared in the <code>contains=</code> argument to <code><a href="setClass.html">setClass</a></code>. </p> <p>If called with <code>strictS3 = TRUE</code>, <code>S3Part()</code> constructs the underlying S3 object by eliminating all the formally defined slots and turning off the S4 bit of the object. With <code>strictS3 = FALSE</code> the object returned is from the corresponding S4 class. For consistency and generality, <code>S3Part()</code> works also for classes that extend the basic vector, matrix and array classes. </p> <p>A call to is equivalent coercing the object to class <code>"S3"</code> for the strict case, or to whatever the specific S3 class was, for the non-strict case. The <code>as()</code> calls are usually easier for readers to understand. </p> <p><code>S3Class</code>: Returns the character vector of S3 class(es) stored in the object, if the class has the corresponding <code>.S3Class</code> slot. Currently, the function defaults to <code><a href="../../base/html/class.html">class</a></code> otherwise. </p> <p><code>isXS3Class</code>: Returns <code>TRUE</code> or <code>FALSE</code> according to whether the class defined by <code>ClassDef</code> extends S3 classes (specifically, whether it has the slot for holding the S3 class). </p> <p><code>slotsFromS3</code>: returns a list of the relevant slot classes, or an empty list for any other object. </p> <p>The function <code>slotsFromS3()</code> is a generic function used internally to access the slots associated with the S3 part of the object. Methods for this function are created automatically when <code><a href="setOldClass.html">setOldClass</a></code> is called with the <code>S4Class</code> argument. Usually, there is only one S3 slot, containing the S3 class, but the <code>S4Class</code> argument may provide additional slots, in the case that the S3 class has some guaranteed attributes that can be used as formal S4 slots. See the corresponding section in the documentation of <code><a href="setOldClass.html">setOldClass</a></code>. </p> <h3>Contained S3 Objects</h3> <p>Registering an S3 class defines an S4 class. Objects from this class are essentially identical in content to an object from the S3 class, except for two differences. The value returned by <code><a href="../../base/html/class.html">class</a>()</code> will always be a single string for the S4 object, and <code><a href="../../base/html/isS4.html">isS4</a>()</code> will return <code>TRUE</code> or <code>FALSE</code> in the two cases. See the example below. It is barely possible that some S3 code will not work with the S4 object; if so, use <code>as(x, "S3")</code>. </p> <p>Objects from a class that extends an S3 class will have some basic type and possibly some attributes. For an S3 class that has an equivalent S4 definition (e.g., <code>"data.frame"</code>), an extending S4 class will have a data part and slots. For other S3 classes (e.g., <code>"lm"</code>) an object from the extending S4 class will be some sort of basic type, nearly always a vector type (e.g., <code>"list"</code> for <code>"lm"</code>), but the data part will not have a formal definition. </p> <p>Registering an S3 class by a call to <code><a href="setOldClass.html">setOldClass</a></code> creates a class of the same name with a slot <code>".S3Class"</code> to hold the corresponding S3 vector of class strings. New S4 classes that extend such classes also have the same slot, set to the S3 class of the contained S3 <em>object</em>, which may be an (S3) subclass of the registered class. For example, an S4 class might contain the S3 class <code>"lm"</code>, but an object from the class might contain an object from class <code>"mlm"</code>, as in the <code>"xlm"</code>example below. </p> <p><span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> is somewhat arbitrary about what it treats as an S3 class: <code>"ts"</code> is, but <code>"matrix"</code> and <code>"array"</code> are not. For classes that extend those, assuming they contain an S3 class is incorrect and will cause some confusion—not usually disastrous, but the better strategy is to stick to the explicit “class”. Thus <code>as(x, "matrix")</code> rather than <code>as(x, "S3")</code> or <code>S3Part(x)</code>. </p> <h3>S3 and S4 Objects: Conversion Mechanisms</h3> <p>Objects in <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> have an internal bit that indicates whether or not to treat the object as coming from an S4 class. This bit is tested by <code><a href="../../base/html/isS4.html">isS4</a></code> and can be set on or off by <code><a href="../../base/html/isS4.html">asS4</a></code>. The latter function, however, does no checking or interpretation; you should only use it if you are very certain every detail has been handled correctly. </p> <p>As a friendlier alternative, methods have been defined for coercing to the virtual classes <code>"S3"</code> and <code>"S4"</code>. The expressions <code>as(object, "S3")</code> and <code>as(object, "S4")</code> return S3 and S4 objects, respectively. In addition, they attempt to do conversions in a valid way, and also check validity when coercing to S4. </p> <p>The expression <code>as(object, "S3")</code> can be used in two ways. For objects from one of the registered S3 classes, the expression will ensure that the class attribute is the full multi-string S3 class implied by <code>class(object)</code>. If the registered class has known attribute/slots, these will also be provided. </p> <p>Another use of <code>as(object, "S3")</code> is to take an S4 object and turn it into an S3 object with corresponding attributes. This is only meaningful with S4 classes that have a data part. If you want to operate on the object without invoking S4 methods, this conversion is usually the safest way. </p> <p>The expression <code>as(object, "S4")</code> will use the attributes in the object to create an object from the S4 definition of <code>class(object)</code>. This is a general mechanism to create partially defined version of S4 objects via S3 computations (not much different from invoking <code><a href="new.html">new</a></code> with corresponding arguments, but usable in this form even if the S4 object has an initialize method with different arguments). </p> <h3>References</h3> <p>Chambers, John M. (2016) <em>Extending R</em>, Chapman & Hall. (Chapters 9 and 10, particularly Section 10.8) </p> <h3>See Also</h3> <p><code><a href="setOldClass.html">setOldClass</a></code> </p> <h3>Examples</h3> <pre> ## an "mlm" object, regressing two variables on two others sepal <- as.matrix(datasets::iris[,c("Sepal.Width", "Sepal.Length")]) fit <- lm(sepal ~ Petal.Length + Petal.Width + Species, data = datasets::iris) class(fit) # S3 class: "mlm", "lm" ## a class that contains "mlm" myReg <- setClass("myReg", slots = c(title = "character"), contains = "mlm") fit2 <- myReg(fit, title = "Sepal Regression for iris data") fit2 # shows the inherited "mlm" object and the title identical(S3Part(fit2), as(fit2, "mlm")) class(as(fit2, "mlm")) # the S4 class, "mlm" class(as(fit2, "S3")) # the S3 class, c("mlm", "lm") ## An object may contain an S3 class from a subclass of that declared: xlm <- setClass("xlm", slots = c(eps = "numeric"), contains = "lm") xfit <- xlm(fit, eps = .Machine$double.eps) xfit@.S3Class # c("mlm", lm") </pre> <hr /><div style="text-align: center;">[Package <em>methods</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>