From b518effc792cf24d66b8aa1f826b3e23afc15771 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Mon, 17 Aug 2026 07:34:33 +0000
Subject: [PATCH] docs: update calibration curves guide with secondary Cox
 model

Co-authored-by: uriahf <11351434+uriahf@users.noreply.github.com>
---
 .../index.qmd                                 | 39 +++++++++++++++++++
 user_guide/05-calibration-curves.qmd          | 13 +++++--
 2 files changed, 49 insertions(+), 3 deletions(-)
 create mode 100644 examples/posts/calibration_with_censored_observations/index.qmd

diff --git a/examples/posts/calibration_with_censored_observations/index.qmd b/examples/posts/calibration_with_censored_observations/index.qmd
new file mode 100644
index 00000000..1df0b884
--- /dev/null
+++ b/examples/posts/calibration_with_censored_observations/index.qmd
@@ -0,0 +1,39 @@
+---
+title: "Calibration Curves with Censored Observations"
+author: "Uriah Finkel"
+date: "2025-12-20"
+categories: [calibration, survival, time-to-event]
+draft: false
+---
+
+Evaluating model calibration in time-to-event settings presents unique challenges when observations are censored prior to the time horizon of interest.
+
+## Time-Dependent Calibration Curves
+
+To construct a smooth time-dependent calibration curve at prediction horizon $t$, `rtichoke` fits a secondary Cox proportional hazards model (Austin, Harrell & van Klaveren 2020; McLernon et al. 2023) on the complementary log-log transformed predicted probabilities:
+
+$$x_i = \log\left(-\log(1 - \hat{p}_i)\right)$$
+
+The secondary Cox model relates observed event times to $x_i$:
+
+$$h(t \mid x_i) = h_0(t) \exp(\beta x_i)$$
+
+The estimated actual risk at horizon $t$ across predicted probabilities $\hat{p}$ is then calculated as:
+
+$$\hat{F}(t \mid \hat{p}) = 1 - \hat{S}_0(t)^{\exp(\beta x)}$$
+
+## Example usage in `rtichoke`
+
+```python
+import rtichoke as rk
+
+fig = rk.create_calibration_curve_times(
+    probs={"Model A": probs_a},
+    reals=reals,
+    times=times,
+    fixed_time_horizons=[5.0],
+    heuristics_sets=[{"censoring_heuristic": "adjusted", "competing_heuristic": "adjusted_as_negative"}],
+    calibration_type="smooth",
+    smooth_method="secondary_cox",  # or "local_aj" (default)
+)
+```
diff --git a/user_guide/05-calibration-curves.qmd b/user_guide/05-calibration-curves.qmd
index 72fdcd99..954efa0e 100644
--- a/user_guide/05-calibration-curves.qmd
+++ b/user_guide/05-calibration-curves.qmd
@@ -58,10 +58,17 @@ When `calibration_type="smooth"`, `create_calibration_curve_times` supports thre
 
 ### 2. Secondary Cox Model (`smooth_method="secondary_cox"`)
 
-**Austin, Harrell & McLernon original time-to-event method** (Austin et al. 2020 / McLernon et al. 2023):
+To construct a smooth time-dependent calibration curve at prediction horizon $t$, `rtichoke` fits a secondary Cox proportional hazards model (Austin, Harrell & van Klaveren 2020; McLernon et al. 2023) on the complementary log-log transformed predicted probabilities:
 
-- Fits a secondary cause-specific Cox proportional hazards model on the complementary log-log transformed predictions ($\log(-\log(1-p))$).
-- Evaluates predicted cumulative incidence at horizon $t$ across the grid of predicted probabilities.
+$$x_i = \log\left(-\log(1 - \hat{p}_i)\right)$$
+
+The secondary Cox model relates observed event times to $x_i$:
+
+$$h(t \mid x_i) = h_0(t) \exp(\beta x_i)$$
+
+The estimated actual risk at horizon $t$ across predicted probabilities $\hat{p}$ is then calculated as:
+
+$$\hat{F}(t \mid \hat{p}) = 1 - \hat{S}_0(t)^{\exp(\beta x)}$$
 
 ### 3. Pseudo-Values LOWESS (`smooth_method="pseudo_values"`)