R package Engineering Workflow

RSE
Rpkg

Notes on the appropriate workflow in R packages

Author

Chi Zhang

Published

October 2, 2023

Useful references:

Steps suggested:

  1. Idea
  2. Design docs
  3. R package programming
  4. QC (Quality check)
  5. Publication
  6. Use in production

Step 2: Design docs

Purpose and scope: the package pkg_name shall …

Package requirements:

library(gt)
df <- data.frame(obligation = c('Duty', 'Desire', 'Intension'), 
                 keyword = c('shall', 'should', 'will'), 
                 description = c('must have', 'nice to have', 'optional'))

gt(df) |> 
  cols_label(obligation = md('**Obligation**'), 
             keyword = md('**Key word**'), 
             description = md('**Description**'))
Obligation Key word Description
Duty shall must have
Desire should nice to have
Intension will optional

Use some documentation tools (md, qmd, or diagram draw.io)

Step 3: packaging

  1. create basic project
  2. Copy and paste exisint R scripts, refactor if necessary (i.e. give self-explanatory names)
  3. Create R generic functions (print, summary)
  4. Document
To do
  • return result as a list, with class attribute
  • return argument

Step 4: Qualiy code

It is important to have clean code, so that it is easier to read and maintain; easier to exntend; and the code runs faster.

  • naming. Make the function and argument names easy to understand
  • formatting. Indentation, spacing, bracketing should be consistent
  • simplicity. Avoid unnecesary complexity. Split large source files into smaller chunks, preferably less than 1000 lines.
  • single responsibility principle (SRP). Each function should have ONE single purpose.
  • don’t repeat yourself. Make a function!
  • comment.
  • error handling. Include error handling messages. tryCatch()
To do
  • Error handling.

Testing

Why do you need unit tests? In short, increase reliability and maintainability of the code.

Other types of tests exist: integration testing, performance testing, snapshot testing. Package testthat allows not only unit tests, but also the other types of tests.

Note

A more comprehensive guide see my other note: R package: tests

Test coverage: use covr. Ideally should cover 100%.

Package quality check

R CMD Check

Code style

Use tidyverse style guide.

  • styler: restyle text, files or entire project.
  • lintr: perform automated checks to confirm that our code conform to the style guide.
  • devtools::spell_check.

Step 5. Publication

pkgdown website might be the most useful place.

Versioning

  • x.y.z
  • x is major, breaking changes
  • y is minor, new features
  • z is patch, bug fixes
  • try usethis::use_version()

Adding badges

# lifecycle
usethis::use_lifecycle_badge(stage = 'experimental')
# R-CMD-check 
usethis::use_github_action_check_standard()