Home > R > Improving base-R examples

Improving base-R examples

Earlier today I saw the hundred bazillionth question about how to use the paste function. My initial response was “take a look at example(paste) to see how it works”.

Then I looked at example(paste), and it turns out that it’s not very good at all. There isn’t even an example of how to use the collapse argument. Considering that paste is one of the first functions that beginners come across, as well as being a little bit tricky (getting to understand the difference between the sep and collapse arguments takes a bit of thinking about when you are new), this seems like a big oversight.

I’ve submitted this as a bug, with a suggested improvement to the examples. Fingers crossed that R-core will accept the update, or something like it.

It got me thinking though, how many other base functions could do with better examples? I had a quick look at some common functions that beginners seems to get confused with, and the following all have fairly bad example sections:
In base: browser, get, seq
In stats: formula, lm, runif, t.test
In graphics: plot
In utils: download.file, read.table

If you have half an hour spare, have a go at writing a better example page for one of these functions, or any other function in the base distribution, then submit it to the bug tracker. (If you aren’t sure that your examples are good enough, or you need advice, try posting what you have on r-devel before submitting a bug report. Dealing with bug reports takes up valuable R-core time, so you need to be sure of quality first.)

This seems like a really easy way to make R more accessible for beginners.

  1. 25th November, 2014 at 14:06 pm

    Should new R user perhaps learn to use packages stringtr for this purpose from the very first day?

    • 25th November, 2014 at 18:58 pm

      str_c in the stringr package is similar but not identical to paste, and since paste is so universally used, I don’t think you can avoid learning it if you are serious about R programming.

  2. crazybilly
    25th November, 2014 at 17:20 pm

    As a beginner who finds many examples utterly opaque, thanks so much for pointing this out! Well said.

  3. 26th November, 2014 at 8:14 am

    Very good point!

  4. 26th November, 2014 at 10:24 am

    hear hear. Many examples jump straight in with tricky edge-cases that are fun for mathematicians but forget to do the A, B, and C first

  5. 26th November, 2014 at 13:47 pm

    Richie, I am interested in gathering the most common error messages that Base R functions produce — the kinds of core functions you properly and usefully suggest for improved examples. If someone would team with me to compile and explain them, with examples, what mechanism would there be to make them available to beginners?

  6. Mat
    27th November, 2014 at 19:20 pm

    Good point! R help files are in general hard to read, and in many cases, more examples would not harm!

  7. 2nd December, 2014 at 17:59 pm

    I agree completely. Many of the R help files feel like they are written for people who already understand the command and want to learn about extreme cases.

  1. 24th December, 2014 at 12:44 pm
  2. 15th January, 2015 at 13:01 pm

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: