2024-09-01
When you want help with writing R code for data manipulation, statistical analyses or visualisation you might turn to various text books, blog posts, articles, internet searches or copy-and-paste from Stack Overflow or LLM output and cross your fingers. Package authors, however, have already written something just for you - the package user - to understand and use the functions in their package.
Run ?somefunction or help("somefunction")
and you’ll be greeted with the help file for the function. In RStudio,
this opens in the ‘Help’ pane. These help files give details about the
function including how to use it, what the arguments mean and their
default values, what the function will return and more. There are some
standard sections you will find in these help files:
Description: A brief description of what the function does.
Usage: Code showing how the function is called, its arguments and their default values.
Arguments: A list of the arguments of the function.
Value: A description of what is returned by the function.
Examples: Some examples of using the function.
You might also find sections like:
Details: Further details about the function.
References: References for relevant papers e.g. describing statistical methods.
See Also: links to help files for related functions.
Any other sections that the author has decided to include. For
example, in the help file for a ggplot2 layer like
geom_point() you’ll find a section called
Aesthetics which describes the aesthetic mappings that
can be used in that layer.
A manual (in PDF or webpage form) containing a package’s help documentation can be found on its CRAN or R-universe (if the package is on R-universe) page.
Vignettes are longer documentation for a package. These can describe how to use and combine functions, recommend a workflow for using a package and provide further details.
Use browseVignettes("packagename") to browse the
available vignettes for a package. Vignettes can also be found on a
package’s CRAN or
R-universe (under
‘articles’) page.
Packages often have a website (created using {pkgdown} or otherwise) showing the function help files, vignettes/articles and possibly further documentation. Some packages may have multiple websites (for example, the targets package has both a documentation website made with pkgdown and a manual).
Groups of packages that are designed to work together or built around the same theme (a ‘-verse’) might also have an overarching website (e.g. the website for the officeverse packages).
These two documents can be found from a package’s CRAN/R-universe page or website. The README gives an overall introduction to the package, while NEWS describes changes to the package over time. The NEWS page can be useful if your code stops working or produces different output after you update a package to a newer version.
The Journal of Statistical
Software and other journals publish papers about software including
R packages. Methodology papers may also have related packages. These
papers can provide further background and details about a package. Links
to relevant papers can hopefully be found from the package documentation
such as in the citation information which can be found using
citation("packagename").
For more about R package documentation from the authoring side of things see the relevant chapters of ‘R Packages’.