16 Appendix 3: R help files

Data Wrangling Recipes in R: Hilary Watt

Help files are routinely available in R, accessed as follows: for function “rnorm” – can be used any function.

help(rnorm)

?rnorm

The help file will open in a separate window and include:

  • Description - a short summary of what the function does.
  • Usage – shows syntax and available “arguments” (options), which are in brackets separated by commas.
  • Arguments – options/ arguments to be passed to the function. Skim for any that may be useful. Any with “= something” are optional, since the “=something” gives its default value.
  • Details - more detailed explanation about how to use the function.
  • References – to the methodology used within the function.
  • See Also – shows related functions
  • Examples - examples of practical use of function, often the most useful part of help file. It is useful to copy and paste this into console and run it, to further understand what the function can do and how to use it.

?hist gives the following at start of help file:

All arguments with default values (“= something” above) are optional. Therefore only argument x is required in above code for hist( ), which is specified first. This implies there is the need to name the variable whose distribution will be shown in the histogram, but no other options are required.

WARNING: R might often ignore “incorrect options”, without any warning. It takes attention to double check they have been implemented. Other times, it might report unused arguments.

Further example: The shows help file for function CrossTable. The first line indicates that this comes from package gmodels.

Above help file shows the possible arguments on this function. Nearly all have “equal something”, giving their default value, hence they do not need to be specified. However, x and y do not have default values, so must always be specified, whenever we use CrossTable. However, further details under argument indicate that, according to datatype, specifying one may be enough. Errors can be caused when datatype is not as per requirements.

Finding useful options: Read through the list of arguments to find ones you recognise or to look for specific things. Ignore ones that you don’t understand. The list is followed by more detail on the options. The art of reading help files is skimming quickly over what you don’t need/understand.

Examples: There is often code given for using the function in practice, running on data available within R. It may be very useful to look at this and run this code if you want to better understand what a function does. Copy and paste into the R script file and run, to help you understand the purpose and potential of the function.

VERY ADVANCED: Another feature of R functions is that you can see exactly the R code that is executed when you call the function simply by typing the function name into the console.

Data Wrangling Recipes in R: Hilary Watt. PCPH, Imperial College London.