Chapter 2: Stan Model 2 Kronecker simulation (restructure)

.Rbuildignore

@@ -11,6 +11,9 @@
 ^data-raw$
 ^README\.Rmd$
 ^\.lintr\.R$
+^\.lintr$
+^scripts$
+^slurm$
 ^_quarto\.yml$
 ^.*\.qmd$
 ^.*\.png$

.do_commit.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+git -c user.name="Claude" -c user.email="claude[bot]@users.noreply.github.com" \
+  commit --author="claude[bot] <claude[bot]@users.noreply.github.com>" \
+  -m "fix(sampler): increase max_treedepth default from 12 to 15
+
+50% treedepth saturation on n=5 phase0 run (500/1000 transitions hit
+the ceiling) is the dominant driver of ESS_bulk=16 and R-hat=1.766.
+The LKJ Cholesky geometry requires longer HMC trajectories than
+max_treedepth=12 allows; raising to 15 gives 8x more trajectory
+length budget before truncation.
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"

.gitconfig_tmp

@@ -0,0 +1,3 @@
+[user]
+	name = Claude
+	email = claude[bot]@users.noreply.github.com

.github/workflows/phase0-debug.yaml

@@ -8,6 +8,16 @@ name: Phase 0 Debug Loop
 #   to the branch under outputs/ci/ so Claude can read them in the
 #   next turn.
 #
+# Architecture note:
+#   This workflow uses the standard r-lib/actions/setup-r-dependencies@v2
+#   pattern, matching every other R workflow in this repo (R-CMD-check,
+#   test-coverage, pkgdown, etc.). That action handles DESCRIPTION
+#   parsing, Remotes: field resolution, system dependencies, caching,
+#   and (critically) GitHub authentication correctly. Earlier versions
+#   of this workflow tried to call remotes::install_deps() directly
+#   and hit 401 errors that turned out to be due to token plumbing
+#   that setup-r-dependencies handles transparently.
+#
 # Trigger:
 #   Manual only (workflow_dispatch). Use either the "Run workflow"
 #   button in the Actions tab, or:
@@ -49,67 +59,71 @@ permissions:
   contents: write
 
 concurrency:
-  # one phase0 run at a time per branch — prevents conflicting commits
   group: phase0-debug-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
   phase0:
     runs-on: ubuntu-latest
-    timeout-minutes: 350     # 350 min is safely under the 360 free-tier cap
+    timeout-minutes: 350
     env:
-      N_SUBJECTS:    ${{ inputs.n }}
-      ITER_WARMUP:   ${{ inputs.iter_warmup }}
-      ITER_SAMPLING: ${{ inputs.iter_sampling }}
-      CHAINS:        ${{ inputs.chains }}
-      CMDSTAN_VERSION: "2.38.0"
+      # Matches every other R workflow in this repo. Required for setup-r-dependencies
+      # to authenticate package downloads from GitHub (including UCD-SERG/serodynamics
+      # via the Remotes: field in DESCRIPTION).
+      GITHUB_PAT:       ${{ secrets.GITHUB_TOKEN }}
+      N_SUBJECTS:       ${{ inputs.n }}
+      ITER_WARMUP:      ${{ inputs.iter_warmup }}
+      ITER_SAMPLING:    ${{ inputs.iter_sampling }}
+      CHAINS:           ${{ inputs.chains }}
+      CMDSTAN_VERSION:  "2.38.0"
 
     steps:
       - name: Checkout PR branch
         uses: actions/checkout@v4
         with:
           ref: ${{ github.ref }}
-          # persist-credentials default true; needed for the later push.
 
       - name: Setup R
         uses: r-lib/actions/setup-r@v2
         with:
-          r-version: "release"
           use-public-rspm: true
 
+      - name: Install package dependencies
+        # This step handles:
+        #   - DESCRIPTION Imports / Depends / LinkingTo / Suggests
+        #   - Remotes: field (stan-dev/cmdstanr, UCD-SERG/serodynamics)
+        #   - System libraries (apt-get install)
+        #   - Caching (transparent)
+        # The same action and same auth setup are used by R-CMD-check.yaml.
+        uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: |
+            any::devtools
+            any::posterior
+            stan-dev/cmdstanr
+          needs: check
+
       - name: Cache cmdstan
         id: cache-cmdstan
         uses: actions/cache@v4
         with:
           path: ~/.cmdstan
           key: cmdstan-${{ runner.os }}-${{ env.CMDSTAN_VERSION }}
-
-      - name: System dependencies for R packages
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y libcurl4-openssl-dev libssl-dev libxml2-dev \
-                                  libfontconfig1-dev libharfbuzz-dev libfribidi-dev \
-                                  libfreetype6-dev libpng-dev libtiff5-dev libjpeg-dev
-
-      - name: Install R packages (CRAN + r-universe)
-        run: |
-          install.packages(c("devtools", "remotes", "posterior", "rlang"))
-          install.packages("cmdstanr",
-            repos = c("https://stan-dev.r-universe.dev",
-                      "https://cloud.r-project.org"))
-        shell: Rscript {0}
+          restore-keys: |
+            cmdstan-${{ runner.os }}-
 
       - name: Install cmdstan (only if cache miss)
         if: steps.cache-cmdstan.outputs.cache-hit != 'true'
         run: |
           cmdstanr::check_cmdstan_toolchain(fix = TRUE)
-          cmdstanr::install_cmdstan(version = Sys.getenv("CMDSTAN_VERSION"),
-                                    cores = 2)
+          cmdstanr::install_cmdstan(
+            version = Sys.getenv("CMDSTAN_VERSION"),
+            cores = 2
+          )
         shell: Rscript {0}
 
       - name: Register cmdstan path
         run: |
-          # Whether cached or freshly installed, point cmdstanr at it.
           paths <- list.files("~/.cmdstan", pattern = "^cmdstan-",
                               full.names = TRUE)
           stopifnot(length(paths) >= 1)
@@ -118,14 +132,14 @@ jobs:
           cat("cmdstan version:", cmdstanr::cmdstan_version(), "\n")
         shell: Rscript {0}
 
-      - name: Install shigella package + dependencies
-        run: |
-          # remotes handles the Remotes: field in DESCRIPTION
-          # (UCD-SERG/serodynamics, stan-dev/cmdstanr).
-          remotes::install_deps(".", dependencies = TRUE, upgrade = "never")
-          devtools::install(".", dependencies = FALSE, upgrade = "never",
-                            quick = TRUE, build = FALSE)
-        shell: Rscript {0}
+      - name: Install local shigella package
+        # Use R CMD INSTALL (base R, shell-level) instead of devtools::install
+        # or remotes::install_local. setup-r-dependencies@v2 doesn't guarantee
+        # remotes/devtools remain in the user library after it finishes, and
+        # devtools::install's `upgrade` arg expectations vary by version.
+        # R CMD INSTALL has no such dependencies — it's the lowest-level
+        # installer and always works.
+        run: R CMD INSTALL --no-multiarch --with-keep.source .
 
       - name: Run Phase 0 diagnostic
         id: run
@@ -137,7 +151,6 @@ jobs:
           mkdir -p "${OUT_DIR}"
 
           Rscript -e '
-            # Explicit %||% for R < 4.4 compatibility on GitHub runners
             `%||%` <- function(a, b) if (is.null(a)) b else a
 
             out_dir <- Sys.getenv("OUT_DIR")
@@ -165,14 +178,13 @@ jobs:
               NULL
             })
 
-            # Write a structured SUMMARY.txt that Claude can grep.
             summary_path <- file.path(out_dir, "SUMMARY.txt")
             lines <- c(
-              sprintf("RUN_ID: %s",   Sys.getenv("GITHUB_RUN_ID")),
-              sprintf("N: %d",        n),
+              sprintf("RUN_ID: %s",      Sys.getenv("GITHUB_RUN_ID")),
+              sprintf("N: %d",           n),
               sprintf("ITER_WARMUP: %d", iter_warmup),
               sprintf("ITER_SAMPLING: %d", iter_samp),
-              sprintf("CHAINS: %d",   chains)
+              sprintf("CHAINS: %d",      chains)
             )
 
             if (is.null(res)) {
@@ -195,7 +207,6 @@ jobs:
                 sprintf("TREEDEPTH: %d / %d",       sum(d$num_max_treedepth %||% 0L), total_iters)
               )
 
-              # Diagnostic verdict — Claude can read this directly.
               ess  <- s$ess_bulk %||% 0
               rhat <- s$rhat %||% Inf
               divg <- sum(d$num_divergent %||% 0L) / total_iters
@@ -216,26 +227,48 @@ jobs:
             cat("\n=== End SUMMARY.txt ===\n")
           ' 2>&1 | tee "${OUT_DIR}/run.log"
 
-          # Always succeed at the workflow level — the SUMMARY.txt
-          # carries the pass/fail signal.
           exit 0
         env:
           OUT_DIR: outputs/ci/phase0_n${{ inputs.n }}_run${{ github.run_id }}
+
+      - name: Run bimodality diagnostic
+        # Runs after the fit so the new RDS is available. Reads its own
+        # OUT_DIR from the positional argument we pass. Skips with a
+        # warning (not a fail) if the script or RDS is missing.
+        if: always()
+        env:
+          OUT_DIR: outputs/ci/phase0_n${{ inputs.n }}_run${{ github.run_id }}
+        run: |
+          set +e
+          if [ ! -f scripts/diagnostic_bimodality.R ]; then
+            echo "diagnostic_bimodality.R missing; skipping."
+            exit 0
+          fi
+          if [ ! -f "${OUT_DIR}/one_fit_n${N_SUBJECTS}_ci.rds" ]; then
+            echo "Fit RDS missing at ${OUT_DIR}; skipping diagnostic."
+            exit 0
+          fi
+          echo "Running diagnostic_bimodality.R on ${OUT_DIR}..."
+          Rscript scripts/diagnostic_bimodality.R "${OUT_DIR}" 2>&1 \
+            | tee "${OUT_DIR}/diagnostic_bimodality.log"
+          exit 0
 
       - name: Commit outputs back to the branch
         if: always()
         run: |
           set -euo pipefail
+          if [ ! -d outputs/ci ] || [ -z "$(ls -A outputs/ci 2>/dev/null)" ]; then
+            echo "outputs/ci/ is empty or missing; nothing to commit."
+            exit 0
+          fi
           git config user.name  "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git add outputs/ci/
           if git diff --cached --quiet; then
             echo "No new outputs to commit."
             exit 0
           fi
-          # [skip ci] prevents the push from triggering other workflows
           git commit -m "ci(phase0): n=${N_SUBJECTS} run ${GITHUB_RUN_ID} [skip ci]"
-          # Push to the branch we ran on
           BRANCH="${GITHUB_REF#refs/heads/}"
           git push origin "HEAD:${BRANCH}"
 

.gitignore

@@ -18,3 +18,5 @@ README_files
 shigella.Rcheck/
 shigella*.tar.gz
 shigella*.tgz
+commit.sh
+gitconfig

.lintr.R

@@ -1,9 +1,8 @@
 
-
-undesirable_functions <- 
-  lintr::default_undesirable_functions |> 
+undesirable_functions <-
+  lintr::default_undesirable_functions |>
   lintr::modify_defaults(
-    
+
     # following https://github.com/r-lib/devtools/blob/2aa51ef/.lintr.R:
     # Base messaging
     "message" = "use cli::cli_inform()",
@@ -18,32 +17,33 @@ undesirable_functions <-
     "cli_alert_info" = "use cli::cli_inform()",
     "cli_alert_success" = "use cli::cli_inform()",
     "cli_alert_warning" = "use cli::cli_inform()",
-    
+
     library = paste(
       "\nuse `::`, `usethis::use_import_from()`, or `withr::local_package()`",
       "instead of modifying the global search path.",
       "\nSee:\n",
       "<https://r-pkgs.org/code.html#sec-code-r-landscape> and\n",
       "<https://r-pkgs.org/testing-design.html#sec-testing-design-self-contained>",
-      "\nfor more details"
+      "\nfor more details."
     ),
-
-    structure = NULL
-    # see https://github.com/r-lib/lintr/pull/2227 and 
+
+    structure = NULL,
+    browser = NULL
+    # see https://github.com/r-lib/lintr/pull/2227 and
     # rebuttal https://github.com/r-lib/lintr/pull/2227#issuecomment-1800302675
-    
+
   )
 
 # define snake_case with uppercase acronyms allowed;
 # see https://github.com/r-lib/lintr/issues/2844 for details:
 withr::local_package("rex")
-snake_case_ACRO = rex::rex(
+snake_case_ACROs1 <- rex::rex(
   start,
   maybe("."),
-  some_of(lower, digit) %or% some_of(upper, digit),
+  list(some_of(upper), maybe("s"), zero_or_more(digit)) %or% list(some_of(lower), zero_or_more(digit)),
   zero_or_more(
     "_",
-    some_of(lower, digit) %or% some_of(upper, digit)
+    list(some_of(upper), maybe("s"), zero_or_more(digit)) %or% list(some_of(lower), zero_or_more(digit))
   ),
   end
 )
@@ -54,7 +54,7 @@ linters <- lintr::linters_with_defaults(
   lintr::redundant_equals_linter(),
   lintr::pipe_consistency_linter(pipe = "|>"),
   lintr::object_name_linter(
-    regexes = c(snake_case_ACRO = snake_case_ACRO)
+    regexes = c(snake_case_ACROs1 = snake_case_ACROs1)
   ),
   lintr::undesirable_function_linter(
     fun = undesirable_functions,
@@ -64,9 +64,22 @@ linters <- lintr::linters_with_defaults(
 
 # prevent warnings from lintr::read_settings:
 rm(undesirable_functions)
-rm(snake_case_ACRO)
+rm(snake_case_ACROs1)
 exclusions <- list(
   `data-raw` = list(
-    pipe_consistency_linter = Inf
-  )
+    pipe_consistency_linter = Inf,
+    undesirable_function_linter = Inf
+  ),
+  vignettes = list(
+    undesirable_function_linter = Inf,
+    object_name_linter = Inf
+  ),
+  "inst/examples" = list(
+    undesirable_function_linter = Inf
+  ),
+  "tests/testthat.R" = list(
+    undesirable_function_linter = Inf
+  ),
+  "quarto/mermaid-diagrams.qmd" = Inf
+
 )

DESCRIPTION

@@ -1,23 +1,34 @@
 Package: shigella
-Title: What the Package Does (One Line, Title Case)
-Version: 0.0.0.9008
+Title: Bayesian Modeling of Shigella Antibody Kinetics
+Version: 0.0.0.9009
 Authors@R: c(
     person("Kwan Ho", "Lee", , "ksjlee@ucdavis.edu", role = c("aut", "cre")),
     person("Douglas Ezra", "Morrison", , "demorrison@ucdavis.edu", role = c("aut"),
            comment = c(ORCID = "0000-0002-7195-830X")))
-Description: What the package does (one paragraph).
+Description: Tools for multivariate Bayesian hierarchical modeling of
+    antibody response trajectories following confirmed Shigella infection,
+    supporting kinetic parameter estimation and serosurveillance
+    applications via Stan (cmdstanr) backends.
 License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 URL: https://ucd-serg.github.io/shigella/
 Remotes:
+    stan-dev/cmdstanr,
     UCD-SERG/serodynamics
 Suggests:
+    cmdstanr,
     knitr,
+    posterior,
     rmarkdown,
     serodynamics (>= 0.0.0.9011),
     spelling,
     testthat (>= 3.0.0)
+Imports:
+    cli,
+    dplyr,
+    MASS,
+    tibble
 VignetteBuilder: knitr
 Depends:
     R (>= 3.5)

NAMESPACE

@@ -1,2 +1,10 @@
 # Generated by roxygen2: do not edit by hand
 
+export(postprocess_stan_output)
+export(prep_data_stan)
+export(prep_priors_stan)
+export(run_mod_stan)
+export(sim_correlated_case_data)
+export(write_status)
+importFrom(stats,median)
+importFrom(stats,rnorm)