Add Stan support as alternative Bayesian modeling backend

.github/copilot-instructions.md

@@ -2,12 +2,17 @@
 
 ## Repository Overview
 
-**serodynamics** is an R package for modeling longitudinal antibody responses to infection. It implements Bayesian MCMC methods using JAGS (Just Another Gibbs Sampler) to estimate antibody dynamic curve parameters including baseline concentration, peak concentration, time to peak, shape parameter, and decay rate.
+**serodynamics** is an R package for modeling longitudinal antibody responses to infection. It implements Bayesian MCMC methods to estimate antibody dynamic curve parameters including baseline concentration, peak concentration, time to peak, shape parameter, and decay rate.
+
+The package supports two Bayesian modeling backends:
+- **JAGS** (Just Another Gibbs Sampler) via `runjags` - the original implementation
+- **Stan** via `cmdstanr` - a modern, efficient alternative (optional)
 
 - **Type**: R package (statistical modeling)
 - **Size**: ~121MB, ~209 files, ~76 R source files, ~1,664 lines of R code
 - **Language**: R (>= 4.1.0)
 - **Key Dependencies**: runjags, rjags, JAGS 4.3.1, serocalculator, ggmcmc, dplyr, ggplot2
+- **Optional Dependencies**: cmdstanr (for Stan support)
 - **Lifecycle**: Experimental (under active development)
 
 ## Lab-Wide Guidance
@@ -231,9 +236,9 @@ devtools::check_man()
 
 - **Windows**: Install Rtools from https://cran.r-project.org/bin/windows/Rtools/ (choose version matching your R version)
 
-### JAGS Installation (REQUIRED)
+### JAGS Installation (REQUIRED for JAGS models)
 
-**ALWAYS install JAGS before attempting to build, test, or run this package.** The package will fail without it.
+**Install JAGS if you plan to use `run_mod()` with JAGS models.** JAGS is required for the original JAGS-based modeling functions but is not needed if you only use Stan models via `run_mod_stan()`.
 
 #### Installing JAGS in Docker (if using rocker/verse)
 
@@ -268,6 +273,25 @@ runjags::findJAGS()
 runjags::testjags()
 ```
 
+### Stan Installation (OPTIONAL for Stan models)
+
+**Install cmdstanr and CmdStan if you plan to use `run_mod_stan()`.** Stan support is optional and provides a modern alternative to JAGS.
+
+```r
+# Install cmdstanr from r-universe
+install.packages("cmdstanr", 
+                 repos = c("https://stan-dev.r-universe.dev",
+                          getOption("repos")))
+
+# Then install CmdStan
+cmdstanr::install_cmdstan()
+
+# Verify installation
+cmdstanr::cmdstan_version()
+```
+
+See the [cmdstanr documentation](https://mc-stan.org/cmdstanr/) for more details and troubleshooting.
+
 ## Build and Development Workflow
 
 ### Initial Setup
@@ -394,8 +418,13 @@ Team members can trigger actions by commenting on PRs:
 
 - **R/**: Package source code (30 R files)
   - `run_serodynamics.R`: Main function to run JAGS Bayesian models
+  - `run_mod.R`: Deprecated wrapper for `run_serodynamics()`
+  - `run_mod_stan.R`: Main function to run Stan Bayesian models
   - `as_case_data.R`: Convert data to case_data class
-  - `prep_data.r`, `prep_priors.R`: Data preparation for JAGS
+  - `prep_data.r`: Data preparation for JAGS
+  - `prep_data_stan.R`: Data preparation for Stan (new)
+  - `prep_priors.R`: Prior preparation for JAGS
+  - `prep_priors_stan.R`: Prior preparation for Stan (new)
   - `sim_case_data.R`: Simulate case data for testing
   - `summarize_posterior.R`, `postprocess_jags_output.R`: Post-processing JAGS results
   - `plot_*.R`: Diagnostic plotting functions (trace, density, Rhat, effective sample size)
@@ -415,8 +444,13 @@ Team members can trigger actions by commenting on PRs:
 - **data-raw/**: Raw data processing scripts (not included in package build)
 
 - **inst/**: Installed files
-  - `inst/extdata/`: JAGS model files (`model.jags`, `model.dobson.jags`), example CSV data
+  - `inst/extdata/`: Model files
+    - `model.jags`, `model.dobson.jags`: JAGS model files
+    - `model.stan`, `model.dobson.stan`: Stan model files (new)
+    - Example CSV data files
   - `inst/examples/`: Example R scripts for documentation
+    - JAGS examples: `run_mod-examples.R`, `examples-prep_priors.R`
+    - Stan examples: `run_mod_stan-examples.R`, `examples-prep_priors_stan.R`, `examples-prep_data_stan.R` (new)
   - `inst/WORDLIST`: Custom spelling dictionary
 
 - **vignettes/**: Package vignettes
@@ -546,6 +580,7 @@ expect_false(has_missing_values(complete_data))
 - **Messaging**: Use `cli::cli_*()` functions for all user-facing messages
 - **No `library()` in package code**: Use `::` or DESCRIPTION Imports
 - **Document all exports**: Use roxygen2 (@title, @description, @param, @returns, @examples)
+- **Use markdown syntax in roxygen2**: Use markdown syntax (numbered lists: `1.`, `2.`, etc.; bullet lists: `-` or `*`) instead of Rd syntax (`\enumerate{}`, `\itemize{}`, `\item`) in roxygen2 documentation comments
 - **Test snapshot changes**: Use `testthat::announce_snapshot_file()` for CSV snapshots
 - **Seed tests**: Use `withr::local_seed()` for reproducible tests
 - **Prefer data-first pipelines**: Design and call functions so the primary data object flows through `|>` naturally
@@ -608,10 +643,39 @@ These instructions have been validated against the actual repository structure,
 9. **ALWAYS** run tests before committing (`devtools::test()`)
 10. **ALWAYS** check and fix lintr issues in changed files in PRs before committing
 11. **ALWAYS** run `devtools::document()` before requesting PR review
-12. **ALWAYS** make sure `devtools::check()` passes before requesting PR review
-13. **ALWAYS** make sure `devtools::spell_check()` passes before requesting PR review
-14. **ALWAYS** run `pkgdown::build_site()` before requesting PR review to ensure the pkgdown site builds successfully
-15. **ALWAYS** verify Quarto documents render successfully locally - don't rely on CI workflows. For vignettes and articles, test rendering with `quarto render path/to/file.qmd` or by building the full site with `pkgdown::build_site()`
-16. When `pkgdown::build_site()` has errors related to Quarto, use `quarto::quarto_render(input = "path/to/file.qmd", quiet = FALSE)` to debug and see detailed error messages
+12. **ALWAYS** run `lintr::lint_package()` before requesting PR review and fix all linting issues
+13. **ALWAYS** run `devtools::check()` before requesting PR review and ensure it passes with 0 errors, 0 warnings, 0 notes
+14. **ALWAYS** make sure `spelling::spell_check_package()` passes before requesting PR review
+15. **ALWAYS** run `pkgdown::build_site()` before requesting PR review to ensure the pkgdown site builds successfully
+16. **ALWAYS** verify Quarto documents render successfully locally - don't rely on CI workflows. For vignettes and articles, test rendering with `quarto render path/to/file.qmd` or by building the full site with `pkgdown::build_site()`
+17. When `pkgdown::build_site()` has errors related to Quarto, use `quarto::quarto_render(input = "path/to/file.qmd", quiet = FALSE)` to debug and see detailed error messages
+
+**CRITICAL PRE-REVIEW VALIDATION**: Before requesting PR review, you MUST run the following validation commands locally and ensure they all pass:
+```r
+# 1. Lint the package - must have 0 linting issues
+lintr::lint_package()
+
+# 2. Run R CMD check - must pass with 0 errors, 0 warnings, 0 notes
+devtools::check()
+
+# 3. Check spelling - must have no spelling errors
+spelling::spell_check_package()
+
+# 4. Build pkgdown site - must build successfully
+pkgdown::build_site()
+```
+
+Do NOT request review if any of these checks fail. Fix all issues first, then re-run the checks to verify.
+
+**AUTOMATED CODE REVIEW ITERATION**: After completing all changes and passing the validation checks above, you MUST iterate with the automated code review (parallel_validation tool) until it provides no further valid feedback:
+
+1. Run `parallel_validation` with appropriate PR title, description, and triviality assessment
+2. Carefully review all feedback from both Code Review and CodeQL Security Scan
+3. Address all valid issues identified by the automated review
+4. Re-run `parallel_validation` after making changes
+5. Repeat steps 2-4 until the automated review provides no further valid feedback
+6. Only then request human review
+
+This iterative process catches issues early and ensures high code quality before human review.
 
 Only search for additional information if these instructions are incomplete or incorrect for your specific task.

.github/workflows/R-CMD-check.yaml

@@ -66,19 +66,31 @@ jobs:
           extra-packages: any::rcmdcheck
           needs: test, check
 
-      - name: "install rjags"
+      - name: "install JAGS R packages"
         run: |
+          if (Sys.info()[["sysname"]] == "Windows") {
+            install.packages("coda",
+                      repos = "https://cloud.r-project.org",
+                      type = "source",
+                      verbose = TRUE)
+            install.packages("runjags",
+                      repos = "https://cloud.r-project.org",
+                      type = "source",
+                      verbose = TRUE)
+          }
+
           install.packages("rjags",
                     repos = "https://cloud.r-project.org",
                     type = "source",
                     verbose = TRUE)
-           withr::local_options(warn = 2)
-           library(rjags)
-           library(runjags)
-           runjags::findjags()
-           runjags::testjags()
+
+          library(rjags)
+          library(runjags)
+          withr::local_options(warn = 2)
+          runjags::findjags()
+          runjags::testjags()
         shell: Rscript {0}
-      
+
       - uses: r-lib/actions/check-r-package@v2
         with:
           upload-snapshots: true

.github/workflows/copilot-setup-steps.yml

@@ -81,7 +81,7 @@ jobs:
 
       # Install R dependencies with caching for faster subsequent runs
       - name: Install R dependencies
-        uses: r-lib/actions/setup-r-dependencies@HEAD
+        uses: r-lib/actions/setup-r-dependencies@v2
         with:
           extra-packages: |
             any::devtools
@@ -106,6 +106,19 @@ jobs:
           runjags::testjags()
         shell: Rscript {0}
 
+      # Install cmdstanr for Stan modeling support (optional)
+      # See .github/copilot-instructions.md "Stan Installation" section
+      - name: Install cmdstanr
+        run: |
+          install.packages("cmdstanr",
+                    repos = c("https://stan-dev.r-universe.dev",
+                             "https://cloud.r-project.org"),
+                    verbose = TRUE)
+          cmdstanr::install_cmdstan(cores = 2)
+          cat("cmdstanr version:", as.character(packageVersion("cmdstanr")), "\n")
+          cat("CmdStan version:", cmdstanr::cmdstan_version(), "\n")
+        shell: Rscript {0}
+
       # Verify JAGS installation
       # See .github/copilot-instructions.md "JAGS Installation" section for details
       - name: Verify JAGS installation
@@ -144,7 +157,7 @@ jobs:
 
             # Display key installed packages
             cat("Key installed packages:\n")
-            key_packages <- c("devtools", "rjags", "runjags", "rcmdcheck", "lintr", "spelling", "testthat")
+            key_packages <- c("devtools", "rjags", "runjags", "cmdstanr", "rcmdcheck", "lintr", "spelling", "testthat")
             for (pkg in key_packages) {
               if (requireNamespace(pkg, quietly = TRUE)) {
                 cat("  -", pkg, ":", as.character(packageVersion(pkg)), "\n")

.github/workflows/lint-changed-files.yaml

@@ -17,7 +17,7 @@ jobs:
         with:
           use-public-rspm: true
 
-      - uses: r-lib/actions/setup-r-dependencies@HEAD
+      - uses: r-lib/actions/setup-r-dependencies@v2
         with:
           extra-packages: |
             any::gh

.gitignore

@@ -14,19 +14,18 @@ cholera_data_compiled_050324.csv
 inst/extdata/*.csv
 *.xlsx
 *.xls
-docs
+docs/
 serodynamics.Rcheck/
 serodynamics*.tar.gz
 serodynamics*.tgz
 inst/doc
 **/.quarto/
 vignettes/*.pdf
 vignettes/*.tex
-docs/
-
 /.quarto/
-
 **/*.quarto_ipynb
 README.html
+*.knit.*
+..Rcheck/
 /doc/
 /Meta/

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: serodynamics
 Title: Modeling Longitudinal Antibody Responses to Infection
-Version: 0.1.0.9003
+Version: 0.1.0.9004
 Authors@R: c(
     person("Peter", "Teunis", , "p.teunis@emory.edu", role = c("aut", "cph"),
            comment = c("Author of the method and original code.",
@@ -46,6 +46,8 @@ Imports:
     tidyselect,
     utils
 Suggests: 
+    badger,
+    cmdstanr,
     Hmisc,
     knitr,
     readr,
@@ -74,6 +76,8 @@ Config/needs/test:
     magrittr,
     rlist
 Config/needs/check: commonmark, xml2
+Remotes: 
+    stan-dev/cmdstanr
 Depends: 
     R (>= 4.1.0)
 LazyData: true

NAMESPACE

@@ -15,9 +15,13 @@ export(plot_rhat)
 export(plot_trace)
 export(postprocess_jags_output)
 export(prep_data)
+export(prep_data_stan)
 export(prep_priors)
+export(prep_priors_stan)
 export(run_mod)
+export(run_mod_stan)
 export(run_serodynamics)
+export(sample_predictive_stan)
 export(serodynamics_example)
 export(sim_case_data)
 export(sim_n_obs)
@@ -46,6 +50,8 @@ importFrom(serocalculator,get_values)
 importFrom(serocalculator,ids)
 importFrom(serocalculator,ids_varname)
 importFrom(stats,complete.cases)
+importFrom(stats,median)
 importFrom(stats,quantile)
+importFrom(stats,rnorm)
 importFrom(tidyr,pivot_wider)
 importFrom(utils,read.csv)

NEWS.md

@@ -1,6 +1,15 @@
 # serodynamics (development version)
 
 ## New features
+
+* Added Stan support as an alternative to JAGS for Bayesian modeling:
+  * New `run_mod_stan()` function for fitting models with Stan/cmdstanr.
+  * New `prep_data_stan()` function to prepare data in Stan format.
+  * New `prep_priors_stan()` function to prepare priors for Stan models.
+  * New Stan model files: `inst/extdata/model.stan` and
+    `inst/extdata/model.dobson.stan`.
+  * Stan support is optional (`cmdstanr` in Suggests) and can be used
+    alongside JAGS.
 * Renamed user-facing functions for clarity (#241):
   - `run_mod()` → `run_serodynamics()`
   - `post_summ()` → `summarize_posterior()`
@@ -15,11 +24,13 @@
 output. (#141)
 
 ## Bug fixes
-* `run_mod()`'s `fitted_residuals` attribute now covers all observations across 
-all strata (previously only the last stratum was retained) and always includes 
-a `Stratification` column (`"None"` when unstratified). (#240)
+
+* `run_mod()`'s `fitted_residuals` attribute now covers all observations across
+  all strata (previously only the last stratum was retained) and always includes
+  a `Stratification` column (`"None"` when unstratified). (#240)
 
 ## Developer-facing changes
+
 * Documented in `CLAUDE.md`, `.github/copilot-instructions.md`, and a
   note in `.lintr.R` that `dplyr::*_join()` calls must specify the
   `relationship` argument (for example `relationship = "many-to-one"`),