Developing packages in RStudio

Intro

Why to write a package? Packages provide an easy way to share code with others or use it later, saving time by organizing the code and projects in standardized way.

Philosophy: anything that can be automated, should be automated.

Prerequisites: install.packages(c("devtools", "roxygen2", "testthat", "knitr"))

Basic workflow

1. create package either via devtools::create(path) or via RStudio–>new Project–>new R package

2. in case git should be used: devtools::use_git()

3. editing functions:

   1. usethis::use_r("functionname") to create a new function script, naming the file after the function. New .R-files for each user-facing function in the package. After adding more functions, these might be grouped.

   2. create roxygen2-skeleton to provide information and document functions via 'Ctrl + Alt + Shift + R'

   3. devtools::load_all() to load the created functions under R/ subdirectory

   4. usethis::use_package() to include functions from other packages (adding them to the Imports field of DESCRIPTION). The function can be used via packagename::fun()

   5. (git-commit after editing a function)

   6. devtools::rename_files("old_name", "new_name") to update the function name in files –> Don’t forget to update test-files, too!

4. check that an R package is in full working order with devtools::check() or 'Ctrl + Shift + E', providing a convenient way to run this without leaving the R session

5. create testing infrastructure via usethis::use_testthat()

   1. usethis::use_test("function_name") to create a test-file for a specific function

   2. devtools::test() or 'Ctrl + Shift + T' to run test

6. pick license, e.g. via usethis::use_mit_license(), creating LICENSE and LICENSE.md-files

7. create and update documentation via devtools::document()

8. use_readme_rmd() initializes a basic, executable README.Rmd file for the github page to describe the purpose of the package, providing installation instructions, and showing a bit of usage. build_readme() renders the file

9. Installation: devtools::check() again, then install package into library via devtools::install()

10. Publish: devtools::build()converts package folder/project into single bundled file

Structure

Recommended folder structure for packages (Posit Software, 2024)

• DESCRIPTION provides metadata about the package

• NAMESPACE declares the functions the package exports for external use and the external functions your package imports from other packages. is automatically edited when using roxygen2

• .Rbuildignore lists files that are needed to be around but should not be included when building the R package from source

• .Rproj.user - directory used internally by RStudio

• .gitignore anticipates Git usage and tells Git to ignore some standard, behind-the-scenes files created by R and RStudio

• tests/ directory in which the testing framework is placed, containing specific tests for the functions

Main functions during development

These functions setup parts of the package and are typically called once per package:

• create_package()

• use_git()

• use_mit_license()

• use_testthat()

• use_github()

• use_readme_rmd()

These functions are called on a regular basis, as adding functions and tests or taking on dependencies:

• use_r()

• use_test()

• use_package()

These functions are called multiple times per day or per hour, during development:

• load_all()

• document()

• test()

• check()

Main shortcuts

• Ctrl + Shift + T - run devtools::test()

• Ctrl + Shift + E - run devtools::check()

• Ctrl + Shift + Alt + R - create roxygen2 skeleton

Package states

• source - directory of files with specific package structure

• bundled - compressed into single file using extension .tar.gz

• binary - single platform-specific file

• installed - binary package that’s been compressed into a package library

• in-memory - package loaded into memory

Methods for converting between package states (Wickham & Bryan 2023)

more info

Writing R Extensions (r-project.org)

R packages book (2e)