Establish guarded experimental analysis methods

[choxos]

Summary

• Enforces fail-closed population, study-pair, multi-arm, and outcome validation for the two-stage methods.
• Defines the supported average conditional link-scale estimand and applies consistent estimability, tie, and ranking semantics.
• Records complete cMAIC bootstrap diagnostics and rejects unstable contrast estimates.
• Uses log-rate Poisson calculations with explicit predictive overflow handling and unavailable sampler diagnostics.
• Presents the package as experimental research software and limits published vignettes to the current interfaces.

Rationale

A disconnected component bridge can be algebraically identified while combining incompatible population estimands or relying on scientifically unsupported transport assumptions. The public interfaces expose these boundaries, reject invalid paths by default, and retain explicit research-only overrides for sensitivity work.

User impact

Exploratory two-stage analyses that retain aggregate-only edges require allow_experimental_bridge = TRUE. Marginal standardized cML-NMR effects remain unavailable and are rejected explicitly. Returned effects, rankings, bootstrap diagnostics, and sampler status carry clearer estimand and validity metadata.

Validation

• Complete standard test suite passed with 19 intentional CRAN skips and four expected adversarial-fixture warnings.
• Focused methodology, bootstrap, Poisson, and two-stage gate suites passed.
• Fresh source package and vignettes built successfully.
• R CMD check --no-manual completed with Status: OK.

[Copilot]

Pull request overview

This PR hardens cpaic’s “experimental” two-stage analysis paths by introducing fail-closed methodological gates, clarifying the supported estimand (“average conditional link-scale” at target covariate means), and expanding diagnostics (bootstrap + sampler + Poisson predictive overflow) so unstable or scientifically incoherent bridges are rejected by default and explicitly recorded when overridden.

Changes:

• Adds explicit two-stage bridge gating (fail-closed by default) and records override reasons/retained edges when allow_experimental_bridge = TRUE.
• Standardizes estimand semantics across reporting/ranking APIs and updates downstream docs/man pages accordingly.
• Improves diagnostics: cMAIC bootstrap failure bookkeeping, sampler diagnostic “passed/failed/unknown” states, and Poisson predictive overflow sentinels with fail-closed predictive checks.

Reviewed changes

Copilot reviewed 64 out of 71 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
vignettes/survival-outcomes.Rmd.orig	Marks vignette source as archived; opts into experimental bridge in examples.
vignettes/survival-outcomes.html	Adds prominent “archived output” banner to rendered HTML.
vignettes/precompile.R	Keeps regeneration path for archived vignettes; changes intermediate naming/output handling.
vignettes/cpaic-methods.Rmd	Adds “research use only” disclaimer and updates methodology/estimand explanations.
vignettes/cpaic-intro.Rmd	Adds “research use only” disclaimer and reframes two-stage examples as explicit opt-in.
vignettes/cpaic-disconnected-myeloma.Rmd.orig	Marks vignette source as archived.
vignettes/cpaic-disconnected-myeloma.html	Adds prominent “archived output” banner to rendered HTML.
vignettes/count-outcomes.Rmd.orig	Marks vignette source as archived; opts into experimental bridge in examples.
vignettes/count-outcomes.html	Adds prominent “archived output” banner to rendered HTML.
vignettes/continuous-outcomes.Rmd.orig	Marks vignette source as archived; opts into experimental bridge in examples.
vignettes/continuous-outcomes.html	Adds prominent “archived output” banner to rendered HTML.
vignettes/binary-outcomes.Rmd.orig	Marks vignette source as archived; opts into experimental bridge in examples.
vignettes/binary-outcomes.html	Adds prominent “archived output” banner to rendered HTML.
vignettes/_survival-outcomes.Rmd	Adds “archived output” banner to intermediate knitted vignette.
vignettes/_cpaic-disconnected-myeloma.Rmd	Adds “archived output” banner to intermediate knitted vignette.
vignettes/_count-outcomes.Rmd	Adds “archived output” banner to intermediate knitted vignette.
vignettes/_continuous-outcomes.Rmd	Adds “archived output” banner to intermediate knitted vignette.
vignettes/_binary-outcomes.Rmd	Adds “archived output” banner to intermediate knitted vignette.
tests/testthat/test-validation.R	Updates tests to explicitly opt into experimental bridge where required.
tests/testthat/test-two-stage-gate.R	New coverage for two-stage gating, override recording, and edge validation.
tests/testthat/test-regression.R	Ensures regression failures are still surfaced when experimental override is enabled.
tests/testthat/test-poisson-overflow.R	New coverage for Poisson predictive overflow metadata and fail-closed checks.
tests/testthat/test-paic.R	Updates anchored PAIC tests to reflect explicit opt-in and new gate behavior.
tests/testthat/test-methodology-safeguards.R	New safeguards tests: target validation, ranking tie rules, estimand enforcement, KM behavior.
tests/testthat/test-maic-bootstrap-validity.R	New bootstrap diagnostics and failure-code coverage for cMAIC.
tests/testthat/test-cmlnmr.R	Extends cML-NMR tests to assert Poisson replication overflow state.
README.md	Rewrites positioning as experimental research software; documents gates/estimand limitations.
R/sensitivity.R	Aligns “target means” semantics and stores estimand metadata in fragility outputs.
R/ranks.R	Refactors ranking engine; enforces supported estimand; consistent tie-handling + failure retention in curves.
R/plot.R	Updates labeling to “target effect-modifier means” and registers additional ggplot vars.
R/plot-mlnmr.R	Updates ranking/estimability plotting for target-mean semantics; fixes Poisson fitted mean calculation; KM delayed entry + labeling.
R/fit_checks.R	Adds two-stage edge validation + bridge gate implementation recording retained edges/reasons.
R/estimability.R	Renames/clarifies estimability to target-mean average-conditional semantics; stores estimand metadata.
R/effects.R	Adds estimand validation helper; updates relative_effects() columns/metadata; target-mean handling + diagnostics attrs.
R/diagnostics.R	Clarifies additivity-test limitations for cML-NMR in disconnected settings.
R/data.R	Updates dataset docs to “target mean” framing.
R/data_setup.R	Strengthens network input validation (labels, missing values, family-specific outcome constraints).
R/cstc.R	Adds two-stage planning + gating + print exposure of gate/override; allows explicit opt-in and IPD-only permission.
R/cpaic-package.R	Updates package-level description/disclaimers and documents gate behavior.
R/cmlnmr.R	Adds Poisson overflow metadata/state; improves sampler diagnostic extraction + status; enforces estimand in outputs.
R/bayesian_diagnostics.R	Adds Poisson overflow summarization + fail-closed predictive checks; aligns target-mean semantics.
R/backend.R	Makes sampler diagnostics extraction fail-closed with explicit “unavailable” metadata instead of silent zeros.
NEWS.md	Documents new safeguards, estimand restrictions, diagnostics, and vignette publication changes.
man/relative_effects.Rd	Updates usage/return columns and documents supported estimand.
man/rank_probs.Rd	Adds set and estimand; updates semantics to target means.
man/rank_curve.Rd	Updates semantics and documents failure rows.
man/prior_sensitivity.Rd	Updates newdata semantics to target means.
man/prior_predictive_check.Rd	Documents Poisson overflow sentinels and fail-closed behavior.
man/plot.cpaic_ranks.Rd	Updates title to average-conditional hierarchy at target means.
man/plot.cpaic_rank_probs.Rd	Updates details to target-mean semantics.
man/plot_rank_curve.Rd	Updates title/description to target-mean semantics.
man/plot_estimability.Rd	Updates title/description to target-mean semantics.
man/geom_km.Rd	Documents right-censoring-only support and delayed entry + reconstructed AgD labeling.
man/estimable_effects_at.Rd	Updates title/description to average-conditional target-mean estimand.
man/cstc.Rd	Adds experimental gate/opt-in and IPD-only-study permission parameters + updated semantics.
man/cpaic-package.Rd	Updates package description to experimental positioning + gate/estimand constraints.
man/cpaic_ranks.Rd	Adds estimand and updates semantics + warnings to target means.
man/cpaic_network.Rd	Documents two-stage survival 0/1 event coding contract.
man/cpaic_bin_ipd.Rd	Updates target description to “target mean”.
man/cpaic_bin_agd.Rd	Updates docs to “target-matched” language.
man/component_effects.Rd	Adds estimand argument docs for cML-NMR component effects.
man/cmlnmr.Rd	Updates semantics (target means, estimand) and clarifies survival/plot_integration_error scope.
man/cmaic.Rd	Adds gate/opt-in parameters, bootstrap validity rule docs, and clarifies incoherence risks.
man/bridge_fragility.Rd	Updates target-mean semantics and clarifies estimand.
inst/stan/cpaic_poisson.stan	Switches to log-rate AgD likelihood; adds RNG overflow sentinels + per-draw overflow counts.
DESCRIPTION	Repositions package as experimental; removes R.rsp vignette plumbing from build metadata.
.Rbuildignore	Excludes archived vignette intermediates/outputs from package builds.
.gitignore	Adjusts ignored dev guidance artifacts.
.github/workflows/pkgdown.yaml	Removes site-stripping step for no-longer-present internal pages.
_pkgdown.yml	Removes archived example articles from published site; updates reference-section descriptions.

Files not reviewed (6)

• man/bridge_fragility.Rd: Generated file
• man/cmaic.Rd: Generated file
• man/cmlnmr.Rd: Generated file
• man/component_effects.Rd: Generated file
• man/cpaic-package.Rd: Generated file
• man/cpaic_bin_agd.Rd: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a4b2003fcd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Derive median ranks from the split tie distribution

When treatments or components are exactly tied, ranked$ranks assigns every tied element the average occupied rank, while ranked$probabilities splits its mass across the occupied integer ranks. Taking the median of the former can therefore disagree with the rank distribution returned by rank_probs(); for example, a structurally tied pair that occupies ranks 1–2 in most draws can report median_rank = 1.5 even when more than half of its split probability lies at rank 2. Compute the median from ranked$probabilities, as is already done for p_best and mean_rank, so all summaries use the promised tie rule.

Useful? React with 👍 / 👎.