R: Mailing Lists Posting Guide

Posting Guide: How to ask good questions that prompt useful answers

This guide is intended to help you get the most out of the R mailing lists, and to avoid embarrassment. Like many responses posted on the list, it is written in a concise manner. This is not intended to be unfriendly - it is more a consequence of allocating limited time and space to technical issues rather than to social niceties.

The list: Remember that R is free software, constructed and maintained by volunteers. They have various reasons for contributing software and participating on the mailing lists, but often have limited time.

Good manners: Remember that customs differ. Some people are very direct. Others surround everything they say with hedges and apologies. Be tolerant. Rudeness is never warranted, but sometimes `read the manual' is the appropriate response. Don't waste time discussing such matters on the list. Ad hominem comments are absolutely out of place.

Questions about statistics: The R mailing lists are primarily intended for questions and discussion about the R software. However, questions about statistical methodology are sometimes posted. If the question is well-asked and of interest to someone on the list, it may elicit an informative up-to-date answer. See also the Usenet groups sci.stat.consult (applied statistics and consulting) and sci.stat.math (mathematical stat and probability).

Basic statistics and classroom homework: R-help is not intended for these.

Which list: R-help or R-devel? There are two widely used mailing list for questions and discussion about R. R-help is intended to be comprehensible to people who want to use R to solve problems but who are not necessarily interested in or knowledgeable about programming. R-devel is intended for questions and discussion about code development in R. Questions likely to prompt discussion unintelligible to non-programmers should go to to R-devel. For example, questions involving C, C++, etc. code should go to R-devel. More general questions involving pure R code and questions likely to be of interest to the large and diverse set of subscribers to R-help should go to R-help.

Do your homework before posting: If it is clear that you have done basic background research, you are far more likely to get an informative response. See also Further Resources further down this page.

Do help.search("keyword") with different keywords (type this at the R prompt)
Read the online help for relevant functions (type ?functionname, e.g., ?prod, at the R prompt)
If something seems to have changed in R, look in the latest NEWS file on CRAN for information about it.
Search the R-faq and the R-windows-faq if it might be relevant (http://cran.r-project.org/faqs.html)
Read at least the relevant section in An Introduction to R
If the function is from a package accompanying a book, e.g., the MASS package, consult the book before posting

Technical details of posting: See General Instructions for more details of the following:

No HTML posting (harder to detect spam)
No binary attachments except for PS, PDF, and some image and archive formats (others are automatically stripped off because they can contain malicious software). Files in other formats and larger ones should rather be put on the web and have only their URLs posted. This way a reader has the option to download them or not.
Use an informative subject line (not something like `question')
For new subjects, compose a new message and include the 'r-help@lists.R-project.org' (or 'r-devel@lists.R-project.org') address specifically. (Replying to an existing post and then changing the subject messes up the threading in the archives and in many people's mail readers.)
If you can't send from an email address that simply accepts replies, then say so in your posting so that people are not inconvenienced when they try to respond to your message

Surprising behavior and bugs: What you think is a bug may be many other things, such as a default behavior that you do not like, a feature, an undocumented feature, or a bug in the documentation. You do not need to commit yourself to one of these in order to ask a question. If it is a real bug, someone will notice it. Before you post a real bug report, make sure you read R Bugs in the R-faq. If you're not completely and utterly sure something is a bug, post a question to r-help, not a bug report to r-bugs - every bug report requires manual action by one of the R-core members. Also, see Simon Tatham's essay on How to Report Bugs Effectively.

For questions about unexpected behavior or a possible bug provide details about your platform (Windows2000, Linux, OS X) and R version (type version at the R prompt). State the full version number, e.g., `1.8.1', not just `1.8'. State whether you installed a pre-compiled binary version of R or compiled it yourself. If the function is in a package other than `base', include the header output from library(help=thatPackage). If you are using an old version of R and think it does not work properly, upgrade.

For questions about functions in standard packages distributed with R (see the FAQ Add-on packages in R), ask questions on R-help. If the question relates to a package that is downloaded from CRAN try contacting the package maintainers first. You can also use find("functionname") and package.description("packagename") to find this information.

Don't say `R crashed', which you may take to mean that R gave an error and terminated your piece of code, but most people will take to mean abnormal termination of the R program. Say exactly what happened, including any error messages you received.

Examples: Sometimes it helps to provide a small example that someone can actually run. For example:

  If I have a matrix x as follows:
  > x <- matrix(1:8, nrow=4, ncol=2,
                dimnames=list(c("A","B","C","D"), c("x","y"))
  > x
    x y
  A 1 5
  B 2 6
  C 3 7
  D 4 8
  >
  how can I turn it into a dataframe with 8 rows, and three
  columns named `row', `col', and `value', which have the
  dimension names as the values of `row' and `col', like this:
  > x.df
     row col value
  1    A   x      1
   ...
  (To which the answer might be:
  > x.df <- reshape(data.frame(row=rownames(x), x), direction="long",
                    varying=list(colnames(x)), times=colnames(x),
                    v.names="value", timevar="col", idvar="row")
  )

When providing examples, it is best to give an R command that constructs the data, as in the matrix() expression above. For more complicated data structures, dump("x", file=stdout()) will print an expression that will recreate the object x.

Further resources: not always consulting these before posting is OK, except perhaps if you have a very general question and the topic of the document indicates immediate relevancy. A response might just point you towards one of these.

Writing R Extensions covers packages, to and from C & C++, R help files.
R Data Import/Export covers reading from and exporting to other file formats
R Language Definition (aka `R Language Manual') describes the R language, data objects, etc.
The article `R Help Desk' by Uwe Ligges in the R Newsletter Vol 3 No 1 has useful tips about where to find information about R.
Two books are often cited in answers to questions: Venables & Ripley, 2002, Modern Applied Statistics with S (4th ed) ("MASS") and Pinheiro & Bates, 2000 (about lme in particular). If you can get these books, look at them. If you cannot, you might indicate this in your question. Further books relevant to R are listed at Publications.
The Contributed Documentation page lists a number of useful introductory and other documents available online.
The R-help archives (see under `Archives and Search Facilities' at http://www.r-project.org/mail.html)
Paul Johnson's R tips page is a organized collection of how to do things in R, with many questions and tips culled from R-help.
A Google search of the web in general or the r-project site specifically (put `site:r-project.org' at the beginning of the search terms)

Responding to other posts:

In general, respond to the list, not just the poster. This will result in your response being archived.
Rudeness and ad hominem comments are not acceptable. Brevity is OK.
When responding to a very simple question, use the following algorithm:
1. compose your response
2. type 4*runif(1) at the R prompt, and wait this many hours
3. check for new posts to R-help; if no similar suggestion, post your response
(This is partly in jest, but if you know immediately why it is suggested, you probably should use it! Also, it's a nice idea to replace 4 by the number of years you have been using R or S-plus.)

Common posting mistakes:

Missing or non-specific message subject
Not doing basic homework before posting a question
Not being more specific than `function xxx doesn't work'
Being overly specific and not stating your real goal.
Not including version and OS information in question regarding unexpected behavior.
Finding a bug in an old version of R that has been fixed in the most recent version.
Claiming that something is a bug when in fact the software is working as intended and documented, just not in the way you first expected.
Claiming that some commonly used function is not behaving in a sensible manner (if you find the behavior odd, it's more productive and polite to ask why it behaves the way it does - after reading the relevant documentation.)
Threatening not to use the software if you cannot get your question answered. Even when intended as a statement of fact, this tends to create negative attitudes.

Final words: It is a skill to ask good questions. If at first you don't get the answers that are useful to you, don't get discouraged. A response that is concise and technically accurate may be just that, and not an intended putdown. If you feel insulted by some response to a post of yours, don't make any hasty response in return - you're as likely as not to regret it. Read Eric Raymond's essay How To Ask Questions The Smart Way for more suggestions, and for insight into people's behavior on technical mailing lists (but don't try asking people at catb.org questions about R).

Compiled by Tony Plate (tplate at acm dot org), Dec 2003