cleverly.CausalStudy#

class cleverly.CausalStudy(data: Any, *, design: PointTreatment | LongitudinalTreatment | TimeToEvent | LongPanel, protocol: StudyProtocol | None = None)[source]#

Validate observed data against an immutable causal-study design.

Parameters:

datadataframe, CausalData, or LongitudinalData: Observed study data. Pandas and Polars dataframes are supported.
designPointTreatment, LongitudinalTreatment, TimeToEvent, or LongPanel: Column roles and treatment-time structure.
protocolStudyProtocol or None: Scientific study protocol. None records that no protocol was supplied.

Attributes:

dataCausalData or LongitudinalData: Return the validated internal data representation.
designPointTreatment, LongitudinalTreatment, TimeToEvent, or LongPanel: Return the immutable study design.
protocolStudyProtocol or None: Return the scientific study protocol, if one was supplied.

See also

PointTreatment: The design declaration for treatment given once.
LongitudinalTreatment: The design declaration for time-varying treatment.
TimeToEvent: The design declaration for one follow-up time and one event code per unit.
LongPanel: The design declaration for one row per unit and decision time.
IdentifiedEffect: What identify() returns.

Examples

>>> from cleverly import ATE, CausalStudy, PointTreatment
>>> from cleverly.datasets import make_linear_ate
>>> frame, _ = make_linear_ate(n=40, seed=1)
>>> study = CausalStudy(
...     frame,
...     design=PointTreatment(
...         outcome="Y", treatment="A", adjustment=("W1", "W2", "W3", "W4")
...     ),
... )
>>> study.identify(ATE()).estimand.name
'ate'

Methods#

CausalStudy.estimate(estimand: ATE | ATT | ATC | CounterfactualMean | NaturalCourseMean | PopulationAttributableRisk | PopulationAttributableFraction | RiskRatio | OddsRatio | RegimeMean | RegimeContrast | LearnedRuleValue | ModifiedTreatmentPolicy | ModifiedTreatmentPolicyEffect | IncrementalMean | IncrementalEffect | MSMProjection | ControlledDirectEffect, method: str | EstimationMethod = 'tmle', **overrides: Any) → TMLEResult | LongitudinalResult[source]#

Identify and estimate one causal quantity.

Parameters:

estimandEstimand: Typed causal quantity.
methodstr or EstimationMethod: Named method or configured method object.
**overridesAny: Method fields overridden for this fit.

Returns:

TMLEResult or LongitudinalResult: Fitted result for the declared design.

CausalStudy.identify(estimand: ATE | ATT | ATC | CounterfactualMean | NaturalCourseMean | PopulationAttributableRisk | PopulationAttributableFraction | RiskRatio | OddsRatio | RegimeMean | RegimeContrast | LearnedRuleValue | ModifiedTreatmentPolicy | ModifiedTreatmentPolicyEffect | IncrementalMean | IncrementalEffect | MSMProjection | ControlledDirectEffect, *, provider: IdentificationProvider | None = None) → IdentifiedEffect[source]#

Bind one typed estimand to an observed-data functional.

Parameters:

estimandEstimand: Typed causal quantity, such as ATE(). String aliases are not accepted.
providerIdentificationProvider or None: Identification strategy. None uses explicit adjustment or history.

Returns:

IdentifiedEffect: Question, functional, assumptions, and available methods before fitting.

Raises:

CapabilityError: If the estimand type or its composition with the design or the data is unsupported, or if a typed estimand holds an intervention of another kind.
DataError: If the estimand names a value that the data lack, or if the set of a point estimand is a mapping, an iterator, a string, or a single item.

See also

IdentifiedEffect: The identified question returned by this method.
CausalStudy.estimate: Identify and estimate in one call.

Notes

Pass a typed estimand such as ATE(). String aliases are refused with a CapabilityError so the failure identifies the required public object.

Examples

>>> from cleverly import ATE, CausalStudy, PointTreatment
>>> from cleverly.datasets import make_linear_ate
>>> frame, _ = make_linear_ate(n=40, seed=1)
>>> study = CausalStudy(
...     frame,
...     design=PointTreatment(
...         outcome="Y", treatment="A", adjustment=("W1", "W2", "W3", "W4")
...     ),
... )
>>> effect = study.identify(ATE(reference=0))
>>> effect.estimand.reference
0

Attributes#

CausalStudy.data#: Return the validated internal data representation.

CausalStudy.design#: Return the immutable study design.

CausalStudy.protocol#: Return the scientific study protocol, if one was supplied.