I'm new to R and having a hard time piecing together information from various sources online related to what is considered a "good" practice with writing R code. I've read basic guides but I've been having a hard time finding information that is definitely up to date.
What are some examples of well written/documented S3 classes?
How about corresponding S4 classes?
What conventions do you use when commenting .R classes/functions? Do you put all of your comments in both .Rd files and .R files? Is synchronization of these files tiresome?
Whether to use S3, S4, or a package at all is mostly a style issue (as Dirk says), but I would suggest using one of those if you want to have a very well structured object (just as you would in any OOP language). For instance, all the time series classes have time series objects (I believe that they're all S3 with the exception of its) because it allows them to enforce certain behavior around the construction and usage of those objects. Similarly with the question about creating a package: it's a good idea to do this if you will be re-using your code frequently or if the code will be useful to someone else. It requires a little more effort, but the added organizational structure can easily make up for the cost.
Regarding S3 vs. S4 (discussed on R-Help here and here), the basic guideline is that S3 classes are more "quick and dirty" while S4 classes place more rigid control over objects and types. If you're working on Bioconductor, you typically will use S4 (see, for instance, "S4 classes and methods").
I would recommend reading some of the following:
"A (Not So) Short Introduction to S4" by Christophe Genolini
"Programmers' niche: A simple class, in S3 and S4" by Thomas Lumley
"Brobdingnag: a ''hello world'' package using S4 methods" by Robin K. S. Hankin
"Converting packages to S4" by Douglas Bates
"How S4 Methods Work" by John Chambers
For documentation, Hadley's suggestion is spot on: Roxygen will make life easier and puts the documentation right next to the code. That aside, you may still want to provide other comments in your code beyond what Roxygen or the man files require, in which case it's a good practice to comment your code for other developers. Those comments will not end up in your package; they will only be visible in the source code.
For 3. Use roxygen - it works like javadoc to take comments in your source files and build Rd files.
That's half a dozen or more questions bundled into one, which makes it difficult to answer.
So let's try from the inside out: First try to solve your RODBC wrapper problem. A code representation will suggest itself. I would start with simple functions, and then maybe build a package around it. That already gives you some encapsulation.
Much of the rest is style. Some prominent R codes swear by S4, while other swear about it. You can always read the packages of others as well as code in R itself. And you can always re-implement your RODBC wrapper in different ways and the compare your own approaches.
Edit: Reflecting you updated and much shortened question: Pick some packages from CRAN, in particular among those you use. I think you will quickly find some more or less interesting according to your style.
somewhat more style related than substance, but the Google R style guide is worth reading:
Related
I'm in the process of creating a small R package containing a set of functions that should be useful in a specialized area of Biology. I currently have the package on GitHub, but want to submit it to CRAN soon. One thing I have noticed when digging around in other packages, is that the code often includes no comments at all (e.g. short comments describing what different parts of the code does), which makes it more difficult to understand. I'm not a programmer or expert in R, so I don't understand why comments are often not included, and Hadley Wickham's "R packages" book makes not mention of this.
Edit: I'm not referring to the object documentation, that one accesses with ?function(), but to comments that are interspersed within the function code, which a normal user wouldn't see, but that could be helpful for people trying to figure out exactly how a function works.
Is there a specific reason to not include comments within the functions of an R package? If so, should I remove all the comments from my code before submitting to CRAN?
I'm looking for some kind of references which explain the pro's en con's of using Rcpp when compared to using rdyncall.
Can someone who has used both explain the basic differences from an R package developers perspective who is interested in providing R wrappers to C++ code.
Thanks.
I think we mention rdyncall in the (brief) comparison to other approaches the intro vignette / JSS paper. It is a neat package, but aims for a much lower-level connection. As I understand it, it gives you C-level APIs with least amount of fuzz, as motivated by say, the rgl package. there is very good and detailed paper about rdyncall in a recent R Journal issue.
And unless I miss something, it does nothing for you on the C++ side. Whereas Rcpp makes use as .Call() to pass complete R objects back and forth, and manages to map a wide variety of R and C++ types automatically for you---with the possibility add your own mappers.
I'm in the process of documenting some of my functions for an R package I'm making.
I'm using roxygen markup, though that is largely irrelevant to my question.
I have put equations into my documentation using \deqn{...}. My question is:
Is there a way to cross-reference this equation later on?
For example, in my Rd file:
\deqn{\label{test}
y = mx + b
}
Can I later do something like:
Referring to equation \ref{test}, ...
I've tried \eqref{test}, \ref{test} (which both get "unknown macro" and don't get linked ), and also \link{test} (which complains it can't find function test because it's really just for linking to other functions).
Otherwise I fear I may have to do something hacky and add in the -- (1) and Refer to equation (1) manually within the \deqn etc in the Rd file...
Update
General answer appears to be "no". (awww...)
However, I can write a vignette and use "normal" latex/packages there. In any case, I've just noticed that the matrix equations I spent ages putting into my roxygen/Rd file look awful in the ?myFunction version of the help (they show up as just-about literal latex source). Which is a shame, because they look beautiful in the pdf version of the help.
#Iterator has pointed out the existence of conditional text, so I'll do ASCII maths in the .Rd files, but Latex maths in the pdf manual/vignette.
I'm compiling my comments above into an answer, for the benefit of others.
First, I do not actually know whether or not .Rd supports tagging of equations. However, the .Rd format is such a strict subset of LaTeX, and produces very primitive text output, that shoehorning extensive equations into its format could be a painful undertaking without much benefit to the user.
The alternative is to use package vignettes, or even externally hosted documentation (as is done by Hadley Wickham, for some of his packages). This will allow you to use PDFs or other documentation, to your heart's content. In this way, you can include screenshots, plots, all of the funkiest LaTeX extensions that only you have, and, most significantly, the AMS extensions that we all know and love.
Nonetheless, one can specify different rendering of a given section of documentation (in .Rd) based on the interface, such as text for the console, nice characters for HTML, etc., and conditional text supports that kind of format variation.
It's a good question. I don't know the answer regarding feasibility, but I had similar questions about documenting functions and equations together, and this investigation into what's feasible with .Rd files has convinced me to use PDF vignettes rather than .Rd files.
Which R packages make good use of S4 classes? I'm looking for packages that use S4 appropriately (i.e. when the complexity of the underlying problem demands), are well written and well documented (so you can read the code and understand what's going on).
I'm interested because I'll be teaching S4 soon and I'd like to point students to good examples in practice so they can read the code to help them learn.
Thinking about this some more, maybe Matrix and/or lme4? Matrix does a lot of trickery with efficient representation of sparse matrices so this may be a worthwhile (though possibly heavy) example.
Else, given that all of BioConductor is done in S4, some of it is bound to be better than average :) I am sure Martin Morgan will pipe in with good examples.
This doesn't exactly answer your question, but....
R in a Nutshell develops an S4 class for a timeseries object and then compares it to the S3 representation. It's a very nice illustration (without being overly complex or too simple) of the differences between S3 and S4.
R programming for Bioinformatics briefly discusses the ExpressionSet set object.
In regards with using the Bioconductor packages, you might find that to fully appreciate the code - or even just to get started - you will have to a reasonable knowledge of biology. I suppose the same applies to complex statistics packages; you need to have a vague idea of what's going on to understand the reasons behind the code structure.
At the last LondonR meeting Brandon Whicher gave a fascinating talk about the use of S4 classes in his package dcemriS4, for use in analysing magnetic resonance imaging (MRI) in medical research.
His talk is available here:
http://www.londonr.org/Medical%20Image%20Analysis%20using%20S4%20classes%20&%20methods.pdf
And the package is on CRAN:
http://star-www.st-andrews.ac.uk/cran/web/packages/dcemriS4/index.html
sp and dependent packages use S4 and well documented. Alpha and omega for spatial stuff in R.
I would go for kernlab, which additionally includes a lot of C code.
It comes with an handy vignette, detailing some of S4 concepts. (It doesn't seem to use roxygen for the documentation, though, but this is not the question here.)
Trying to get a hold of the S4 system I ran across an educational package sequence. The implementation of the class system is illustrated in an accompanying set of slides in a repo roo by the same author. Though the example used is from biostatistics, it's good to follow.
It is a great learning resource, because the author took carefully contrasted the different object systems while at the same time keeping the complexity of the package adequate for learning.
How do people learn about giving an R package a namespace? I find the documention in "R Extensions" fine, but I don't really get what is happening when a variable is imported or exported - I need a dummy's guide to these directives.
How do you decide what is exported? Is it just everything that really shouldn't required the pkg:::var syntax? What about imports?
Do imports make it easier to ensure that your use of other package functions doesn't get confused when function names overlap?
Are there special considerations for S4 classes?
Packages that I'm familiar with that use namespaces such as sp and rgdal are quite complicated - are there simple examples that could make things clearer?
I have a start on an answer on the devtools wiki: https://r-pkgs.org/Metadata.html
Few years later here....
I consolidated findings from Chambers, other StackOverflow posts, and lots of tinkering in R:
https://blog.thatbuthow.com/how-r-searches-and-finds-stuff/
This is less about implementing NAMESPACE/IMPORTS/DEPENDS and more about the purpose of these structures. Answers some of your questions.
The clearest explanation I've read is in John Chambers' Software for Data Analysis: Programming with R, page 103. I don't know of any free online explanations that are better than what you've already found in the R Extensions manual.
You could also pick an easy, small package and follow it.
I semi-randomly looked at digest which is one of my smaller packages. I loads a (small) dynamic library and exports one symbol, the digest() function. Here is the content of the NAMESPACE file:
## package has dynamic library
useDynLib(digest)
## and one and only one core function
export(digest)
Have a look at the rest of the source files and maybe try to read Writing R Extensions alongside looking at the example, and do some experiments.
http://www.stat.uiowa.edu/~luke/R/namespaces/morenames.pdf