Expand “Before You Validate” beyond fixed time horizons

[uriahf]

Context

The first version of Before You Validate is intentionally focused on declaring fixed time horizons for time-to-event validation. The broader draft also covered reference groups, prediction stratification, censoring assumptions, competing-event estimands, and reporting guidance. Those topics should be added incrementally after the fixed-horizon guide is reviewed.

Proposed follow-up sections

1. Define reference groups

Explain how the keys and shapes of probs, reals, and times encode:

• one model in one population;
• several models in one population; and
• one model across several populations.

Include compact, runnable input examples and guidance on interpretable model/cohort/site labels.

2. Choose prediction stratification

Compare:

• probability_threshold for absolute-risk decisions and individual treatment trade-offs; and
• ppcr for rank-based decisions under a capacity constraint.

Document that these answer different decision questions. Restore a concise treat-all/treat-none explanation where it directly supports interpretation, while moving lengthy methodological diagrams to the blog.

3. Choose a censoring heuristic

Document:

• excluded; and
• adjusted.

State the target quantity, the independent-censoring assumption, and the limitations under informative loss to follow-up. Link to a deeper methodological source and to an interactive blog walkthrough.

4. Choose a competing-event estimand

Compare:

• excluded;
• adjusted_as_censored;
• adjusted_as_negative; and
• adjusted_as_composite.

For every choice, state the scientific question answered—not only the mechanical recoding. Emphasize that the composite option changes the endpoint and that censoring asks a hypothetical question.

5. Add sensitivity-analysis guidance

Show how to pass multiple defensible entries in heuristics_sets. Explain that these should be pre-specified and reported as alternative estimands rather than selected after viewing the most favorable result.

6. Add a complete pre-validation checklist

Cover:

• target population and reference groups;
• decision rule and prediction strata;
• horizon units and clinical meaning;
• event-code convention;
• censoring assumptions;
• competing-event interpretation; and
• planned sensitivity analyses.

7. Connect documentation, blog, and API reference

Keep the official guide concise and action-oriented. Put detailed Aalen–Johansen derivations, internal processing steps, and advanced interactive explorers in the rtichoke Python blog. Cross-link both surfaces to prepare_performance_data_times().

Acceptance criteria

• each section answers a concrete choice users must make before validation;
• examples use only public rtichoke APIs;
• no unresolved TODOs or obsolete internal helper imports;
• terminology and argument values match the current implementation;
• all Quarto pages render successfully;
• interactive components reuse the merged uriahtalks Quarto extension rather than duplicating JavaScript/OJS cells.