cleverly.PointTreatment

class cleverly.PointTreatment(outcome: str, treatment: str | tuple[str, ...], adjustment: ~collections.abc.Sequence[str] = <factory>, randomized: bool = False, missingness: str | None = None, intermediate: str | None = None, weights: str | None = None, weights_type: ~typing.Literal['probability'] = 'probability', weights_estimated: bool = False, cluster: str | None = None, strata: ~collections.abc.Sequence[str] = <factory>, treatment_kind: ~typing.Literal['discrete', 'continuous'] = 'discrete', outcome_family: ~typing.Literal['gaussian', 'binomial', 'auto'] = 'auto', treatment_missingness: str | None = None, treatment_probabilities: ~typing.Any = None, treatment_adjustment: ~collections.abc.Sequence[str] | None = None, continuous_treatment: ~collections.abc.Sequence[str] = <factory>, treatment_support: ~typing.Any = None, dose_atoms: ~collections.abc.Sequence[float] | ~collections.abc.Mapping[str, ~collections.abc.Sequence[float]] = <factory>)

Declare column roles for a point-treatment study.

Parameters:

outcomestr

Outcome column.

treatmentstr or sequence of str

Discrete treatment or continuous dose column, or the columns of a vector treatment. A vector of categorical columns is one categorical treatment over the observed tuples. A vector with a column in continuous_treatment takes ModifiedTreatmentPolicy with JointPolicy declarations only.

adjustmentsequence of str

Baseline adjustment columns. Supply at least one unless randomized=True.

randomizedbool

Whether the treatment was randomized and an empty adjustment set is intentional.

missingnessstr or None

Outcome-observation indicator. One means observed.

intermediatestr or None

Binary intermediate column for a controlled direct effect.

weightsstr or None

Probability-weight column.

weights_type{“probability”}

Interpretation of weights.

weights_estimatedbool

Whether the supplied weights were estimated from these data.

clusterstr or None

Independent-cluster identifier used for variance estimation.

stratasequence of str

Baseline strata columns, each also an adjustment column. They define stratum-specific parameters, such as ate[S=1], reported beside the marginal ones. CausalStudy.identify() refuses a stratum that lacks a treatment arm beside an incremental estimand, and an MSMProjection whose design is singular inside a stratum.

treatment_kind{“discrete”, “continuous”}

Treatment support used to select supported estimands, for a treatment of one column. A vector treatment keeps "discrete" and names its doses in continuous_treatment.

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

Outcome family. "auto" infers it from observed values.

treatment_missingnessstr or None

Treatment-observation indicator. One means the treatment is recorded. It declares a treatment missing at random. The composite indicator identifies the arm means and their contrasts on in-sample TMLE and DRTMLE fits, and their point estimates on the in-sample per-arm outcome-adaptive CTMLE. It also identifies regime means and arm MSMs on in-sample TMLE fits.

treatment_probabilitiesmapping of level to str, or None

The known treatment mechanism of a randomized design (a tuple of (level, column) pairs, the form the design stores, is also accepted): each treatment level mapped to the column that holds P(A = level | W). Every method then divides by these probabilities in place of an estimate, and the columns are not adjustment covariates. A design names columns, so the array forms of cleverly.TMLE.fit() are refused here. CollaborativeTMLEMethod is unavailable on such a design, because there is no mechanism to select.

treatment_adjustmentsequence of str or None

The adjustment columns that the treatment mechanism reads, a subset of adjustment. None reads all of them. The outcome regression and every other nuisance keep the full set. The declaration restricts the observed-data model and does not change the estimand. The interval is claimed only under that restriction, and the identification record prints it. An empty sequence declares a marginal treatment mechanism. To exclude instruments, omit them from adjustment instead. The declaration is refused beside treatment_probabilities, which supplies a known mechanism, and beside an incremental estimand, which shifts the fitted propensity score.

continuous_treatmentsequence of str

The columns of a vector treatment that hold a continuous dose.

treatment_supportSupport, mapping of str to Support, or None

The declared conditional support of a continuous dose, as cleverly.TMLE.fit() takes it. A vector treatment maps each continuous component to its support. A modified treatment policy must assign each row a dose inside it.

dose_atomssequence of float, or mapping of str to sequence of float

The doses of a continuous treatment with a recorded point mass, as cleverly.TMLE.fit() takes them. A vector treatment maps each continuous component to its atoms.

Attributes:

treatment_columnstuple of str

The treatment’s columns: one, or the components of a vector.

treatment_namestr

The treatment’s name: its column, or its components joined by +.

support{“discrete”, “continuous”, “vector”}

What the prepared treatment is, as CausalData.treatment_kind records it.

See also

LongitudinalTreatment

The same declaration for time-varying treatment.

CausalStudy

What a design is handed to along with the data.

cleverly.datasets.make_linear_ate

A frame with the columns this example names.

Examples

>>> from cleverly import PointTreatment
>>> design = PointTreatment(
...     outcome="Y", treatment="A", adjustment=("age", "baseline_score")
... )
>>> design.treatment
'A'

A randomized trial declares that its empty adjustment set is deliberate:

>>> PointTreatment(outcome="Y", treatment="A", randomized=True).adjustment
()

A trial that knows its allocation probabilities names their columns:

>>> PointTreatment(
...     outcome="Y",
...     treatment="A",
...     adjustment=("age",),
...     treatment_probabilities={0: "p_control", 1: "p_treated"},
... ).treatment_probabilities
((0, 'p_control'), (1, 'p_treated'))

A design can let the treatment mechanism read a subset of the adjustment set:

>>> PointTreatment(
...     outcome="Y",
...     treatment="A",
...     adjustment=("age", "baseline_score"),
...     treatment_adjustment=("age",),
... ).treatment_adjustment
('age',)

Methods

PointTreatment.prepare(data: Any) → CausalData

Validate data and encode the declared column roles.

Parameters:

datadataframe or CausalData

Pandas, Polars, or prepared causal data.

Returns:

CausalData

Validated internal representation.

Attributes

PointTreatment.cluster: str | None = None

PointTreatment.intermediate: str | None = None

PointTreatment.missingness: str | None = None

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

PointTreatment.randomized: bool = False

PointTreatment.support

What the prepared treatment is, as CausalData.treatment_kind records it.

"vector" is a vector with a continuous component, which has no arms. An all-categorical vector is "discrete": one categorical treatment over its tuples.

PointTreatment.treatment_adjustment: Sequence[str] | None = None

PointTreatment.treatment_columns

The treatment’s columns: one, or the components of a vector.

PointTreatment.treatment_kind: Literal['discrete', 'continuous'] = 'discrete'

PointTreatment.treatment_missingness: str | None = None

PointTreatment.treatment_name

The treatment’s name: its column, or its components joined by +.

PointTreatment.treatment_probabilities: Any = None

PointTreatment.treatment_support: Any = None

PointTreatment.weights: str | None = None

PointTreatment.weights_estimated: bool = False

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

PointTreatment.outcome: str

PointTreatment.treatment: str | tuple[str, ...]

PointTreatment.adjustment: Sequence[str]

PointTreatment.strata: Sequence[str]

PointTreatment.continuous_treatment: Sequence[str]

PointTreatment.dose_atoms: Sequence[float] | Mapping[str, Sequence[float]]