BREAKING: use population metadata for time references

[uriahf]

Status

Draft — intentional behavioral compatibility change. Do not merge as routine patch-level cleanup.

Goal

Use the internal evaluation metadata introduced in #369 to align time-dependent reference ownership with stable population identity.

Behavioral compatibility impact

This changes observable output for existing valid keyed-population inputs when distinct populations happen to have equal event risk at a horizon.

Current releases can collapse their prevalence/risk-dependent references to shared traces. After this change, those populations retain separate population-owned references. This can change reference trace names/counts, legend entries, color ownership, Plotly figure structure, and downstream snapshots that inspect those traces.

Function signatures and statistical formulas are unchanged, but this is still a potentially breaking behavioral change.

Implementation

The public time-dependent curve path now calls _build_evaluation_metadata() from #369 and determines reference ownership from the distinct population identities in that metadata.

• multiple models with shared outcome/time arrays have one shared population -> shared population-scoped references;
• keyed evaluation populations have distinct population identities -> population-owned references at every horizon, even when their numerical event risks coincide.

Reference values are still computed using the same cutoff-0 horizon-specific event risk. _replace_reference_data_times() accepts an explicit internal multiple_populations flag, with the previous risk-based inference retained as a fallback for callers without semantic context.

Tests

Regression coverage verifies equal-risk population ownership for ROC, precision-recall, gains, lift, decision curves, and interventions avoided, plus public PR behavior for keyed populations and multiple models sharing one population.

Release decision required

Before merging, decide explicitly how this behavioral change should be versioned and communicated.

Scope

Two-file diff on top of #369. No public function-signature changes, no statistical formula changes, no rtichoke_viz changes, and no unrelated refactoring.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-21 12:23 UTC