S4 classes in R: printing function definition and getting help

I’m not very familiar with S4 classes and methods, but I assume it’s the recommended way to write new packages since it is newer than S3; this of course is open to debate. I’ll outline my experience of programming with S4 classes and methods in a later post, but in the mean time, I want to write down some notes on how to get help (via ? in R) and getting function definitions from S4 methods.

For S3 classes and methods, suppose I want to learn more about a certain method, say print of some class. Let’s use class lm as an example. I could type ?print.lm to get documentation on the function, and type print.lm in the R console to get the function definition printed. This allows me to learn more about the method and learn from them (perks of open source!). To recap:

 <pre class="src src-sh"><span style="color: #ff4500;">## </span><span style="color: #ff4500;">S3</span>

?generic.class ## get help to the generic function “generic” of a particular class “class” generic.class ## print the function in console

However, with S4, this is not the class. I’ve used a few packages that are written in S4 and could not get documentation open within R and get the function definitions printed to learn about the underlying code based on the previous techniques. As I learn to write and document an R package based on S4, I read this section of the R manual for writing packages. I misinterpreted the reading and thought to get help on a method I had to type something like methods?generic,signature_list-method to get help. However, I received an error due to the - symbol (it’s an operator in R). I believe the stated convention is just for the documentation piece of S4 methods in the .Rd files. After some more searching, I came across this link (examples section) that showed me how to get help. Let’s illustrate with the show method (S4’s equivalent of the print method) for the mer class in the lme4 package.

 <pre class="src src-sh"><span style="color: #ff4500;">## </span><span style="color: #ff4500;">S4</span>

showMethods(“show”) ## show all methods for show ?show ## shows the generic documentation of show method?show(“mer”) ## method?generic(“signature 1″, “signature 2″, …) — get help for the generic function for a particular signature list, usually a single class getMethod(“show”, signature=“mer”) ## function definition lme4:::printMer ## printMer is what the show method for mer calls

For our particular example, the show method for the mer class calls a printMer function in the lme4 namespace. Thus, we need to call lme4:::printMer to see the definition.

Hope this out others out there.

About Vinh Nguyen

Statistician

1 comment

  1. I’m not very familiar with S4 classes and methods, but I assume it’s the recommended way to write new packages since it is newer than S3; this of course is open to debate.

    And to open the debate, I’ll quote from Google’s R Style guide:

    Objects and Methods The S language has two object systems, S3 and S4, both of which are available in R. S3 methods are more interactive and flexible, whereas S4 methods are more formal and rigorous. (For an illustration of the two systems, see Thomas Lumley’s “Programmer’s Niche: A Simple Class, in S3 and S4″ in R News 4/1, 2004, pgs. 33 – 36: http://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf.) Use S3 objects and methods unless there is a strong reason to use S4 objects or methods. A primary justification for an S4 object would be to use objects directly in C++ code. A primary justification for an S4 generic/method would be to dispatch on two arguments.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>