How genentech/bayeserbook works
This project is a book that serves as a hands‐on tutorial on exposure–response analysis using Bayesian methods. It’s built entirely within the R ecosystem and uses Quarto for authoring and publishing, leveraging the BayesERtools package along with related Bayesian modeling packages like rstanarm and rstanemax. The project not only houses the source content (in the form of .qmd notebooks and R scripts) but also retains execution outputs (in the “_freeze” and “output” directories) and includes continuous integration workflows for publishing updates.
Main components
• Source Repository & Project Management:
• Git repository containing the full file tree, including the R project file (BayesERbook.Rproj), build/configuration files (.github/workflows, .gitignore, quarto.yml), and style resources (custom.scss).
• Content & Analysis Notebooks:
• “notebook” directory with two subdivisions: “binary” and “emax”. Each contains several .qmd (Quarto) files illustrating analytical workflows (e.g., basic_workflow, simulation, model_diagnostics).
• Execution & Freeze Artifacts:
• The “_freeze” directory contains executed notebook versions including rendered outputs (HTML results, figure directories, etc.), ensuring reproducibility.
• R Scripts & Modules:
• The “R” directory (e.g., R/cli_color_text.R) for utility functions and additional code behind the scenes.
• Data Handling:
• “data” directory with example CSV files that serve as inputs for the exposure–response analyses.
• Output & Artifacts:
• “output” directory holding serialized model objects and computed metrics (RDS files) generated during the analytical processes.
• Continuous Integration & Deployment:
• The “.github” directory (notably the publish.yml workflow) demonstrates how the project is built, tested, and published automatically.
• External Dependencies:
• The project relies on external packages (BayesERtools, rstanarm, and rstanemax) as well as the Quarto rendering engine that converts .qmd files into a polished website or book.
Relationships and interactions
• Data Flow:
• How the raw data (from the “data” folder) is ingested by R scripts and notebooks.
• How notebooks consume these inputs, perform Bayesian model fitting (using rstanarm/rstanemax via BayesERtools), and finally generate output summaries (RDS files in “output”) and rendered HTML (in “_freeze”).
• Build & Execution Pipeline:
• Transformation of source notebooks (.qmd files) through the Quarto build process (guided by quarto.yml) to produce the final published book.
• That CI/CD (from GitHub workflows) is triggered upon commits, ensuring that code style (via usethis::use_tidy_style) and publishing are automatically enforced.
• External Services:
• Optionally denote the links to external documentation sites (BayesERtools website and GitHub repo) and the integration with R package repositories.
Important architectural patterns and design principles
• Separation of concerns is evident – the project clearly segments code (in the “R” folder), notebooks (in “notebook”), and data/results.
• Reproducibility is enforced with “freeze” folders that capture execution state and output.
• Continuous integration (“.github/workflows”) is used to maintain code quality and automate the publishing process.
• Modularity is supported via discrete notebooks for different analyses, enabling easy extension and reuse.