cleverly.TimeToEvent

class cleverly.TimeToEvent(time: str, event: str, treatment: str, baseline: Sequence[str], grid: Sequence[float] | None = None, causes: Mapping[int, str] | None = None, cluster: str | None = None, weights: str | None = None, weights_type: Literal['probability'] = 'probability', weights_estimated: bool = False, time_varying: None = None, continuous_treatment: bool = False, treatment_probabilities: Any = None, treatment_support: Any = None, dose_atoms: Sequence[float] = ())

Declare a baseline treatment with one follow-up time and one event code per unit.

The data hold one row per unit. The time is binned onto a grid \(0 = g_0 < g_1 < \dots < g_K\), node \(k\) covers \((g_{k-1}, g_k]\), and the treatment is one decision held over every node. cleverly.longitudinal.LongitudinalData.from_time_to_event() states the binning rules and the refusals. The estimand is a risk or a cumulative incidence at the grid times, as for a survival LongitudinalTreatment. At a grid time before which no follower of a regimen had the event, the risk is zero and reports no interval (status "constant_node_plugin").

Parameters:

timestr

The follow-up time column. Every time is a positive finite number.

eventstr

The event-code column: 0 for censored, and a positive integer per cause.

treatmentstr

The baseline treatment column.

baselinesequence of str

Covariates measured before the treatment. The list names at least one column.

gridsequence of float or None

The grid times, which are the visit times. None needs integer times and uses \(g_k = k\) up to the largest event time. The fit costs \(K(K+1)/2\) sequential regressions per regimen and cause, so a default grid on day-level times can hold thousands of nodes.

causesmapping of int to str or None

The label of each nonzero event code. None reads codes {0, 1} as one event and any other codes as competing causes labelled str(code).

clusterstr or None

Independent-cluster identifier.

weightsstr or None

Probability-weight column.

weights_type{“probability”}

Interpretation of weights.

weights_estimatedbool

Whether the supplied weights were estimated from these data.

time_varyingNone

Not accepted. One row per unit holds no covariate measured after baseline, so any other value raises CapabilityError with code api_redirection.

continuous_treatmentbool

Whether the treatment is a continuous dose. A regimen is then a modified treatment policy at baseline.

treatment_probabilitiesmapping of level to str, or None

The known baseline treatment mechanism (a tuple of (level, column) pairs is also accepted) of a randomized design: each treatment level mapped to the column that holds \(P(A = \text{level} \mid W)\). The fit then divides by these probabilities and fits no treatment learner. A design names columns, so the array forms of cleverly.longitudinal.LTMLE.fit() are refused here.

treatment_supportSupport or None

The declared conditional support of a continuous treatment.

dose_atomssequence of float

The doses of a continuous treatment with a recorded point mass.

Attributes:

outcomestr

The event-code column, which the identified functional names as the outcome.

See also

LongitudinalTreatment

The wide layout, which also takes post-baseline covariates.

CausalStudy

What a design is handed to along with the data.

cleverly.longitudinal.LongitudinalData.from_time_to_event

The container it builds.

Examples

>>> from cleverly import TimeToEvent
>>> design = TimeToEvent(
...     time="ftime", event="ftype", treatment="arm", baseline=["age"], grid=[30, 60, 90]
... )
>>> design.grid
(30.0, 60.0, 90.0)

Methods

TimeToEvent.prepare(data: Any) → LongitudinalData

Validate data and construct its held survival representation.

Parameters:

datadataframe or LongitudinalData

Pandas, Polars, or prepared longitudinal data.

Returns:

LongitudinalData

The held container with its time grid.

Attributes

TimeToEvent.causes: Mapping[int, str] | None = None

TimeToEvent.cluster: str | None = None

TimeToEvent.continuous_treatment: bool = False

TimeToEvent.dose_atoms: Sequence[float] = ()

TimeToEvent.grid: Sequence[float] | None = None

TimeToEvent.outcome

The event-code column, which the identified functional names as the outcome.

TimeToEvent.time_varying: None = None

TimeToEvent.treatment_probabilities: Any = None

TimeToEvent.treatment_support: Any = None

TimeToEvent.weights: str | None = None

TimeToEvent.weights_estimated: bool = False

TimeToEvent.weights_type: Literal['probability'] = 'probability'

TimeToEvent.time: str

TimeToEvent.event: str

TimeToEvent.treatment: str

TimeToEvent.baseline: Sequence[str]