1. Components of an R package
Welcome to this course on developing packages in R.
2. The power of R packages
R packages provide a way to share and reuse code across projects, whether across a business, with the rest of the R community, or wanting a structured way to develop code for ourselves.
This course will show the process of creating our own R packages, from basic package creation to writing comprehensive documentation and automated tests.
3. R package components
R packages commonly contain a variety of objects,
4. R package components
such as functions and data. Functions are stored in dot-R files in the R directory. Packages also include at least
5. R package components
two supporting files called DESCRIPTION and NAMESPACE.
The directory layout is an example of how these components could be structured into an R package called ourPackage. The R folder stores the functions in ourPackage, the supporting files are at the main level of the package, and data is stored in the data-raw and data folders or directories.
6. R package components
R packages can also include R Markdown templates stored in the inst directory. These help provide a structure for working with the package. R Markdown is a file format that combines R code and Markdown, a lightweight markup language, to create dynamic reports and documents.
7. R package components
Help documentation that typically includes examples of using individual functions is also a key component. These documentation files are stored in the man directory.
8. R package components
Dependable R packages also need unit tests. Unit tests are automated tests that check individual functions or pieces of code to ensure they produce the expected output under various conditions.
9. R package components
Moreover, it is best practice to include vignettes, which are long-form tutorials demonstrating how to use the package.
All of this is included in the package in a standardized structure, providing users with a reliable and well-organized way to access and use the package's content.
10. Core package functionality
Not everything is mandatory, though. R packages only need four essential components: an R directory, a man directory, a NAMESPACE file, and a DESCRIPTION file. Let's take a closer look at each.
11. R directory
The main purpose of the R directory is to house the package functions.
Each function or component of the package should have its own file.
In ourPackage, we might have functions that convert different units. These would be stored in the converter-dot-R file. We might also have a variety of smaller functions that we use throughout our analyses stored in the utils-dot-R file. It's best practice to include an R file with the package's name to help understand the package.
12. man directory
The man directory is short for manual.
It stores comprehensive documentation for a package's functions and objects, which users can easily access.
For ourPackage, the converter-dot-R file may contain two unit converting functions. temp_converter converts temperatures and distance_converter converts distances. Each of these has documentation stored in separate Rd files in man.
13. NAMESPACE
The NAMESPACE file contains vital information about functions and objects that our package imports from other packages and functions and objects that our package makes available to its users, ensuring seamless integration with other packages.
For ourPackage, we would like both distance_converter and temp_converter to be available to our package users. We may also want to import the tibble function from the tibble package for use in these functions. These are generated along with the documentation in the man folder using the roxygen2 package.
14. DESCRIPTION
The DESCRIPTION file contains essential package metadata. Metadata is data that provides information about other data.
For ourPackage, we have this example template DESCRIPTION, which can be updated to include any relevant information. Notice how the DESCRIPTION includes the package name, version, author, and dependencies.
15. Let's practice!
Time to test out your understanding!