Add stratified marginal curve overlay to plot_predicted_curve()

[Copilot]

plot_predicted_curve() previously only supported individual-level conditional predictions. This adds support for overlaying marginal ("new person") predictions across strata in a single panel.

Changes

• New parameter overlay_strata: When TRUE with ids = "newperson", overlays marginal predictions for each stratum (e.g., age groups, disease types) with distinct colors
• Stratification detection: Automatically detects and uses Stratification column from sr_model when present
• Visual separation: Each stratum gets its own color for median curves and credible intervals, with legend showing stratum labels
• Compatible with existing options: Works with log_y, show_all_curves, xlim, etc.

Usage

# Overlay marginal predictions for typhi vs paratyphi strata
plot_predicted_curve(
  model          = nepal_sees_jags_output,
  ids            = "newperson",
  antigen_iso    = "HlyE_IgA",
  overlay_strata = TRUE,
  show_quantiles = TRUE
)

Defaults to overlay_strata = FALSE preserving existing behavior for individual subject plots.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add Support for Overlaying Stratified Marginal Curves in plot_predicted_curve()</issue_title>
<issue_description>Description:

Summary:
This issue proposes extending the plot_predicted_curve() function to overlay marginal (“new person”) model predictions for different strata (e.g., age groups) in the same panel. This will improve visualization of stratified model fits from SRM outputs.

Motivation:

• Current implementation only supports conditional (individual-level) predictions.

• Comparing marginal model fits across strata (e.g., <5 vs ≥5 years) on the same plot would help assess group-level differences in antibody kinetics.

• Suggested by Sam and supported by Kristen and Ezra during the 07.30.2025 meeting.

Proposed Features:

• Overlay median marginal curves for each stratum using different colors or line types.

• Optionally overlay observed individual data in the background (optional).

• Ensure compatibility with stratified SRM outputs (i.e., one new_person per stratum).

• Maintain current behavior when no stratification is used.

Implementation Notes:

• Separate logic for:

  • Observed data (optional)

  • Marginal predicted values from new_person

• Add new arguments to control stratified marginal overlay (e.g., strat_overlay = TRUE)

• Reuse logic from serocalculator or internal helpers to minimize duplication

Development Plan:

• Implement in a new PR, separate from PR Add multi-ID faceting support to plot_predicted_curve and update tests/examples #120

• Collaborate with Sam and Kristen for design and review

• Add visual test cases with multiple strata

</issue_description>

<agent_instructions>@copilot, please check whether the current plot_predicted_curve.r file already addresses this issue. If the function does not include this functionality or description, please create a new PR and work on implementing it.</agent_instructions>

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

• Fixes Add Support for Overlaying Stratified Marginal Curves in plot_predicted_curve() #128

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.