docs: update time-dependent calibration documentation with secondary Cox model

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)
+)
+```

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"`)