R Help-Files?!

What to do if you get lost in R?

Before you start: function calls, arguments and returned values.
Setup: Use R or RStudio to open ?read.table; no input file is needed to read the help.
Your check: Find what a function accepts and returns in its help page. Practise in the unit summary.

Open a help page

Enter ?read.table or help("read.table") in the Console. RStudio opens the documentation in its Help pane. You can also use the official online help for read.table(); prefer the installed help for details specific to your R version.

The R Syntax lesson uses this function with a supplied file and explains its arguments. If you arrived directly here, that lesson also supplies the project setup. You can read the help without downloading the file.

A quick route through the help

The heading identifies read.table and its package, utils; Data Input is the title. Several functions share this help page, including read.csv() and read.csv2(). Locate the read.table entry in Usage.

Section Question it answers
Description What does the function do? Here it reads tabular data into a data frame.
Usage How can I call it? Look for argument names, their order and default values.
Arguments What does each input mean, and which values are accepted? Connect file, header and sep to the syntax example.
Value What does the function return? Here it returns the imported data frame.
Details, Note or Warning Which special rules or limitations affect my use?
Examples What can I inspect and adapt? Check the inputs and comments before running the code.

Start with Description, connect Usage to Arguments, and check Value. Use Details for questions those sections leave open. The illustrated guide below also shows References and See Also; sections can vary between functions.

Defaults are starting settings

In Usage, skip = 0 specifies a parameter and its default value: when you omit skip, this function starts without skipping lines. dec = "." means decimal points; sep = "" means separation by whitespace, such as spaces or tabs. A parameter such as file has no default shown: the local-file call needs you to supply its value.

Check the argument description as well. Although Usage shows header = FALSE, read.table() can infer a header for some file layouts. Set header explicitly when you know whether your file has column names. The syntax lesson’s comma-separated file needs header = TRUE and sep = ","; you do not need to supply every other input listed in Usage.

In the entries for read.csv() and read.csv2(), ... indicates that additional arguments can be passed to read.table(). Supply the actual named arguments you need, such as skip = 4. The dots are documentation notation here, not text to copy into an import call.

Guided view of the help page

Now that you know how to access the built-in R help pages you need to know how to read them. Typically, the R Help files follow a fairly standard outline as seen below in a heavily clipped screenshot of the function read.table. Different functions might have different sections, but these are the main ones you should be aware of:

read.table help page showing the package, title, description and usage signature; these sections are explained alongside. Package Name:
The package to which the function belongs (in grey).

Title:
The name of the function and its purpose.

Description:
An extended description of what the function does.

Usage:
A description of the syntax of the function. This is where all the arguments can be found that can be supplied to the function, as well as any default values of these arguments.

Arguments section of read.table help, listing argument names and their meanings. Arguments:
A description of each argument.

Usually this includes a specification of the class (character, numeric, list, etc.).

This section is an important one to understand, because arguments are frequently a cause of errors in R.


















Value section of read.table help: the result is a data frame representing the file contents. Value:
A description of the class of the value returned by the function.






Memory usage notes in read.table help, including the cost of storing imported columns. Other comments:
Other comments worth mentioning.











Details section of read.table help describing how columns are read and converted. Details:
This section provides more details about how the function works, including the various ways to call it and a longer discussion of its arguments.





References section of read.table help, citing the underlying statistical-computing literature. References:
References underlying the implementation or use of the function.

See Also section of read.table help with related import functions and documentation. See also:
Links to other relevant functions that can be read.





Examples section of read.table help with runnable import code. Examples:
Worked examples of real R code that can be pasted into the R console and run.










Summary

  • Title: name of the function.
  • Description: a short description of what the function does.
  • Usage: the syntax of the function.
  • Arguments: the description of the arguments taken by the function.
  • Value: the value returned by the function
  • Examples: provide examples on how to use the function

Try reading the help yourself

Use ?read.table to answer these questions in your own words:

  1. Which argument skips introductory lines, and what is its default?
  2. Which argument limits the number of data rows read? What does its default mean?
  3. What kind of object does the function return? Which operator would you use to store it under the name trees?
Suggested answers
  1. skip controls how many initial lines are skipped. Its default is 0, so reading starts at the beginning of the file.
  2. nrows sets the maximum number of data rows. Its default, -1, places no row limit; nrows = 2 reads at most two data rows after any skipped lines and header.
  3. It returns a data frame. Use trees <- read.table(...), replacing ... with the actual arguments needed by your file. The arrow assigns the returned value; the equals signs inside the call connect argument names to their supplied values.

Ready to continue: you can find an argument’s meaning and default, choose settings for a file, and identify the returned object. Practise changing the supplied import in R Syntax, or use the Unit 01 summary to check your first saved script.

Updated: