Building High-Quality Reproducible Examples in R: Methods and Best Practices

The Importance of Reproducible Examples

Reproducible examples are essential tools in technical discussions, teaching, bug reporting, and seeking guidance. A well-constructed Minimal Reproducible Example (MRE) enables others to precisely replicate your issues on their own machines, facilitating effective assistance.

Core Components of Minimal Reproducible Examples

A complete MRE should include the following key components: minimal dataset, minimal runnable code, necessary environment information, and seed setting for random processes.

Data Preparation Strategies

Data forms the foundation of MREs. Typically, there's no need to share large original datasets; instead, create small example data that simulates the problem.

Using Built-in Datasets

R provides rich built-in datasets that can be viewed using the data() command. For example, use ?iris to view detailed information about the iris dataset.

Creating Example Data

For data requiring specific formats, use appropriate conversion functions:

# Date type example
d <- as.Date("2020-12-30")
class(d)
# [1] "Date"

Vector Creation

x <- rnorm(10)  # Normally distributed random vector
x <- runif(10)  # Uniformly distributed random vector
x <- sample(1:100, 10)  # Random sample of 10 values from 1 to 100
x <- sample(LETTERS, 10)  # Random sample of 10 letters from alphabet

Matrix Creation

m <- matrix(1:12, 3, 4, dimnames=list(LETTERS[1:3], LETTERS[1:4]))
m
#   A B C  D
# A 1 4 7 10
# B 2 5 8 11
# C 3 6 9 12

Data Frame Creation

set.seed(42)  # Set random seed for reproducibility
n <- 6
dat <- data.frame(id=1:n, 
                  date=seq.Date(as.Date("2020-12-26"), as.Date("2020-12-31"), "day"),
                  group=rep(LETTERS[1:2], n/2),
                  age=sample(18:30, n, replace=TRUE),
                  type=factor(paste("type", 1:n)),
                  x=rnorm(n))
dat
#   id       date group age   type         x
# 1  1 2020-12-26     A  27 type 1 0.0356312
# 2  2 2020-12-27     B  19 type 2 1.3149588
# 3  3 2020-12-28     A  20 type 3 0.9781675
# 4  4 2020-12-29     B  26 type 4 0.8817912
# 5  5 2020-12-30     A  26 type 5 0.4822047
# 6  6 2020-12-31     B  28 type 6 0.9657529

Note: Avoid using df as a data frame name since df() is the name of the F distribution density function in R, which may cause conflicts.

Copying Original Data

When sharing original data is necessary, the dput() function is the best choice as it generates R code required for exact data replication.

Why Use dput()?

dput() output contains all necessary information about the data, including variable types and other characteristics. In contrast, directly printing data loses these important details.

Data Subset Processing

# Sharing data subsets
dput(iris[1:4, ])  # First four rows of iris dataset

Console output:

structure(list(Sepal.Length = c(5.1, 4.9, 4.7, 4.6), Sepal.Width = c(3.5, 
3, 3.2, 3.1), Petal.Length = c(1.4, 1.4, 1.3, 1.5), Petal.Width = c(0.2, 
0.2, 0.2, 0.2), Species = structure(c(1L, 1L, 1L, 1L), .Label = c("setosa", 
"versicolor", "virginica"), class = "factor")), row.names = c(NA, 
4L), class = "data.frame")

Handling Factor Level Issues

When data frames contain multi-level factors, dput output can be overly verbose. Use the droplevels() function to address this:

dput(droplevels(iris[1:4, ]))

Special Data Structure Handling

For data.table or tidyverse's tbl_df objects, convert to regular data frames first:

dput(as.data.frame(my_data))

Code Writing Standards

Code should be concise and clear, capable of directly reproducing the problem.

Practices to Avoid

• Including unnecessary data transformation steps
• Pasting entire scripts instead of locating specific problematic code

Principles to Follow

• Explicitly load required packages at the beginning of code
• Test code in new sessions to ensure runnability
• Provide closing or cleanup code for operations involving open connections or file creation
• Ensure restoration of original settings if global options are modified

Providing Environment Information

Complete environment information is crucial for problem diagnosis.

Basic Environment Information

Typically, provide R version and operating system information. When package conflicts are involved, sessionInfo() output is particularly valuable.

Specific Environment Information

For RStudio users:

rstudioapi::versionInfo()

For specific package issues:

packageVersion("package_name")

Reproducibility in Random Processes

Setting random seeds is essential in code involving random numbers.

set.seed(42)
rnorm(3)
# [1]  1.3709584 -0.5646982  0.3631284

set.seed(42)
rnorm(3)
# [1]  1.3709584 -0.5646982  0.3631284

Note: Random number generators in R 3.6.0 and later versions differ from earlier versions. To reproduce results from older versions, use:

RNGversion("3.5.2")
set.seed(42)

Verification and Sharing

Before sharing examples, always test code for complete runnability in new R sessions. Consider using platforms like GitHub Gist for code sharing to benefit from better syntax highlighting and format preservation.

Conclusion

Building high-quality reproducible examples requires systematic approaches and careful preparation. By following the best practices outlined in this article, you will be able to create clear, complete, and easily understandable examples that facilitate more effective technical support and collaborative experiences.