13 Create an `R` package

Creating an R package can be done in a few easy steps. Making an R package is a great way to share your code with others and organize your analysis workflow. In this chapter, we will go through the step-by-step process of creating an R package.

Code

library(devtools)
library(usethis)

Code

usethis::create_package("~/Documents/GitHub/MyExamplePackage")
usethis::use_mit_license("Your Name Here")
usethis::use_readme_md()
usethis::use_pkgdown()
usethis::use_testthat()

This R code will create a new R package in the directory “~/Documents/GitHub/MyExamplePackage” and add some basic files and structures to it, including:

usethis::create_package("~/Documents/GitHub/MyExamplePackage"): This creates a new R package in the specified directory by creating a new subdirectory with the name of the package and adding some basic files and folders, such as DESCRIPTION, NAMESPACE, man, R, and tests. The package will have the name “MyExamplePackage”.
usethis::use_mit_license("Your Name Here"): This adds a MIT license file to the package with the specified author name. The MIT license is a permissive open-source license that allows others to use, modify, and distribute the software. Note that there are other options for licenses that you may want to consider depending on your intended use case.
usethis::use_readme_md(): This creates a README.md file in the package root directory. The README.md file is a markdown file that provides an overview of the package, including a description, installation instructions, and basic usage examples.
usethis::use_pkgdown(): This adds a docs/ directory to the package and configures it to use pkgdown, a tool for creating web-based documentation for R packages. The docs/ directory will contain the package documentation in HTML format.
usethis::use_testthat(): This adds the testthat package to the Imports field in the DESCRIPTION file and creates a tests/ directory in the package with some example test files. The testthat package is a popular testing framework for R packages and is used to ensure that the package functions correctly and consistently.

13.1 Package Dependencies

Code

usethis::use_package("ggplot2", type = "Imports", min_version = TRUE)

There are various options for the type option including:

Depends is used to indicate that your package depends on another package in order to work properly. When you include a package in the Depends field, it is attached automatically when your package is loaded. This means that the functions and datasets from the dependent package are available without having to use the :: operator. For example, if your package depends on the dplyr package, you would include dplyr in the Depends field of your DESCRIPTION file.
Imports is used for packages that are needed by your package but that don’t need to be loaded with library(). Packages referred to in @import or @importFrom statements in your Roxygen2 comments, or whose functions are accessed via the :: operator, should be here. For example, if your package requires the ggplot2 package, you would include ggplot2 in the Imports field of your DESCRIPTION file.
Suggests is for packages that aren’t really necessary, but that you’re using in your examples, vignettes, or tests. Any package listed in Imports will need to be installed with your package, while packages listed in Suggests do not need to be installed with your package. For example, if your package suggests the caret package, you would include caret in the Suggests field of your DESCRIPTION file.
Enhances is used to indicate that your package provides additional functionality when certain packages are installed. These packages are not required for the package to work properly, but they can enhance its functionality. When a package is listed in the Enhances field, it is attached automatically when your package is loaded. For example, if your package enhances the ggplot2 package, you would include ggplot2 in the Enhances field of your DESCRIPTION file.
LinkingTo is used to indicate that your package uses external resources, such as C or C++ libraries, that are not available in R. When a package is listed in the LinkingTo field, it is linked to your package during installation. For example, if your package uses a C++ library called mylib, you would include mylib in the LinkingTo field of your DESCRIPTION file.

Code

tidyverse_packages <- c('tibble','readr','dplyr','tidyr',
                        'stringr','purrr','ggplot2','forcats')

tidyverse_friends <- c('broom','lubridate','readxl',
                       'knitr','shiny','furrr','flexdashboard',
                       'yardstick')

other_packages <- c('devtools','rsq','arsenal','skimr',
                    'RSQLite','dbplyr','plotly','DT','GGally','corrr',
                    'AMR','caret','shiny','DataExplorer','randomForest',
                    'usethis','testthat','pkgdown')

purrr::walk(c(tidyverse_packages, tidyverse_friends, other_packages),
            function(package){
              usethis::use_package(package, "Imports", min_version = TRUE)
              }
            )

13.2 Package Functions

You can do this by creating R scripts in the R/ directory of your package. Each function should be defined in its own R script.

For example, let’s say you want to create a function that adds two numbers together. You can create an R script called add.R in the R/ directory of your package, and define the function in that script:

Code

#' Add two numbers
#'
#' @param x A number
#' @param y A number
#'
#' @return The sum of x and y
add <- function(x, y) {
  x + y
}

The documentation for your function should be written in Roxygen2 syntax, which is a convenient way to generate documentation for your package.

13.2.1 What is `Roxygen2`?

Roxygen2 is a popular package in R that is used to document R code. The official reference manual for Roxygen2 is available on the CRAN website, which is the Comprehensive R Archive Network. The reference manual provides detailed information on how to use Roxygen2 to document R code, including a description of the syntax for Roxygen2 comments and a list of all the available tags.

The Roxygen2 reference manual is available at the following link: https://cran.r-project.org/web/packages/roxygen2/roxygen2.pdf

The manual includes the following sections:

Introduction: This section provides an overview of Roxygen2 and its purpose.
Writing documentation: This section covers the basics of writing documentation using Roxygen2 comments.
Roxygen syntax: This section provides a detailed description of the syntax for Roxygen2 comments.
Tags: This section includes a list of all the available tags in Roxygen2 and their descriptions.
Examples: This section provides examples of how to use Roxygen2 to document R code.
Advanced topics: This section covers advanced topics such as using Roxygen2 with S4 methods, debugging Roxygen2 comments, and using Roxygen2 with C++ code.

Overall, the Roxygen2 reference manual is a comprehensive resource for learning how to use Roxygen2 to document R code. It provides detailed information on the syntax and available tags, as well as examples and advanced topics for more experienced users.

13.3 How to Organize and Run Your Tests

We should have a folder named R with all the R code, and one folder named tests/testthat, where all the test scripts will live. For each file with R scripts there should be another one with tests, with the same name, but prefixed by test-, as shown:

It’s important to test your functions to make sure they work as expected. You can do this by creating tests for your functions in the tests/ directory of your package.

To create a test for our add() function above, we can create a file called test-add.R in the tests/ directory, and define the test in that file:

Code

test_that("add() function works", {
  expect_equal(add(1, 2), 3)
})

This test uses the testthat package to check that the add() function returns the correct value. Above the expect_equal is checking to see if 1+2 = 3 in our function.

As you might expect you might want to include some specific examples or edge-cases that you are currently iterating on with the application of the functions within the testing environment.

If you have a function my_function.R as one of your package functions if you want to create a test you need a file test-my_function.R as a corresponding test file.

13.4 Create Package

After defining your package functions and tests, you can build your package using the devtools package:

Code

devtools::load_all()
devtools::document()
devtools::install()

this will:

devtools::load_all(): This function is used to load the package into the R environment. It is typically used during development to test the package and make sure that everything is working as expected.
devtools::document(): This function is used to update the package documentation based on the code in the package. It generates the man/ directory containing documentation files for each function or dataset in the package, based on the roxygen2 comments in the package code.
devtools::install(): This function is used to install the package in the R environment. It compiles and installs the package, making it available for use in R. The package is installed in the user’s default library directory, or in a specified directory if one is provided.

Taken together, these three functions are used to build and install the R package, making it available for use within the current R environment. Before running these functions, the package must have been created, and all necessary files, including the DESCRIPTION file and package code, should be in place. These functions are often used during the package development process, as they allow us to quickly update and test the package without having to manually rebuild and reinstall the package each time.

Code

detach(package:MyExamplePackage)

13.5 Build package site

pkgdown::build_site() is a function in R that is used to build a website for an R package. The website is built using the pkgdown package, which is a tool for generating static HTML documentation for R packages. Some advantages of using pkgdown::build_site() to build a website for your R package include:

Professional documentation: pkgdown generates professional-looking documentation for your R package. The website includes information about the package, such as its purpose, installation instructions, and usage examples. The documentation is also easy to navigate, making it more user-friendly.
User-friendly layout: The website generated by pkgdown is user-friendly and easy to navigate. The package documentation is organized into sections, making it easy to find the information you are looking for.
Automatic updates: pkgdown::build_site() can be set up to automatically update the website whenever changes are made to the package. This ensures that the documentation is always up-to-date and accurate.
Customizable templates: The pkgdown package allows you to customize the templates used to generate the website, making it possible to create a website that matches your branding and style.
Enhanced discoverability: By making your package’s documentation available through a website, you can enhance its discoverability. Users can find your package more easily through search engines or by browsing online resources, making it more likely that your package will be used and cited by others.

Using pkgdown::build_site() to build a website for your R package can enhance its discoverability, make its documentation more professional and user-friendly, and provide automatic updates, all of which can be beneficial for both users and developers.

Note that you do not need to publish the HTML generated for your package if you are creating it for internal use, to prevent pkgdown from automatically publishing your website online, you should not configure the package to use GitHub Pages or any other web hosting platform. You can also make sure that the generated HTML files are not pushed to any public repositories or shared publicly.

For additional details we refer you to (Wickham 2015) and (Wickham 2019).

# Create an `R` package {#sec-create-R-package} Creating an `R` package can be done in a few easy steps. Making an `R` package is a great way to share your code with others and organize your analysis workflow. In this chapter, we will go through the step-by-step process of creating an `R` package. ```{r, eval=FALSE} library(devtools) library(usethis) ``` ```{r echo=TRUE, eval=FALSE} usethis::create_package("~/Documents/GitHub/MyExamplePackage") usethis::use_mit_license("Your Name Here") usethis::use_readme_md() usethis::use_pkgdown() usethis::use_testthat() ``` This `R` code will create a new R package in the directory "\~/Documents/GitHub/MyExamplePackage" and add some basic files and structures to it, including: - `usethis::create_package("~/Documents/GitHub/MyExamplePackage")`: This creates a new `R` package in the specified directory by creating a new subdirectory with the name of the package and adding some basic files and folders, such as `DESCRIPTION`, `NAMESPACE`, `man`, `R`, and `tests`. The package will have the name "MyExamplePackage". - `usethis::use_mit_license("Your Name Here")`: This adds a MIT license file to the package with the specified author name. The MIT license is a permissive open-source license that allows others to use, modify, and distribute the software. Note that there are other options for licenses that you may want to consider depending on your intended use case. - `usethis::use_readme_md()`: This creates a README.md file in the package root directory. The `README.md` file is a markdown file that provides an overview of the package, including a description, installation instructions, and basic usage examples. - `usethis::use_pkgdown()`: This adds a `docs/` directory to the package and configures it to use pkgdown, a tool for creating web-based documentation for R packages. The `docs/` directory will contain the package documentation in HTML format. - `usethis::use_testthat()`: This adds the testthat package to the `Imports` field in the `DESCRIPTION` file and creates a `tests/` directory in the package with some example test files. The `testthat` package is a popular testing framework for `R` packages and is used to ensure that the package functions correctly and consistently. ## Package Dependencies ```{r} #| eval: false usethis::use_package("ggplot2", type = "Imports", min_version = TRUE) ``` There are various options for the `type` option including: - **Depends** is used to indicate that your package depends on another package in order to work properly. When you include a package in the `Depends` field, it is attached automatically when your package is loaded. This means that the functions and datasets from the dependent package are available without having to use the `::` operator. For example, if your package depends on the `dplyr` package, you would include `dplyr` in the `Depends` field of your `DESCRIPTION` file. - **Imports** is used for packages that are needed by your package but that don't need to be loaded with `library()`. Packages referred to in `@import` or `@importFrom` statements in your Roxygen2 comments, or whose functions are accessed via the `::` operator, should be here. For example, if your package requires the `ggplot2` package, you would include `ggplot2` in the `Imports` field of your `DESCRIPTION` file. - **Suggests** is for packages that aren't really necessary, but that you're using in your examples, vignettes, or tests. Any package listed in `Imports` will need to be installed with your package, while packages listed in `Suggests` do not need to be installed with your package. For example, if your package suggests the `caret` package, you would include `caret` in the `Suggests` field of your `DESCRIPTION` file. - **Enhances** is used to indicate that your package provides additional functionality when certain packages are installed. These packages are not required for the package to work properly, but they can enhance its functionality. When a package is listed in the `Enhances` field, it is attached automatically when your package is loaded. For example, if your package enhances the `ggplot2` package, you would include `ggplot2` in the `Enhances` field of your `DESCRIPTION` file. - **LinkingTo** is used to indicate that your package uses external resources, such as C or C++ libraries, that are not available in `R`. When a package is listed in the `LinkingTo` field, it is linked to your package during installation. For example, if your package uses a C++ library called `mylib`, you would include `mylib` in the `LinkingTo` field of your `DESCRIPTION` file. ```{r, eval=FALSE} tidyverse_packages <- c('tibble','readr','dplyr','tidyr', 'stringr','purrr','ggplot2','forcats') tidyverse_friends <- c('broom','lubridate','readxl', 'knitr','shiny','furrr','flexdashboard', 'yardstick') other_packages <- c('devtools','rsq','arsenal','skimr', 'RSQLite','dbplyr','plotly','DT','GGally','corrr', 'AMR','caret','shiny','DataExplorer','randomForest', 'usethis','testthat','pkgdown') purrr::walk(c(tidyverse_packages, tidyverse_friends, other_packages), function(package){ usethis::use_package(package, "Imports", min_version = TRUE) } ) ``` ## Package Functions You can do this by creating R scripts in the `R/` directory of your package. Each function should be defined in its own `R` script. For example, let's say you want to create a function that adds two numbers together. You can create an `R` script called `add.R` in the `R/` directory of your package, and define the function in that script: ```{r, eval=FALSE} #' Add two numbers #' #' @param x A number #' @param y A number #' #' @return The sum of x and y add <- function(x, y) { x + y } ``` The documentation for your function should be written in `Roxygen2` syntax, which is a convenient way to generate documentation for your package. ### What is `Roxygen2`? `Roxygen2` is a popular package in `R` that is used to document `R` code. The official reference manual for `Roxygen2` is available on the CRAN website, which is the Comprehensive `R` Archive Network. The reference manual provides detailed information on how to use Roxygen2 to document `R` code, including a description of the syntax for `Roxygen2` comments and a list of all the available tags. The Roxygen2 reference manual is available at the following link: <https://cran.r-project.org/web/packages/roxygen2/roxygen2.pdf> The manual includes the following sections: 1. Introduction: This section provides an overview of Roxygen2 and its purpose. 2. Writing documentation: This section covers the basics of writing documentation using Roxygen2 comments. 3. Roxygen syntax: This section provides a detailed description of the syntax for Roxygen2 comments. 4. Tags: This section includes a list of all the available tags in Roxygen2 and their descriptions. 5. Examples: This section provides examples of how to use Roxygen2 to document R code. 6. Advanced topics: This section covers advanced topics such as using `Roxygen2` with S4 methods, debugging `Roxygen2` comments, and using `Roxygen2` with C++ code. Overall, the `Roxygen2` reference manual is a comprehensive resource for learning how to use `Roxygen2` to document `R` code. It provides detailed information on the syntax and available tags, as well as examples and advanced topics for more experienced users. ## How to Organize and Run Your Tests We should have a folder named `R` with all the `R` code, and one folder named `tests/testthat`, where all the test scripts will live. For each file with R scripts there should be another one with `tests`, with the same name, but prefixed by `test-`, as shown: It's important to test your functions to make sure they work as expected. You can do this by creating tests for your functions in the `tests/` directory of your package. To create a test for our `add()` function above, we can create a file called `test-add.R` in the `tests/` directory, and define the test in that file: ```{r, eval=FALSE} test_that("add() function works", { expect_equal(add(1, 2), 3) }) ``` This test uses the `testthat` package to check that the `add()` function returns the correct value. Above the `expect_equal` is checking to see if `1+2 = 3` in our function. As you might expect you might want to include some specific examples or edge-cases that you are currently iterating on with the application of the functions within the testing environment. If you have a function `my_function.R` as one of your package functions if you want to create a test you need a file `test-my_function.R` as a corresponding test file. ## Create Package After defining your package functions and tests, you can build your package using the `devtools` package: ```{r , eval=FALSE} devtools::load_all() devtools::document() devtools::install() ``` this will: - `devtools::load_all()`: This function is used to load the package into the R environment. It is typically used during development to test the package and make sure that everything is working as expected. - `devtools::document()`: This function is used to update the package documentation based on the code in the package. It generates the man/ directory containing documentation files for each function or dataset in the package, based on the roxygen2 comments in the package code. - `devtools::install()`: This function is used to install the package in the R environment. It compiles and installs the package, making it available for use in R. The package is installed in the user's default library directory, or in a specified directory if one is provided. Taken together, these three functions are used to build and install the `R` package, making it available for use within the current `R` environment. Before running these functions, the package must have been created, and all necessary files, including the `DESCRIPTION` file and package code, should be in place. These functions are often used during the package development process, as they allow us to quickly update and test the package without having to manually rebuild and reinstall the package each time. ```{r, eval=FALSE} detach(package:MyExamplePackage) ``` ## Build package site `pkgdown::build_site()` is a function in `R` that is used to build a website for an `R` package. The website is built using the `pkgdown` package, which is a tool for generating static HTML documentation for `R` packages. Some advantages of using `pkgdown::build_site()` to build a website for your `R` package include: - Professional documentation: `pkgdown` generates professional-looking documentation for your `R` package. The website includes information about the package, such as its purpose, installation instructions, and usage examples. The documentation is also easy to navigate, making it more user-friendly. - User-friendly layout: The website generated by pkgdown is user-friendly and easy to navigate. The package documentation is organized into sections, making it easy to find the information you are looking for. - Automatic updates: `pkgdown::build_site()` can be set up to automatically update the website whenever changes are made to the package. This ensures that the documentation is always up-to-date and accurate. - Customizable templates: The `pkgdown` package allows you to customize the templates used to generate the website, making it possible to create a website that matches your branding and style. - Enhanced discoverability: By making your package's documentation available through a website, you can enhance its discoverability. Users can find your package more easily through search engines or by browsing online resources, making it more likely that your package will be used and cited by others. Using `pkgdown::build_site()` to build a website for your `R` package can enhance its discoverability, make its documentation more professional and user-friendly, and provide automatic updates, all of which can be beneficial for both users and developers. Note that you do not need to publish the HTML generated for your package if you are creating it for internal use, to prevent `pkgdown` from automatically publishing your website online, you should not configure the package to use GitHub Pages or any other web hosting platform. You can also make sure that the generated HTML files are not pushed to any public repositories or shared publicly. For additional details we refer you to [@Wickham2015-zr] and [@Wickham2019-yn].

13.1 Package Dependencies

13.2 Package Functions

13.2.1 What is Roxygen2?

13.3 How to Organize and Run Your Tests

13.4 Create Package

13.5 Build package site

13.2.1 What is `Roxygen2`?