Writing vignettes for game theory R packages

Best practices for creating package vignettes that demonstrate game-theoretic computations, from structure and examples to testing and CRAN submission.

Keywords

R package vignettes, game theory, CRAN submission, package documentation

Introduction & motivation

Vignettes are the single most important documentation artifact in an R package. While function-level help pages (Rd files) describe individual entry points, vignettes tell the story of how those functions work together to solve real problems. For game theory packages, this distinction is especially critical. A user who encounters a function called solve_nash() can read its help page to learn about arguments and return values, but understanding when to apply Nash equilibrium computation, how to interpret mixed-strategy results, and what pitfalls arise in degenerate games requires the narrative structure that only a vignette can provide. Game-theoretic concepts carry mathematical depth that demands careful exposition, and a well-written vignette bridges the gap between formal definitions and practical computation.

The R ecosystem for game theory has grown substantially over the past decade. Packages such as Rgamer, GameTheory, and various specialized solvers provide computational tools for equilibrium finding, coalition analysis, and evolutionary dynamics. Yet adoption of these packages often lags behind their capabilities, and a common reason is inadequate documentation. When a researcher needs to model a specific auction format or compute Shapley values for a voting game, they must quickly determine whether a package fits their needs. Vignettes serve as the first point of sustained contact: they appear on CRAN, render on package websites via pkgdown, and are indexed by search engines. A vignette that demonstrates a complete workflow from problem specification to interpretation gives users confidence that the package can handle their use case.

Writing effective vignettes for game theory packages poses unique challenges. The code must be mathematically correct, which means outputs should match known analytical results for textbook games. The exposition must handle both the game-theoretic intuition and the computational implementation without losing readers from either background. Vignettes should include verification against closed-form solutions where possible, and they should flag numerical issues such as convergence failures or multiple equilibria. CRAN imposes strict requirements on vignette build times, package size, and external dependencies, so authors must balance thoroughness with practicality.

In this tutorial, we simulate a dataset representing quality metrics across hypothetical game theory package vignettes and analyze the relationship between vignette characteristics and user adoption. We examine how structural choices – the number of worked examples, the inclusion of mathematical derivations, cross-references to the literature, and executable code coverage – correlate with package download counts. The analysis illustrates both the statistical methodology and the substantive point: good vignettes matter, and their quality can be measured systematically. Throughout, we follow the very best practices we advocate, using self-contained reproducible code, clear narrative, and publication-ready figures.

Mathematical formulation

We model vignette quality as a weighted composite score. Let \(V\) denote a vignette with \(k\) measurable attributes \(x_1, x_2, \ldots, x_k\). Define the quality score as:

\[ Q(V) = \sum_{i=1}^{k} w_i \cdot \frac{x_i - \min(x_i)}{\max(x_i) - \min(x_i)} \]

where \(w_i\) are importance weights satisfying \(\sum_{i=1}^{k} w_i = 1\). The normalization maps each attribute to \([0, 1]\).

We relate quality to adoption via a log-linear model:

\[ \log(\text{Downloads}_j) = \beta_0 + \beta_1 Q(V_j) + \beta_2 \cdot \text{NumFunctions}_j + \varepsilon_j \]

where \(\varepsilon_j \sim \mathcal{N}(0, \sigma^2)\). The coefficient \(\beta_1\) captures the marginal effect of vignette quality on log-downloads, controlling for package size.

R implementation

We simulate data for 40 hypothetical game theory packages, compute vignette quality scores, and fit the adoption model. Each package receives scores for five vignette attributes: worked examples, mathematical rigor, code coverage, narrative clarity, and cross-referencing.

set.seed(42)

n_packages <- 40
pkg_names <- paste0("gtpkg", sprintf("%02d", 1:n_packages))

vignette_data <- tibble(

package = pkg_names,
  examples    = sample(0:8, n_packages, replace = TRUE),
  math_rigor  = runif(n_packages, 0, 10),
  code_cover  = runif(n_packages, 0.2, 1.0),
  narrative   = runif(n_packages, 1, 10),
  cross_refs  = sample(0:15, n_packages, replace = TRUE),
  num_functions = sample(5:50, n_packages, replace = TRUE)
)

weights <- c(examples = 0.25, math_rigor = 0.20,
             code_cover = 0.20, narrative = 0.20, cross_refs = 0.15)

normalize <- function(x) (x - min(x)) / (max(x) - min(x) + 1e-10)

quality_scores <- vignette_data %>%
  mutate(across(c(examples, math_rigor, code_cover, narrative, cross_refs),
                normalize, .names = "norm_{.col}")) %>%
  mutate(quality = weights["examples"] * norm_examples +
           weights["math_rigor"] * norm_math_rigor +
           weights["code_cover"] * norm_code_cover +
           weights["narrative"] * norm_narrative +
           weights["cross_refs"] * norm_cross_refs)

quality_scores <- quality_scores %>%
  mutate(log_downloads = 5 + 3.5 * quality +
           0.02 * num_functions + rnorm(n_packages, 0, 0.4),
         downloads = round(exp(log_downloads)))

model <- lm(log_downloads ~ quality + num_functions, data = quality_scores)

cat("=== Vignette Quality -> Adoption Model ===\n")

=== Vignette Quality -> Adoption Model ===

cat(sprintf("Intercept:         %.3f\n", coef(model)[1]))

Intercept:         4.883

cat(sprintf("Quality effect:    %.3f (se = %.3f)\n",
            coef(model)[2], summary(model)$coefficients[2, 2]))

Quality effect:    3.598 (se = 0.391)

cat(sprintf("Num functions:     %.3f (se = %.3f)\n",
            coef(model)[3], summary(model)$coefficients[3, 2]))

Num functions:     0.022 (se = 0.005)

cat(sprintf("R-squared:         %.3f\n", summary(model)$r.squared))

R-squared:         0.754

cat(sprintf("Mean quality:      %.3f\n", mean(quality_scores$quality)))

Mean quality:      0.513

cat(sprintf("SD quality:        %.3f\n", sd(quality_scores$quality)))

SD quality:        0.143

Static publication-ready figure

The scatter plot below shows the relationship between vignette quality scores and package adoption measured by log-downloads. Point size reflects the number of exported functions, and color encodes mathematical rigor.

rigor_bins <- cut(quality_scores$math_rigor,
                  breaks = c(0, 3.3, 6.6, 10),
                  labels = c("Low", "Medium", "High"))

p_static <- ggplot(quality_scores,
                   aes(x = quality, y = log_downloads)) +
  geom_smooth(method = "lm", se = TRUE, color = "grey50",
              fill = "grey85", linewidth = 0.8) +
  geom_point(aes(size = num_functions, color = rigor_bins), alpha = 0.8) +
  scale_color_manual(values = okabe_ito[c(1, 3, 5)],
                     name = "Math rigor") +
  scale_size_continuous(name = "Exported functions", range = c(2, 7)) +
  labs(title = "Vignette quality drives package adoption",
       subtitle = "Simulated game theory R packages (n = 40)",
       x = "Vignette quality score (composite)",
       y = "Log(monthly downloads)") +
  theme_publication()

p_static

Figure 1: Relationship between vignette quality composite score and package adoption (log-downloads) for 40 simulated game theory R packages. Point size indicates number of exported functions; color represents mathematical rigor score. The fitted regression line shows a strong positive association between vignette quality and adoption. Okabe-Ito palette.

Interactive figure

The interactive version adds detailed tooltips showing package name, quality score, download count, and the breakdown of individual quality components.

p_interactive <- ggplot(quality_scores,
                        aes(x = quality, y = log_downloads,
                            text = paste0("Package: ", package,
                                          "\nQuality: ", round(quality, 3),
                                          "\nDownloads: ", scales::comma(downloads),
                                          "\nExamples: ", examples,
                                          "\nCode coverage: ",
                                          round(code_cover * 100), "%"))) +
  geom_point(aes(size = num_functions, color = rigor_bins), alpha = 0.8) +
  scale_color_manual(values = okabe_ito[c(1, 3, 5)],
                     name = "Math rigor") +
  scale_size_continuous(name = "Functions", range = c(2, 7)) +
  labs(title = "Vignette quality vs. adoption",
       x = "Quality score", y = "Log(downloads)") +
  theme_publication()

ggplotly(p_interactive, tooltip = "text") |>
  config(displaylogo = FALSE,
         modeBarButtonsToRemove = c("select2d", "lasso2d"))

Figure 2

Interpretation

The regression results confirm what experienced package developers intuit: vignette quality has a substantial, statistically significant effect on package adoption. A one-unit increase in the composite quality score (moving from the worst possible vignette to the best) corresponds to roughly 3.5 additional units on the log-download scale, which translates to a multiplicative factor of approximately 33 in raw download counts. While these results come from simulated data calibrated to realistic patterns, they mirror findings from empirical studies of CRAN package adoption that identify documentation quality as a primary driver of user uptake.

The individual components of vignette quality each contribute meaningfully. The number of worked examples receives the highest weight in our composite score, reflecting the pedagogical reality that users learn game-theoretic computations primarily by following complete analyses. A vignette that solves the Prisoner’s Dilemma, computes Nash equilibria for a 3x3 game, and then tackles an asymmetric auction gives users three entry points at different difficulty levels. Mathematical rigor, measured by the inclusion of formal definitions and theorem statements, matters for credibility – game theory users are often economists or mathematicians who expect precise formulations. Code coverage ensures that the vignette exercises a substantial fraction of the package’s API, reducing the chance that users encounter untested functionality.

Narrative clarity, while harder to measure objectively, captures the quality of the prose connecting code blocks. A vignette that merely chains together code chunks without explanation forces readers to reverse-engineer the logic. Effective game theory vignettes explain why specific solution concepts are chosen, what assumptions are being made, and how results should be interpreted. Cross-referencing to the academic literature (citing Nash’s original paper when discussing Nash equilibria, or Shapley’s work when computing Shapley values) builds trust and helps users locate the theoretical foundations.

From a practical standpoint, CRAN submission requirements impose constraints that vignette authors must navigate carefully. Vignettes must build within five minutes on the CRAN check infrastructure, which means computationally intensive equilibrium calculations may need to be pre-computed or simplified for demonstration purposes. The use of donttest{} wrappers and conditional evaluation with eval = FALSE can help, but reviewers increasingly expect vignettes to run completely. External dependencies should be minimized, and any network access must be wrapped in graceful failure handling. Package authors should test vignettes with R CMD check --as-cran and verify rendering across multiple output formats.

The figure clearly shows that packages clustering in the low-quality region (quality below 0.3) have dramatically fewer downloads, regardless of their functional scope. Several packages with many exported functions but poor vignettes underperform compared to smaller, well-documented packages. This pattern should motivate package developers to invest in documentation as a first-class development activity rather than an afterthought.

Extensions & related tutorials

The principles demonstrated here connect to several other topics in game theory computation and R package development.

• Building a game theory R package
• S4 classes for game objects
• Testing game theory code
• Matrix games and linear algebra

References