How it works

smoothstate estimates smooth state probabilities over a continuous predictor. In rtichoke, that predictor is usually a predicted probability.

Binary outcomes

For a binary state indicator Y, the target is

P(Y = 1 \mid p),

where p is the model prediction. smooth_binary_state() estimates this relationship with a local linear smoother and returns the curve as a Polars DataFrame.

Time-to-event outcomes

For survival calibration at horizon t, the target is

P\{Z(t)=1 \mid \hat p(t)=p\}.

The secondary-Cox smoother follows the calibration approach used in rtichoke:

x_i = \log\{-\log(1-\hat p_i)\},

then expands x_i with a 3-knot restricted cubic spline using knots at the 10th, 50th, and 90th percentiles. The resulting two-column spline basis is the sole predictor in a Cox proportional hazards model.

The fitted model has the form

h(u \mid x_i) = h_0(u)\exp\{\mathbf{s}(x_i)^T\boldsymbol\beta\},

and the smooth state probability at horizon t is

\widehat P\{Z(t)=1\mid p\} = 1 - \exp\left[-\widehat H_0(t)\exp\{\mathbf{s}(x)^T\widehat{\boldsymbol\beta}\}\right].

The restricted cubic spline allows the relationship between predicted and observed risk to be nonlinear while remaining linear in the tails.

Why a specialized implementation?

The Cox design matrix here has only one transformed predictor and one spline term. smoothstate exploits this narrow structure directly instead of constructing a general-purpose regression model. Runtime dependencies remain NumPy and Polars.