Getting started with R package vignettes
1. Getting started with R package vignettes
Time to explore vignettes.2. R package structure
Though not mandatory, it is best practice to include these in an R package.3. Purpose of vignettes in R Package documentation
In R package development, a vignette is an R Markdown document that shows how to use the package's functionality. Vignettes play a crucial role in R package documentation by providing detailed explanations, showcasing practical examples, and giving comprehensive tutorials for using the package's functionality.4. Vignette best practices
Vignettes should deliver information in a concise manner, avoiding unnecessary details. By organizing the vignette into sections or subsections with clear headings, users can easily find the information they need. Text should be provided above R code examples to motivate the problem, then R code showing package functionality, and text after as needed discussing results. This ensures a logical flow of topics and facilitates navigation. Providing engaging examples and use cases allows users to understand the package's functionality in real-world scenarios.5. Browsing an R Package Vignette
It can be helpful to review the vignettes of other well-documented packages to understand how to construct our own. The browseVignettes function in the preloaded utils package provides a guide for doing just that. Its first argument is a string of the name of the package to review. We choose dplyr. This function opens a web browser to a local webpage, allowing us to navigate through the available vignettes within the package.6. Browsing an R Package Vignette
Focus on the "Introduction to dplyr" row and the HTML option. If we click on HTML,7. HTML version of a vignette
we get another webpage. We see that the vignette starts with why the dplyr package is helpful and also what data will be used throughout the vignette examples.8. source version of a vignette
The webpage was generated using R Markdown. We can see the source code of the R Markdown file by clicking on source in the vignettes main page.9. source version of a vignette
We now see the familiar R Markdown layout of text and R chunks of code to be run. Let's zoom in on the top section of it.10. source version of a vignette YAML header
The top portion contains metadata on the title, output, description, and properties of the vignette in YAML format. VignetteIndexEntry is what will appear as the title on the vignettes webpage. knitr::rmarkdown as VignetteEngine specifies that the rmarkdown package, which is built on top of knitr, is used as the engine to render the vignette content. The last line specifies that the vignette source code is encoded in UTF-8, which is a widely supported character encoding system.11. Vignette metadata
Metadata is data about the data, such as the file name and location of this cat picture. The YAML header metadata information contains four main pieces. The title of the vignette serves as a concise summary of its content. The output section specifies the type of output that will be generated when the vignette is rendered. This can include HTML, PDF, or other formats, giving the user several options. rmarkdown-colon-colon-html_vignette is a common choice. The description provides a brief overview of the vignette's content as a paragraph. It should give readers a clear idea of what they can expect to learn or achieve by reading the vignette. The vignette section includes additional metadata related to the vignette. Entries start with percent-backslash. We will focus on vignette composition before writing our own in the next video.12. Vignettes versus articles
Now that we've discussed the metadata, let's take a step back and explore the concept of vignettes in more detail. While vignettes serve as valuable resources within a package, it's important to note that they differ from traditional articles. Sometimes people confuse vignettes as being peer-reviewed since they can have the style of academic writing and explanations of code, but they usually aren't. A vignette primarily focuses on package-specific functionality, providing hands-on examples and demonstrations of how to use the package effectively. Vignettes are typically included as part of the package documentation. An article covers broader topics or research, presenting findings or insights that may or may not be directly related to the package. Articles are often published separately from the package.13. Let's practice!
Let's practice!Create Your Free Account
or
By continuing, you accept our Terms of Use, our Privacy Policy and that your data is stored in the USA.