cleverly.datasets.make_point_survival

cleverly.datasets.make_point_survival(n: int = 2000, *, seed: int | Generator | None = None, arms: int = 2, causes: int = 1, n_times: int = 5, censoring: bool = True, time_varying: bool = False, continuous_event_time: bool = False, dose: str | None = None, grid: Sequence[float] | None = None, end_of_study: bool = False, layout: str = 'long', cluster_size: int | None = None, hazard_scale: Mapping[int, float] | None = None, backend: Literal['pandas', 'polars'] | str | None = None) → tuple[Any, dict[str, float]]

A baseline treatment, a discrete-time event, and dropout at the visits.

The long layout has one row per unit with columns W1, W2, A (or D for a dose), time and event. event is 0 for censored and the cause code otherwise. A unit that drops out at node \(k\) is censored at the grid time \(g_{k-1}\), and a unit event-free at the end is censored at \(g_K\). The wide layout has C1..CK and Y1..YK (R1..RK and D1..DK for two causes), and L2..LK with time_varying=True. C1 is all ones.

Parameters:

nint

Number of units.

seedint, Generator, or None

Seed or NumPy random generator.

arms{2, 3}

The number of arms, when dose is None.

causes{1, 2}

The number of absorbing causes. Two causes are relapse (code 1) and death (code 2).

n_timesint

The number of nodes \(K\).

censoringbool

Whether units drop out at the visits.

time_varyingbool

Whether a binary covariate \(L_k\) enters the hazard at nodes k >= 2. Wide layout only.

continuous_event_timebool

Whether the event time is exponential given \((A, W)\). One cause, long layout only. The default grid is 0.5, 1, 2, 3 for four nodes.

dose{“discrete”} or None

"discrete" draws a dose on 0..5 in place of an arm.

gridsequence of float or None

The grid times of the long layout. None uses 1..K.

end_of_studybool

Whether the outcome is one binary Y after n_times censoring nodes. Wide layout only; every censoring node then has dropout.

layout{“long”, “wide”}

The frame layout.

cluster_sizeint or None

Rows per cluster. W1 and W2 are then drawn once per cluster and shared by its rows, which correlates the rows of a cluster and leaves the law of one row unchanged. The frame gains an id column. None leaves the rows independent.

hazard_scalemapping of int to float or None

A factor in (0, 1] on the all-cause hazard at each listed node, keyed by the node counted from one. It lowers the risk increment at that node, so a fit with error can report a curve that decreases there. None changes no draw. A discrete event time only.

backend{“pandas”, “polars”, “pyarrow”} or None, default=None

Dataframe backend.

Returns:

dataframe

The observations.

truthdict of str to float

The risk (risk_regimen), the incidence (cif_regimen) or the mean (ey_regimen) of every static arm arm0, arm1 (and arm2) at every node, and each arm’s contrast with arm0, under the names a fit reports for the regimens {"arm0": 0, "arm1": 1, ...}. Empty on a dose draw.

Examples

>>> from cleverly.datasets import make_point_survival
>>> frame, truth = make_point_survival(n=200, seed=0, n_times=3)
>>> list(frame.columns)
['W1', 'W2', 'A', 'time', 'event']
>>> round(truth["risk_regimen[arm1 @ t=3]"], 4)
0.2596