Survival Analysis¶

Kaplan-Meier estimation, log-rank test (G-rho family), Cox proportional hazards (CPU), and discrete-time survival models (GPU-accelerated).

Survival analysis.

Public API:: kaplan_meier(time, event, …) -> KMSolution survdiff(time, event, group, …) -> LogRankSolution coxph(time, event, X, …) -> CoxSolution # CPU only discrete_time(time, event, X, …) -> DiscreteTimeSolution # GPU accelerated

pystatistics.survival.coxph(time, event, X, *, terms=None, names=None, strata=None, ties='efron', tol=1e-09, max_iter=20, conf_level=0.95)[source]¶

Cox proportional hazards model.

CPU only — no backend parameter. Matches R’s survival::coxph().

Parameters:

time (array-like) – Time to event or censoring.
event (array-like) – Event indicator (1=event, 0=censored).
X (array-like or DataSource) – Covariate matrix (n, p). No intercept — Cox model has no intercept. When terms is given, X is instead the data source (a DataSource or column mapping) from which the term spec pulls columns.
terms (sequence or None) – Structured term spec for categorical predictors and interactions (bare column names, C(name, ref=…), or tuples of those). When given, the covariate matrix is built from X (the source) with no intercept, and the expanded column labels are used automatically. Mutually exclusive with names.
strata (array-like or None) – Strata labels for stratified Cox (not yet implemented).
ties (str) – Method for handling tied event times: “efron” (default) or “breslow”.
tol (float) – Convergence tolerance for Newton-Raphson.
max_iter (int) – Maximum Newton-Raphson iterations.
conf_level (float) – Confidence level for .conf_int (default 0.95). Wald intervals on the coefficient (log-hazard-ratio) scale; exp(.conf_int) gives hazard- ratio intervals.
names (list[str] | None)

Return type:

CoxSolution

pystatistics.survival.discrete_time(time, event, X, *, names=None, intervals=None, backend=None, conf_level=0.95)[source]¶

Discrete-time survival via person-period logistic regression.

GPU-accelerated — delegates to regression.fit(family=’binomial’).

Parameters:

time (array-like) – Time to event or censoring.
event (array-like) – Event indicator (1=event, 0=censored).
X (array-like) – Covariate matrix (n, p). No intercept — interval dummies serve as the intercept.
intervals (array-like or None) – Time interval boundaries. If None, uses unique event times.
backend (str or None) – Backend for the person-period logistic regression, forwarded to regression.fit. Default None → ‘cpu’ (the R-reference path). Explicit values: “cpu” (float64), “gpu” (float32, CUDA or Apple Silicon), “gpu_fp64” (float64, CUDA only — the exact double-precision GPU path), or “auto” (GPU-fp32 if CUDA present, else CPU).
conf_level (float) – Confidence level for .conf_int (default 0.95). Wald intervals on the covariate coefficient scale; exp(.conf_int) gives discrete-time hazard-ratio intervals.
names (list[str] | None)

Return type:

DiscreteTimeSolution

pystatistics.survival.kaplan_meier(time, event, *, strata=None, conf_level=0.95, conf_type='log')[source]¶

Kaplan-Meier survival curve estimation.

Matches R’s survival::survfit(Surv(time, event) ~ 1).

Parameters:

time (array-like) – Time to event or censoring.
event (array-like) – Event indicator (1=event, 0=censored).
strata (array-like or None) – Strata labels for stratified KM (not yet implemented).
conf_level (float) – Confidence level for CI (default 0.95).
conf_type (str) – CI transformation: “log” (R default), “plain”, “log-log”.

Return type:

KMSolution

pystatistics.survival.survdiff(time, event, group, *, rho=0.0)[source]¶

Log-rank test (and G-rho family).

Matches R’s survival::survdiff().

Parameters:

time (array-like) – Time to event or censoring.
event (array-like) – Event indicator (1=event, 0=censored).
group (array-like) – Group labels (e.g. treatment vs control).
rho (float) – G-rho weight parameter. rho=0 (default) gives the standard log-rank test. rho=1 gives Peto & Peto / Gehan-Wilcoxon.

Return type:

LogRankSolution

class pystatistics.survival.CoxSolution(_result, _names=None)[source]¶

Bases: SolutionReprMixin

Cox proportional hazards solution.

Properties mirror R’s coxph() output.

Parameters:

_result (Result[CoxParams])
_names (tuple[str, ...] | None)

property coefficients¶

property coef: dict[str, float]¶: Named coefficient mapping (like R’s coef()).

property hr: dict[str, float]¶: Named hazard ratio mapping (exp(coef)).

property hazard_ratios¶

property standard_errors¶

property z_values¶

property p_values¶

property loglik¶

property concordance: float¶

property n_events: int¶

property n_observations: int¶

property n_iter: int¶

property converged: bool¶

property ties: str¶

property conf_level: float¶: Confidence level for conf_int (default 0.95).

property conf_int¶

Wald confidence intervals for the coefficients, shape (p, 2).

coef ± z * se on the coefficient (log-hazard-ratio) scale, where z is the normal quantile for conf_level (Cox inference is asymptotic-normal). exp(conf_int) gives hazard-ratio intervals.

property backend_name: str¶

property timing¶

property warnings: tuple[str, ...]¶

summary()[source]¶

R-style summary of Cox PH fit.

Return type:: str

class pystatistics.survival.DiscreteTimeSolution(_result, _names=None, _conf_level=0.95)[source]¶

Bases: SolutionReprMixin

Discrete-time survival model solution.

Properties mirror the logistic regression on person-period data.

Parameters:

_result (Result[DiscreteTimeParams])
_names (tuple[str, ...] | None)
_conf_level (float)

property coefficients¶

property coef: dict[str, float]¶: Named coefficient mapping.

property hr: dict[str, float]¶: Named hazard ratio mapping (exp(coef)).

property standard_errors¶

property z_values¶

property p_values¶

property conf_level: float¶: Confidence level for conf_int (default 0.95).

property conf_int¶

Wald confidence intervals for the covariate coefficients, shape (p, 2).

coef ± z * se on the (discrete-time log-hazard) coefficient scale, with the normal quantile for conf_level (the person-period logistic fit is asymptotic-normal). exp(conf_int) gives discrete-time hazard-ratio intervals.

property hazard_ratios¶

property baseline_hazard¶

property interval_labels¶

property person_period_n: int¶

property n_intervals: int¶

property n_observations: int¶

property n_events: int¶

property glm_deviance: float¶

property glm_aic: float¶

property converged: bool¶

Whether the person-period binomial IRLS converged.

False means the underlying logistic fit hit the iteration cap (or, for an all-censored design with no events, that no fit ran) — treat the coefficients as unreliable. Mirrors CoxSolution.converged.

property n_iter: int¶

IRLS iterations used by the person-period binomial GLM.

Mirrors CoxSolution.n_iter. A value at the solver’s iteration cap alongside converged == False indicates a fit that did not settle.

property backend_name: str¶

property timing¶

property warnings: tuple[str, ...]¶

summary()[source]¶

Summary of discrete-time survival model.

Return type:: str

class pystatistics.survival.KMSolution(_result)[source]¶

Bases: SolutionReprMixin

Kaplan-Meier survival curve solution.

Properties mirror R’s survfit() output.

Parameters:: _result (Result[KMParams])

property time¶: Unique event times.

property survival¶: S(t) at each event time.

property n_risk¶: Number at risk just before each event time.

property n_events¶: Number of events at each event time.

property n_censored¶: Number censored in each interval.

property se¶: Greenwood standard error of S(t).

property standard_errors¶: Greenwood standard error of S(t) (uniform-accessor alias of se).

property ci_lower¶: Lower confidence bound for S(t).

property ci_upper¶: Upper confidence bound for S(t).

property conf_int¶

Confidence band for S(t) at each event time, shape (m, 2).

Columns are [lower, upper] — the uniform-accessor form of ci_lower / ci_upper (which remain available).

property conf_level: float¶

property conf_type: str¶

property n_observations: int¶

property n_events_total: int¶

property median_survival: float | None¶: Median survival time (smallest t where S(t) <= 0.5).

property backend_name: str¶

property timing¶

property warnings: tuple[str, ...]¶

summary()[source]¶

R-style summary of Kaplan-Meier fit.

Return type:: str

class pystatistics.survival.LogRankSolution(_result)[source]¶

Bases: SolutionReprMixin

Log-rank test solution.

Properties mirror R’s survdiff() output.

Parameters:: _result (Result[LogRankParams])

property statistic: float¶

property df: int¶

property p_value: float¶

property n_groups: int¶

property observed¶

property expected¶

property n_per_group¶

property rho: float¶

property group_labels¶

property backend_name: str¶

property timing¶

property warnings: tuple[str, ...]¶

summary()[source]¶

R-style summary of log-rank test.

Return type:: str