cleverly.LongPanel

class cleverly.LongPanel(unit: str, time: str, treatment: str | Sequence[str], baseline: Sequence[str], time_varying: Sequence[str] = (), censoring: str | None = None, outcome: str | None = None, event: str | Mapping[str, str] | None = None, times: Sequence[Any] | None = None, cluster: str | None = None, weights: str | None = None, weights_type: Literal['probability'] = 'probability', weights_estimated: bool = False, outcome_family: Literal['gaussian', 'binomial', 'auto'] = 'auto', continuous_treatment: bool = False, treatment_probabilities: Mapping[Any, str] | None = None, censoring_probabilities: str | None = None, treatment_support: Any = None, dose_atoms: Sequence[float] = ())

Declare a longitudinal study read from a long panel: one row per unit and time.

Each row holds the covariates measured before that row’s decision, the decision, and whether the unit is still observed after it. cleverly.longitudinal.LongitudinalData.from_long_panel() states the layout, the generated column names and the refusals. The estimands are those of LongitudinalTreatment, and one unit’s rows are one observation.

Parameters:

unitstr

The unit identifier column.

timestr

The decision-time column.

treatmentstr or sequence of str

The decision at each row. A list of columns is one vector node per time.

baselinesequence of str

Unit-level covariates measured before the first decision. The list names at least one column.

time_varyingsequence of str

Covariates measured at each row before that row’s decision.

censoringstr or None

1 where the unit is still observed after the row’s decision.

outcomestr or None

An end-of-study outcome, one value per unit.

eventstr or mapping of str to str or None

A survival event indicator on each row, or one column per competing cause. Declare exactly one of outcome and event.

timessequence or None

Every decision time, in time order. None uses the times the panel holds, sorted, and needs numbers, dates or durations.

clusterstr or None

Independent-cluster identifier, constant within a unit.

weightsstr or None

Unit-level probability-weight column.

weights_type{“probability”}

Interpretation of weights.

weights_estimatedbool

Whether the supplied weights were estimated from these data.

outcome_family{“auto”, “gaussian”, “binomial”}

Outcome family used by the sequential regressions.

continuous_treatmentbool

Whether the treatment holds a continuous dose at every node.

treatment_supportSupport or None

The declared conditional support of the dose at every node.

dose_atomssequence of float

The doses with a recorded point mass at every node.

treatment_probabilitiesmapping of level to str, or None

The known treatment mechanism: each level mapped to the column that holds P(A_t = level | past) on each row. A tuple of (level, column) pairs, the form the design stores, is also accepted.

censoring_probabilitiesstr or None

The column that holds P(C_t = 1 | past) on each row.

See also

LongitudinalTreatment

The same declaration on a wide frame.

CausalStudy

What a design is handed to along with the data.

cleverly.longitudinal.LongitudinalData.from_long_panel

The container it builds.

Examples

>>> from cleverly import LongPanel
>>> design = LongPanel(
...     unit="customer",
...     time="week",
...     treatment="offer",
...     baseline=["age"],
...     time_varying=["engagement"],
...     censoring="active",
...     outcome="bought",
... )
>>> design.time_varying
('engagement',)

Methods

LongPanel.prepare(data: Any) → LongitudinalData

Validate a long panel and construct its trajectory representation.

Parameters:

datadataframe or LongitudinalData

A pandas or polars long panel, or data that this design prepared.

Returns:

LongitudinalData

Validated time-ordered representation.

Attributes

LongPanel.censoring: str | None = None

LongPanel.censoring_probabilities: str | None = None

LongPanel.cluster: str | None = None

LongPanel.continuous_treatment: bool = False

LongPanel.dose_atoms: Sequence[float] = ()

LongPanel.event: str | Mapping[str, str] | None = None

LongPanel.outcome: str | None = None

LongPanel.outcome_family: Literal['gaussian', 'binomial', 'auto'] = 'auto'

LongPanel.outcome_role

The outcome the identified functional names: the outcome or the event columns.

LongPanel.time_varying: Sequence[str] = ()

LongPanel.times: Sequence[Any] | None = None

LongPanel.treatment_probabilities: Mapping[Any, str] | None = None

LongPanel.treatment_support: Any = None

LongPanel.weights: str | None = None

LongPanel.weights_estimated: bool = False

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

LongPanel.unit: str

LongPanel.time: str

LongPanel.treatment: str | Sequence[str]

LongPanel.baseline: Sequence[str]