Week 4: Package Basics

Stat 431

In this short module, we will learn about the structure of R Packages.


Time Estimates:
     Videos: 0 min
     Readings: 10 min
     Activities: 15 min
     Check-ins: 8



Extra Resources:

Basics of Packages

In principle, an R Package is nothing more than a folder with a very specific structure, which allows R to recognize it as a “Package”. Minimally, to be a package, a folder must contain:

  1. A subfolder named /R/, containing .R code files.
  2. A text file named DESCRIPTION, which contains information about the package in a very specifically formatted way.
  3. A text file named NAMESPACE, which contains a list of the functions that the package makes available.

(If you’re thinking to yourself, “Boy, that sounds like a lot of annoyingly specific formatting!” - you’re not wrong. Fortunately, there are automatic ways to make these files, which we will learn about in the next module.)

Any folder with that structure can, in principle, be installed into R as a package. Typically, you will be installing packages from one of three sources:

1. install.packages("something")

If you are able to install a package directly using install.packages(), that means the package has been accepted to the Comprehensive R Archive Network, or CRAN.

The minimal folder structure is not sufficient to be accepted to CRAN; these packages must meet many strict guidelines about documenting and testing the package’s functions.

2. install_github("username/something")

You may have come across packages you wanted to use that could only be installed using the install_github function (from the remotes or devtools package).

In principle, anyone can put a package-structured folder on GitHub, and if the repository is public, anyone else can install that package.

In practice, it’s good to have your package meet CRAN-like levels of careful documentation before you share it with the public.

3. Installing from your personal sources

If you use R heavily in the future, you may find it useful to write packages just for yourself. For example, if you find yourself using the same small “helper” functions over and over, it can be nice to simply load a package rather than re-run them for every project.

We won’t worry about installing from sources for this class.


Check-In 1: Basic Package Structure


Visit this GitHub repository, where our good friend Regina George has made a package.

Answer the following questions about Regina’s package by clicking around in her files.

  1. What is the name of this package?
  2. Besides Regina, who is listed as an author of this package?
  3. Which other packages does Regina’s package depend on? (Hint: Which packages does this one import?)
  4. Which functions are defined in the file insults.R?
  5. In the documentation comments above the functions, what does @param indicate?
  6. In the documentation comments above the functions, what does @importFrom do?
  7. Look at the functions defined in the file give_candygrams.R. One of them does NOT appear in the NAMESPACE file. What is different about the documentation comments for this function?
  8. Why do you think Regina decided not to include the function from Q7 in her namespace?

Canvas Link