RPR-Help

Getting help for R

 

Keywords:  The internal R help system; other help resources.

 

 

 

Abstract

This unit discusses the available Help resources for R programming and develops effective strategies for solving problems.

 

This unit ...

Prerequisites

You need to complete the following units before beginning this one:

• RPR-Installation (Installing R and RStudio)

 

Objectives

This unit will ...

• ... introduce the inbuilt R help system;
• ... point you to useful alternatives;
• ... discuss how to write effective questions on technical forums and mailing lists.

 

Outcomes

After working through this unit you ...

• ... have used the R help system;
• ... are able to get help on a function:
  • via R's internal system,
  • via Web searches, or
  • by asking effective questions (including Minimal Working Examples - MWE) on mailing lists.

 

Deliverables

• Time management: Before you begin, estimate how long it will take you to complete this unit. Then, record in your course journal: the number of hours you estimated, the number of hours you worked on the unit, and the amount of time that passed between start and completion of this unit.
• Journal: Document your progress in your Course Journal. Some tasks may ask you to include specific items in your journal. Don't overlook these.
• Insights: If you find something particularly noteworthy about this unit, make a note in your insights! page.

 

Contents

The Help system

Task:

• Start RStudio (if it's not already open) and as you work through the sections below, type the commands and explore what they do.

If all you need is the correct name of a function (eg. was it list_files(), list.files(), or listFiles()?), just type the first three characters of the function name and use RStudio's autocomplete mechanism to find what you need.

If you are wondering about the parameters of a function, just hover the cursor over the function name in the script pane or the console and wait a moment: a little window with the function signature will pop up.

But for more detailed information, help is available for all commands as well as for the R syntax. As well, help is available to find the names of commands when you are not sure of them. You can get help through the command line, or from a search field in the Help tab of the lower-right pane.

(help() is a function in R, arguments to a function are passed in parentheses "()")

> help(rnorm)
>

(shorthand for the same thing)

> ?rnorm
>

(what was the name of that again ... ?)

> ?binom
No documentation for 'binom' in specified packages and libraries:
you could try '??binom'
> ??binom
>

(I see "Binomial" in the list of keywords...)

> ?Binomial
>

(Alternatively: use the apropos() function.

> ?apropos
> apropos("med")   # all functions that contain the string "med"
> apropos("^med")  # all functions that begin with the string
> apropos("med$")  # all functions that end with the string

If you need help on operators, place them in quotation marks. Try:

> ?"+"
> ?"~"
> ?"["
> ?"%in%"
>

That's all fine, but you will soon notice that R's help documentation is not all that helpful for newcomers (who need the most help). To illustrate, open the help window for the function var().

> ?var

Here's what you might look for.

• The Description section describes the function in general technical terms.
• The Usage section tells you what arguments are required (these don't have defaults), what arguments have defaults, and what the defaults are, and whether additional arguments ("...") are allowed. Often a function comes in several variants, you will find them here.
• The Arguments section provides detailed information . You should read it, especially regarding whether the arguments are single values, vectors, or other objects, and what effect missing arguments will have.
• The Details section might provide common usage and context information. It might also not. Often functions have crucial information buried in an innocuous note here.
• You really have to read and understand the Value section. It explains the output of the function (its returnvalue). The object a function returns could be a list, a matrix or something else (we'll discuss these data types in detail elsewhere.). The value could also be an object that has special methods defined e.g. for plotting it. In that case, the object is formally a "list", and its named "components" can be retrieved with the usual list syntax.

If you look at the bottom of the help text, you will usually find examples of the function's usage; these sometimes make matters more clear than the terse and principled help-text above.

What you often won't find:

• Clear commented, examples that relate to the most frequent use cases.
• Explanations why a particular function is done in a particular way (e.g. why the denominator is n-1 for sd() and var()).
• Notes on common errors.
• A (reasonably) exhaustive list of alternatives and related functions. There are usually some entries, but there is no guarantee that all alternatives are listed – especially if they are provided by an external package.

Therefore, my first approach for R information is usually to Google for what interests me and this is often the quickest way to find working example code. R has a very large user base and it is becoming very rare that a reasonable question will not have a reasonable answer among the top three hits of a Google search. Also, as a result of a Google search, it may turn out that something can't be done (easily) – and you won't find things that can't be done in the help system at all. You may want to include "r language" in your search terms, although Google is usually pretty good at figuring out what kind of "r" you are looking for, especially if your query includes a few terms vaguely related to statistics or programming.

• There is an active R-help mailing list to which you can post–or at least search the archives: your question probably has been asked and answered before. A number of SIGs (Special Interest Groups) exist for more specific discussions - e.g. for mac OS, geography, ecology etc. They are listed here.

• Most of the good responses these days are on stack overflow, discussion seems to be shifting to there from the R mailing list. Information on statistics questions can often be found or obtained from the CrossValidated forum of stackexchange.
  • try this sample search on stackOverflow...
  • try this sample search on CrossValidated...

• Rseek is a specialized Google search on R-related sites. Try "time series analysis" for an example.

• The bioconductor project has its own support site on the Web.

If you want a quick and constructive answer from the R mailing list or stackoverflow, you must do a bit of homework first. If you ask your question well, you will get incredibly insightful and helpful responses, but you need to help the helpers help you:

• Use the dput() function, perhaps combined with head() to create a small, reproducible dataset with which your problem can be reproduced or your question illustrated. Keep this as small as possible. Post that. Don't post screenshots!
• Post minimal code that reproduces the problem with the data you have supplied. Together the code and data have to form an MWE – a minimal working example. People love to play with your code and get it to work, but they hate having to copy, paste, reformat or otherwise edit someone's stuff just so they can answer their question.
• Don't waste too much time on explaining what you did (since that didn't work) - just enough to help your readers understand that you did indeed invest some effort in trying to solve the problem yourself, but explain clearly what you want to achieve. Focus on the desired result - not on how to fix your algorithm; your algorithm may be the wrong mental model in the first place.
• Don't post in HTML, be sure to post in plain text only.

Task:

• Read "How to write a reproducible example" and "How to make a great R reproducible example".

BTW: the same principles apply to questions you post on the course mailing list.

 

 

Further reading, links and resources

 

Notes

 

Self-evaluation

Question 1

Is the apropos() command case-sensitive?

Answer ...

Try it out:

apropos("^med")
apropos("^MED")

 

 

 

---

 

If in doubt, ask! If anything about this learning unit is not clear to you, do not proceed blindly but ask for clarification. Post your question on the course mailing list: others are likely to have similar problems. Or send an email to your instructor.

---

 

About ...
 
Author:

Boris Steipe <boris.steipe@utoronto.ca>

Created:

2017-08-05

Modified:

2017-09-09

Version:

1.0

Version history:

• 1.0 Completed to first live version
• 0.1 Material collected from previous tutorial

---

This copyrighted material is licensed under a Creative Commons Attribution 4.0 International License. Follow the link to learn more.