event_time()

Create a vector of event times.

Usage

Source

event_time(
    time,
    status,
    time_max=None,
)

event_time() creates a vector of event times that may be exact, or right-, left-, or interval-censored. It validates its input and raises an error describing the first problem found.

Parameters

time: Any

Non-negative event times (numbers or booleans, with None or nan for missing values). For interval-censored values, this is the lower end of the interval. Accepts a list, a NumPy array, or a DataFrame series. A single number is treated as a vector of length 1.

status: Any

Status codes, the same length as time: "e" (exact event), "r" (right-censored), "l" (left-censored), or "i" (interval-censored). It can be missing (None) only where time is missing. Codes are case-sensitive, and categorical input is rejected.

time_max: Any = None

Upper ends of the intervals, the same length as time. Must be missing for values that are not interval-censored, and greater than time otherwise. The default None sets all values to missing.

Returns

EventTime

The event-time vector.

Raises

TypeError

If time or time_max isn’t numeric, or status isn’t a character vector.

ValueError

If the lengths differ, or a value breaks one of the rules above.

Notes

Errors carry two extra attributes: check, a stable identifier for the rule that failed (such as "status_invalid_value"), and locations, a 0-based integer array of the offending positions (empty when the rule isn’t about particular positions). Only the first failing rule is reported, but with every location that breaks it.

Examples

import greenwood as gw

x = gw.event_time(
    time=[7, 5, 3, 2, None],
    status=["e", "r", "l", "i", None],
    time_max=[None, None, None, 4, None],
)
x

<event_time[5]>
7      5+     3-     [2, 4] <NA>

To start from a data frame, name the columns in a formula (or with Outcome.event_time()) and pass data= to fit(), which works on every DataFrame backend:

import polars as pl

df = pl.DataFrame({
    "times": [0.14, 0.15, 0.44, 0.76, 1.18],
    "status": ["l", "e", "e", "e", "r"],
})
gw.Turnbull().fit("event_time(times, status)", data=df)

Turnbull (self-consistent NPMLE for interval-censored data)

     n  atoms  ambiguous  iters  converged
all  5      4          1      1       True