Add Gaussian partner-dependence predictive checks

[Pascal-Kueng]

Summary

• Add simulate_dyad_responses() to generate plug-in response datasets from cross-sectional Gaussian glmmTMB models.
• Add check_partner_dependence() to compare observed and simulated partner variation and association.
  • Support model-centred and raw responses, meaningful member roles, and label-invariant summaries for interchangeable members.
  • Add help pages, examples, plots, tests, developer validation, and a known-population outer simulation study.

Scope and interpretation

This PR supports unweighted cross-sectional Gaussian identity-link glmmTMB models without zero inflation. The fitted parameters and fitted-row design remain fixed, while random effects and Gaussian errors are newly generated for each simulated dataset.

This is a descriptive plug-in predictive reference. The model is not refitted, parameter uncertainty is not included, and observations are not held out. Observed positions and middle 95% ranges are descriptive guides, not p-values or calibrated confidence intervals.

The check is likely most useful when the model makes a simplifying assumption that could be wrong (for example, no remaining partner relationship or equal variation across roles). When the model freely estimates the same feature from these data, close agreement is expected (learned patterns are reproduced).

For exchangeable dyads, the deterministic summary follows Woody and Sadler's (2005) between-/within-dyad decomposition. The observed-versus-simulated comparison adapts the principle from Gelman, Meng, and Stern (1996). It is not a posterior predictive distribution.

Review focus

Conceptual questions about the diagnostic target and interpretation are collected in Discussion #21.

• Column-first tidy evaluation (.data / .env) and {{ }} wrapper forwarding
• Fitted-row alignment, pairing, and omitted-row handling
• Whether the interpretation is clear and appropriately cautious
• Readability of the API, output, and documentation

Review cleanup

• Resolve bare identifiers in the fitted model frame before the calling environment; retain quoted names and explicit external vectors.
• Share paired-statistic, label, and reference-summary helpers, and apply one calculation to observed and simulated responses. The refactor at ab87b04 removed 39 R-source lines while preserving the Gaussian formulas and result schema.
• Cover name collisions, explicit pronouns, embraced wrappers, and single-simulation dimensions.
• Add plain-language source comments explaining reusable objects, their shapes, and how later functions use them.
• Lead the guide and help pages with quick starts, examples, and interpretation. Put object shapes, tidy-evaluation programming, and implementation details later; use the same practical-first structure in both worked examples.
• Preserve the existing prototype branches as references. Build fresh non-Gaussian cross-sectional work first, then Gaussian ILD on the accepted combined foundation. Keep family restrictions and undefined-statistic policies explicit.

Validation

Documentation cleanup at fadb3b6:

• Synchronized the three Rd help pages with their revised source documentation; checked whitespace, section order, and local documentation links.
• Source comparisons confirmed that executable R code, existing help-example code, and all 44 R chunks in the two worked examples are unchanged. The runnable help example gained only a note about using fewer simulations for speed.
• New R CMD checks, coverage, and the documentation build are running on this commit. R is unavailable locally, so R-based validation is delegated to CI.

Cleanup validation at ab87b04:

• R CMD check passed on all five platforms.
• The coverage workflow passed: 1,502 expectations, zero failures and skips, and 94.72% overall coverage. Identifier-helper coverage is 100%.
• CI records one dependency-loading warning: glmmTMB was built with TMB 1.9.21 while the runner has TMB 1.9.25. This is reported separately from the code checks; no dependency versions were changed in this cleanup.
• The pkgdown documentation workflow passed.

Earlier validation of the unchanged numerical design (not rerun for this cleanup):

• The independent Woody–Sadler/Dingy validation report renders with all assertions passing.
• In the outer simulation study, all 7,000 fitted-model runs completed without warnings, convergence problems, or check errors.
• The known-truth control behaved as expected: 4–7% of summaries fell outside the middle 95%, and position SDs were 0.275–0.290 versus 0.289 expected.
• Flexible correct fits clustered tightly near the middle, showing why close agreement is not independent evidence of good fit. The deliberately wrong assumptions were flagged in the expected direction in 84.4–96.8% of datasets with 50 dyads and 100% with 200 dyads.

[Pascal-Kueng]

This can probably be shortened. The basic idea is:

• apply criteria to simulation
• apply criteria to prediction
• plot