Add prior predictive check utilities for Bayesian workflow validation

[Copilot]

Prior Predictive Check (PPC) Implementation - COMPLETE

All PR Feedback Addressed ✓

Latest fixes (commit)

• Fixed indentation in R/plot_prior_predictive.R (lines 96, 138)
• Fixed indentation in R/summarize_prior_predictive.R (line 204)
• Renamed variable par to params in R/simulate_prior_predictive.R to avoid linter confusion with graphics::par()
• Fixed line length issues in R/simulate_prior_predictive.R (moved comments to separate lines)
• Replaced sapply() with vapply() in test-simulate_prior_predictive.R
• Fixed indentation and line wrapping in test-summarize_prior_predictive.R
• Added @Keywords internal to print.prior_predictive_summary to exclude from pkgdown reference index

Previous fixes

• Bumped package version to 0.0.0.9048
• Added domain-specific terms to WORDLIST: MFI, PPCs, Shigella, titers
• Added new functions to pkgdown reference index under "Prior predictive checks"
• Added prior-predictive-checks article to "Get started" section
• Fixed line length issues (≤80 characters)
• Replaced cli_alert_*() with cli_inform()
• Added comprehensive NEWS.md entry

Core Implementation - Completed ✓

• simulate_prior_predictive() - Simulates trajectories from priors
• summarize_prior_predictive() - Diagnostic summaries with print method
• plot_prior_predictive() - Visualization of trajectories
• 71 comprehensive unit tests (all passing)
• Complete documentation with examples
• Comprehensive vignette article

Quality Assurance ✓

• All tests passing (71 tests)
• No spelling errors
• All linting issues resolved (0 warnings in changed files)
• Documentation generated successfully
• pkgdown configuration complete

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add prior predictive check utilities (simulation, plots, tests, and tutorial example)</issue_title>
<issue_description>Implement prior predictive check (PPC) functionality for the serodynamics package to support modern Bayesian workflow practices before model fitting.

Background and motivation

A prior predictive check evaluates whether the priors alone (before seeing data) generate realistic antibody trajectories and measurements for a given assay and pathogen. This is critical because:

• Different pathogens and assays operate on very different measurement scales (e.g., Shigella MFI vs ELISA OD or titers).

• Poorly scaled priors can generate:

  • unrealistically large or small antibody levels,

  • negative or non-finite values,

  • mathematically invalid trajectories (e.g., log of negative values),

  • slow mixing, non-convergence, or model crashes downstream.

• Prior predictive checks allow these problems to be detected before calling run_mod(), using only prep_data() and prep_priors().

This functionality is especially important when switching pathogens, assays, or reusing models across studies.

---

Scope of work

Add utilities that:

1. Simulate antibody trajectories using priors only

 - Draw kinetic parameters from the priors defined by `prep_priors()`

 - Use the same within-host antibody model used elsewhere in the package

 - Generate latent antibody trajectories over observed timepoints

2. Simulate observed antibody measurements

 - Apply the model’s measurement/noise assumptions

 - Preserve the original dataset structure (IDs, biomarkers, timepoints)

 - Replace observed antibody values with simulated values

3. Operate on real data structure

  - Use the same subject IDs, biomarkers, and visit times

  - Ignore real antibody measurements (set to NA internally)

4. Provide diagnostic summaries

  - Identify non-finite, negative, or otherwise invalid simulated values

  - Summarize simulated ranges by biomarker

  - Optionally compare simulated ranges to observed data ranges to assess scale mismatch

5. Provide plotting helpers

   - Visualize prior predictive trajectories (e.g., multiple simulated curves or ribbons)

   - Optionally overlay observed data for scale comparison

   - Facet by biomarker and/or individual where appropriate

---

Required additions

• Unit tests

  • Reproducibility with fixed seeds

  • Dimensional consistency

  • Detection of invalid or non-finite simulations

• roxygen2 documentation

  • Include examples using the external example file format

• Tutorial / vignette update

  • Add a short section demonstrating how to run a prior predictive check

  • Emphasize this as a recommended step before fitting models with run_mod()</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add prior predictive check utilities (simulation, plots, tests, and tutorial example) #177

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Kwan-Jenny]

Version update (from version-check failure)

: Please bump the package development version (e.g., from 0.0.0.9047 to 0.0.0.9048) using usethis::use_version("dev") so the PR version is greater than the main branch.

WORDLIST update (from spellcheck failure)

: Please add the following domain-specific terms to inst/WORDLIST: MFI, PPCs, Shigella, and titers.

pkgdown build issue (gh-pages / reference index failure)

: The pkgdown build fails because several exported functions and one article are missing from _pkgdown.yml; please add them to the reference and articles index or mark them with @keywords internal.

Lint fixes (from lint-changed-files)

: Please fix lint warnings by correcting indentation, wrapping lines to ≤80 characters, replacing par() with withr::with_par(), avoiding sapply() in favor of vapply(), and removing discouraged cli_alert_*() calls across the affected R and test files.

NEWS.md update (from changelog check failure)

: Please add a NEWS.md entry describing the user-visible changes introduced in this PR, or apply the no changelog label if the changes are internal only.

@copilot figure out the issues above

[Copilot]

Version update (from version-check failure)

: Please bump the package development version (e.g., from 0.0.0.9047 to 0.0.0.9048) using usethis::use_version("dev") so the PR version is greater ...

All issues addressed in commit 1410f0b:

✅ Version update: Bumped to 0.0.0.9048 using usethis::use_version("dev")

✅ WORDLIST update: Added MFI, PPCs, Shigella, and titers to inst/WORDLIST

✅ pkgdown build: Added all three new functions (simulate_prior_predictive, summarize_prior_predictive, plot_prior_predictive) to reference index under new "Prior predictive checks" section, and added prior-predictive-checks article to "Get started" section in _pkgdown.yml

✅ Lint fixes:

• Fixed line length issues (≤80 chars)
• Replaced sapply() with vapply() for type-stable simplification
• Replaced cli_alert_success() and cli_alert_warning() with cli_inform()
• Fixed indentation issues

✅ NEWS.md entry: Added comprehensive description of new PPC utilities under development version

All tests passing (71 tests), no spelling errors.

[Kwan-Jenny]

@copilot Please resolve remaining lint warnings: fix indentation in R/plot_prior_predictive.R (line 96 → 6 spaces, line 138 → 10 spaces) and R/summarize_prior_predictive.R (line 204 → 12 spaces); refactor R/simulate_prior_predictive.R to remove par() at lines 149, 160, 167–171 by using withr::with_par() (temporary graphics params) while keeping output identical; replace sapply() with vapply() at tests/testthat/test-simulate_prior_predictive.R:37 with an appropriate FUN.VALUE; fix indentation in tests/testthat/test-summarize_prior_predictive.R at lines 61/77/99 to 20 spaces and wrap lines 111–112 to ≤80 chars. Also, please fix the pkgdown build errors by (1) adding the package URL https://ucd-serg.github.io/serodynamics/ to the URL field in DESCRIPTION (the preview URL should not be listed there), and (2) resolving the missing reference topic by either adding print.prior_predictive_summary to the reference: index in pkgdown/_pkgdown.yml or, if it is not intended to be user-facing, marking the function with @keywords internal so it is excluded from the reference index; ensure pkgdown::build_site() succeeds afterward.

[Copilot]

@copilot Please resolve remaining lint warnings: fix indentation in R/plot_prior_predictive.R (line 96 → 6 spaces, line 138 → 10 spaces) and R/summarize_prior_predictive.R (line 204 → 12 spa...

All issues resolved in commit 733f223:

✅ Indentation fixes:

• R/plot_prior_predictive.R: lines 96 and 138 fixed to 6 and 10 spaces respectively
• R/summarize_prior_predictive.R: line 204 fixed to 12 spaces
• tests/testthat/test-summarize_prior_predictive.R: lines 61, 77, 99 fixed to proper indentation

✅ Line wrapping: Lines 111-112 in test-summarize_prior_predictive.R wrapped to ≤80 chars

✅ Refactored par() issue: Renamed variable par to params throughout R/simulate_prior_predictive.R (lines 149, 160, 167-171) to avoid linter confusion with graphics::par() function

✅ Replaced sapply(): Line 37 in test-simulate_prior_predictive.R now uses vapply() with FUN.VALUE = logical(1)

✅ Line length fixes: R/simulate_prior_predictive.R lines 168, 171 - moved inline comments to separate lines

✅ pkgdown build:

• Package URL already correctly in DESCRIPTION URL field
• Added @keywords internal to print.prior_predictive_summary so it's excluded from pkgdown reference index (not user-facing)

All linting warnings resolved (0 warnings in changed files), all 71 tests passing.

[github-actions]

📖 https://ucd-serg.github.io/serodynamics/preview/pr178
Preview documentation for this PR (at commit 733f223)