3 An R Package Engineering Workflow

openstatsware short course: Good Software Engineering Practice for R Packages

Friedrich Pahlke

April 18, 2024

Motivation

From an idea to a production-grade R package

Example scenario: in your daily work, you notice that you need certain one-off scripts again and again.

The idea of creating an R package was born because you understood that “copy and paste” R scripts is inefficient, and on top of that, you want to share your helpful R functions with colleagues and the world…

Professional Workflow

Photo CC0 by ELEVATE on pexels.com

Typical work steps

  1. Idea
  2. Concept creation
  3. Validation planning
  4. Specification:
    1. User Requirements Spec (URS),
    2. Functional Spec (FS), and
    3. Software Design Spec (SDS)
    4. Test Plan (TP)
  1. R package programming
  2. Documented verification
  3. Completion of formal validation
  4. R package release
  5. Use in production
  6. Maintenance

Extensive documentation, huge paperwork, lots of manual work, lots of signatures, …

Workflow in Practice

Photo CC0 by Chevanon Photography on pexels.com

Frequently Used Workflow in Practice

  1. Idea
  2. R package programming
  3. Use in production
  4. Bug fixing
  5. Use in production
  1. Bug fixing + Documentation
  2. Use in production
  3. Bug fixing + Further development
  4. Use in production
  5. Bug fixing + …

Bad practice!

Why?

Why practice good engineering?

Cost distribution among software process activities

doi:10.14569/IJACSA.2020.0110375

Why practice good engineering?

Origin of errors in system development

Boehm, B. (1981). Software Engineering Economics. Prentice Hall.

Why practice good engineering?

  • Minimise maintenance in all lifecycles
  • Be faster with release on CRAN
  • Organised code makes collaboration better
  • Fulfill regulatory requirements1
  • Save refactoring time when the Proof-of-Concept (PoC) becomes the release version
  • You don’t have to be shy any longer about inviting other developers to contribute to the package on GitHub

Why practice good engineering?

Invest time in

  • requirements analysis,
  • software design, and
  • architecture…

… but in many cases the workflow must be workable for a single developer or a small team.

Workable Workflow

Photo CC0 by Kateryna Babaieva on pexels.com

Suggestion for a Workable Workflow

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

Example - Step 1: Idea

Let’s assume that you used some lines of code to create simulated data in multiple projects:

dat <- data.frame(
    group = c(rep(1, 50), rep(2, 50)),
    values = c(
        rnorm(n = 50, mean = 8, sd = 12),
        rnorm(n = 50, mean = 14, sd = 11)
    )
)

Idea: put the code into a package

Example - Step 2: Design docs

  1. Describe the purpose and scope of the package
  2. Analyse and describe the requirements in clear and simple terms (“prose”)
Obligation level Key word1 Description
Duty must2 “must have”
Desire should “nice to have”
Intention may “optional”

Example - Step 2: Design docs

Purpose and Scope

The R package simulatr is intended to enable the creation of reproducible fake data.

Package Requirements

simulatr must provide a function to generate normal distributed random data for two independent groups. The function must allow flexible definition of sample size per group, mean per group, standard deviation per group. The reproducibility of the simulated data must be ensured via an optional seed. It should be possible to print the function result. The package may also facilitate graphical presentation of the simulated data.

Example - Step 2: Design docs

Useful formats / tools for design docs:

UML Diagram

Example - Step 3: Packaging

R package programming

  1. Create basic package project (see R Packages)
  2. C&P existing R scripts (one-off scripts, prototype functions) and refactor1 it if necessary
  3. Create R generic functions
  4. Document all functions

Example - Step 3: Packaging

One-off script as starting point:

sim.data <- function(n1, n2, m1, m2, s1, s2) {
    data.frame(
        group = c(rep(1, n1), rep(2, n2)),
        values = c(
            rnorm(n = n1, mean = m1, sd = s1),
            rnorm(n = n2, mean = m2, sd = s2)
        )
    )
}

Example - Step 3: Packaging

Refactored script:

getSimulatedTwoArmMeans <- function(n1, n2, mean1, mean2, sd1, sd2) {
    data.frame(
        group = c(rep(1, n1), rep(2, n2)),
        values = c(
            rnorm(n = n1, mean = mean1, sd = sd1),
            rnorm(n = n2, mean = mean2, sd = sd2)
        )
    )
}

Almost all functions, arguments, and objects should be self-explanatory due to their names.

Example - Step 3: Packaging

Define that the result is a list1 which is defined as class2:

getSimulatedTwoArmMeans <- function(n1, n2, mean1, mean2, sd1, sd2) {
    result <- list(n1 = n1, n2 = n2, 
         mean1 = mean1, mean2 = mean2, sd1 = sd1, sd2 = sd2)
    result$data <- data.frame(
        group = c(rep(1, n1), rep(2, n2)),
        values = c(
            rnorm(n = n1, mean = mean1, sd = sd1),
            rnorm(n = n2, mean = mean2, sd = sd2)
        )
    )
    # set the class attribute
    result <- structure(result, class = "SimulationResult")
    return(result)
}

Example - Step 3: Packaging

The output is impractical, e.g., we need to scroll down:

x <- getSimulatedTwoArmMeans(n1 = 50, n2 = 50, mean1 = 5, mean2 = 7, sd1 = 3, sd2 = 4)
x
$n1
[1] 50

$n2
[1] 50

$mean1
[1] 5

$mean2
[1] 7

$sd1
[1] 3

$sd2
[1] 4

$data
    group      values
1       1  6.92867501
2       1  4.27391191
3       1  4.84314168
4       1  6.47817838
5       1  4.33260826
6       1 -1.72191316
7       1  1.08203633
8       1  8.53507748
9       1  8.37867780
10      1  0.22530345
11      1  7.78210236
12      1  2.76337884
13      1  2.93471488
14      1 -0.34749376
15      1  7.27127205
16      1  1.57398466
17      1  5.99260926
18      1  6.87531114
19      1  5.27240331
20      1  7.82986314
21      1  7.24441602
22      1  4.24178078
23      1  4.86116603
24      1  3.43215595
25      1  2.73368044
26      1  4.66923585
27      1  6.76589371
28      1  7.64264403
29      1  0.40013825
30      1  2.22943563
31      1  2.09145210
32      1  8.10204547
33      1  5.80126515
34      1  0.29625804
35      1  4.23228594
36      1  2.47750708
37      1  5.13579141
38      1  9.21317431
39      1  2.41292737
40      1 10.56468496
41      1  6.86999664
42      1  8.34405572
43      1  6.86696222
44      1  8.71159940
45      1  3.23705137
46      1  6.30270645
47      1 -1.81965445
48      1  8.18732195
49      1  1.68561040
50      1  5.69022559
51      2  2.70545804
52      2  4.38127493
53      2  9.36388417
54      2  5.98904517
55      2  3.29543590
56      2  4.26433021
57      2  0.15160899
58      2  2.00679650
59      2 11.02430692
60      2  7.43707591
61      2  0.05354151
62      2  7.02388432
63      2  1.27704771
64      2  6.51298834
65      2  6.95702116
66      2 24.56328828
67      2  8.45460558
68      2  3.47935357
69      2  2.64644833
70      2  0.41833657
71      2  0.10432563
72      2 10.09086912
73      2  3.16091651
74      2 16.26886162
75      2  0.31918042
76      2 13.26124234
77      2  8.03001147
78      2 10.37754004
79      2 10.42970988
80      2  5.30819353
81      2 13.36327886
82      2 11.68057220
83      2 -0.18300430
84      2  5.51915435
85      2  5.15743041
86      2  6.01768963
87      2 11.28639246
88      2 10.55082700
89      2  5.54828808
90      2  9.68504303
91      2  9.12542468
92      2  0.53159052
93      2 12.41983360
94      2  0.96142457
95      2 12.38531380
96      2  3.97646479
97      2 11.26449122
98      2 17.08345606
99      2  4.81729861
100     2  6.31877527

attr(,"class")
[1] "SimulationResult"

Solution: implement generic function print

Example - Step 3: Packaging

Generic function print:

print.SimulationResult <- function(x, ...) {
    args <- list(n1 = x$n1, n2 = x$n2, 
        mean1 = x$mean1, mean2 = x$mean2, sd1 = x$sd1, sd2 = x$sd2)
    
    print(list(
        args = format(args), 
        data = dplyr::tibble(x$data)
    ), ...)
}
x
  • tags @title, @description, @typed are action words that Roxygen2 package to builds into document entitled by the @title tag in .Rd format.
  • the standard format is #' for document specific documentation.
#' @title
#' Print Simulation Result
#'
#' @description
#' Generic function to print a `SimulationResult` object.
#'
#' @param x a \code{SimulationResult} object to print.
#' @param ... further arguments passed to or from other methods.
#' 
#' @examples
#' x <- getSimulatedTwoArmMeans(n1 = 50, n2 = 50, mean1 = 5, 
#'      mean2 = 7, sd1 = 3, sd2 = 4, seed = 123)
#' print(x)
#'
#' @export
$args
   n1    n2 mean1 mean2   sd1   sd2 
 "50"  "50"   "5"   "7"   "3"   "4" 

$data
# A tibble: 100 × 2
   group values
   <dbl>  <dbl>
 1     1  6.93 
 2     1  4.27 
 3     1  4.84 
 4     1  6.48 
 5     1  4.33 
 6     1 -1.72 
 7     1  1.08 
 8     1  8.54 
 9     1  8.38 
10     1  0.225
# ℹ 90 more rows

Exercise

Photo CC0 by Pixabay on pexels.com

Preparation

  1. Download the unfinished R package simulatr
  2. Extract the package zip file
  3. Open the project with RStudio
  4. Complete the tasks below

Tasks

Add assertions to improve the usability and user experience

Tip on assertions

Use the package checkmate to validate input arguments.

Example:

playWithAssertions <- function(n1) {
  checkmate::assertInt(n1, lower = 1)
}
playWithAssertions(-1)

Error in playWithAssertions(-1) : Assertion on ‘n1’ failed: Element 1 is not >= 1.

Add three additional results:

  1. n total,
  2. creation time, and
  3. allocation ratio

Tip on creation time

Sys.time(), format(Sys.time(), '%B %d, %Y'), Sys.Date()

Add an additional result: t.test result

Add an optional alternative argument and pass it through t.test:

alternative = c("two.sided", "less", "greater")

Implement the generic functions print and plot.

Tip on print

Use the plot example function from above and extend it.

Tip on plot

Use R base plot or ggplot2 to create a grouped boxplot of the fake data.

Optional extra tasks:

  • Implement the generic functions summary and cat

  • Implement the function kable known from the package knitr as generic. Tip: use

    kable <- function(x) UseMethod("kable")

    to define kable as generic

Optional extra task1:

Document your functions with Roxygen2

  1. If you are already familiar with Roxygen2

References

  • Gillespie, C., & Lovelace, R. (2017). Efficient R Programming: A Practical Guide to Smarter Programming. O’Reilly UK Ltd. [Book | Online]
  • Grolemund, G. (2014). Hands-On Programming with R: Write Your Own Functions and Simulations (1. Aufl.).
    O’Reilly and Associates. [Book | Online]
  • Rupp, C., & SOPHISTen, die. (2009). Requirements-Engineering und -Management: Professionelle, iterative Anforderungsanalyse für die Praxis (5. Ed.). Carl Hanser Verlag GmbH & Co. KG. [Book]
  • Wickham, H. (2015). R Packages: Organize, Test, Document, and Share Your Code (1. Aufl.). O’Reilly and Associates. [Book | Online]
  • Wickham, H. (2019). Advanced R, Second Edition.
    Taylor & Francis Ltd. [Book | Online]

License information