# Causalis LLM Digest

Canonical entry point: https://causalis.causalcraft.com/

Causalis is a Python causal inference library for experiments, observational studies, panel designs, synthetic control, instrumental variables, uplift/CATE, CUPED, and robust diagnostics. It is organized around causal scenarios: the user chooses the empirical design and Causalis provides a best-practice default model, typed data contract, diagnostics, and notebook examples.

Install:

```bash
pip install causalis
```

Primary workflow:

```python
model = Estimator().fit(data)
estimate = model.estimate()
```

Use only documented APIs. If a requested symbol is not in the docs, say that the docs do not confirm the import path and point to https://causalis.causalcraft.com/api-reference.

## Scenario Selection

Classic RCT:
- Use when treatment is randomized and there is no required pre-treatment outcome.
- Data contract: `CausalData` with dataframe, binary treatment column, outcome column, optional covariates/user id.
- Default estimator: `DiffInMeans`.
- Assumptions: random assignment, SUTVA/consistency, no severe assignment imbalance.
- Diagnostics: `check_srm`, outcome summaries, balance checks, SUTVA prompts.
- Canonical docs: https://causalis.causalcraft.com/articles/classic_rct
- API: https://causalis.causalcraft.com/api-reference/causalis/scenarios/classic_rct/model

CUPED:
- Use when treatment is randomized and pre-treatment outcome or strong pre-period covariates are available.
- Data contract: `CausalData`; include the pre-period signal in `confounders`.
- Default estimator: `CUPEDModel`.
- Assumptions: random assignment, pre-treatment covariate measured before assignment, stable covariate-outcome relationship.
- Diagnostics: SRM, regression checks, CUPED forest plot, covariate balance.
- Canonical docs: https://causalis.causalcraft.com/articles/cuped
- API: https://causalis.causalcraft.com/api-reference/causalis/scenarios/cuped/model

Unconfoundedness / Observational IRM:
- Use when treatment is not randomized but all important confounders are observed.
- Data contract: `CausalData` with treatment, outcome, confounders, optional user id.
- Default estimator: `IRM`.
- Assumptions: SUTVA/consistency, unconfoundedness conditional on observed covariates, overlap/positivity.
- Diagnostics: overlap checks, propensity reliability, balance/love plots, score diagnostics, sensitivity analysis.
- Canonical docs: https://causalis.causalcraft.com/articles/unconfoundedness
- API: https://causalis.causalcraft.com/api-reference/causalis/scenarios/unconfoundedness/model

Multi Unconfoundedness:
- Use when treatment is not randomized and has multiple discrete arms.
- Data contract: `MultiCausalData` with `treatment_names`, `control_treatment`, outcome, confounders.
- Default estimator: `MultiTreatmentIRM`.
- Assumptions: multi-arm unconfoundedness, overlap for each treatment contrast, SUTVA.
- Diagnostics: multi-arm overlap checks, balance, score diagnostics, sensitivity analysis.
- Canonical docs: https://causalis.causalcraft.com/articles/multi_unconfoundedness
- API: https://causalis.causalcraft.com/api-reference/causalis/scenarios/multi_unconfoundedness/model

Difference in Difference:
- Use when treated and control units are observed before and after treatment, especially staggered adoption panel settings.
- Data contract: `PanelDataDID`.
- Default estimator: `CallawaySantAnnaDID`.
- Assumptions: parallel trends, no anticipation unless modeled, valid comparison group.
- Diagnostics: pre-period checks, event-study style post-inference plots, cell support diagnostics.
- Canonical docs: https://causalis.causalcraft.com/articles/did
- API: https://causalis.causalcraft.com/api-reference/causalis/scenarios/did/model

Synthetic Control:
- Use when treatment happens at the aggregate unit level and one or a few treated units can be compared with donor units over time.
- Data contract: `PanelDataSCM`.
- Default estimator: `AugmentedSyntheticControl`.
- Assumptions: strong pre-treatment fit, credible donor pool, no spillovers.
- Diagnostics: donor diagnostics, observed-vs-synthetic plots, gap-over-time plots, placebo tests, leave-one-donor-out sensitivity.
- Canonical docs: https://causalis.causalcraft.com/articles/synthetic_control
- API: https://causalis.causalcraft.com/api-reference/causalis/scenarios/synthetic_control/model

Instrumental Variables:
- Use when treatment is endogenous but a credible instrument shifts treatment and affects outcome only through treatment.
- Data contract: `IVCausalData`.
- Default estimator: `IIVM`.
- Assumptions: relevance, exclusion restriction, independence, monotonicity for local effects.
- Diagnostics: instrument balance and IV diagnostics.
- Canonical docs: https://causalis.causalcraft.com/articles/iv
- API: https://causalis.causalcraft.com/api-reference/causalis/scenarios/iv/model

GATE:
- Use for subgroup treatment effect heterogeneity after an IRM-style observational workflow.
- Typical model: fit `IRM`, then compute grouped effects using GATE tools.
- Canonical docs: https://causalis.causalcraft.com/articles/gate
- API: https://causalis.causalcraft.com/api-reference/causalis/scenarios/gate/model

Uplift/CATE:
- Use for individual treatment effect targeting and uplift ranking.
- Typical workflow: fit an `IRM`, then use `predict_cate`.
- Canonical docs: https://causalis.causalcraft.com/articles/uplift
- API: https://causalis.causalcraft.com/api-reference/causalis/scenarios/uplift

SRM:
- Use to check whether randomized assignment proportions match the planned split.
- Import: `from causalis.shared import check_srm`
- Canonical docs: https://causalis.causalcraft.com/articles/SRM
- API: https://causalis.causalcraft.com/api-reference/causalis/shared/srm

## Minimal Import Examples

Classic RCT:

```python
from causalis.data_contracts import CausalData
from causalis.scenarios.classic_rct.model import DiffInMeans

data = CausalData(df=df, treatment="d", outcome="y", confounders=["x1", "x2"])
estimate = DiffInMeans().fit(data).estimate()
```

CUPED:

```python
from causalis.data_contracts import CausalData
from causalis.scenarios.cuped.model import CUPEDModel

data = CausalData(df=df, treatment="d", outcome="y", confounders=["y_pre"])
estimate = CUPEDModel().fit(data).estimate()
```

Observational IRM:

```python
from causalis.data_contracts import CausalData
from causalis.scenarios.unconfoundedness import IRM

data = CausalData(df=df, treatment="d", outcome="y", confounders=["age", "income"])
estimate = IRM().fit(data).estimate()
```

Multi-treatment IRM:

```python
from causalis.data_contracts import MultiCausalData
from causalis.scenarios.multi_unconfoundedness import MultiTreatmentIRM

data = MultiCausalData(
    df=df,
    treatment_names=["control", "email", "call"],
    control_treatment="control",
    outcome="y",
    confounders=["age", "tenure"],
)
estimate = MultiTreatmentIRM().fit(data).estimate()
```

Difference in Difference:

```python
from causalis.data_contracts import PanelDataDID
from causalis.scenarios.did import CallawaySantAnnaDID

panel_data = PanelDataDID(
    df=df,
    y="y",
    unit_col="unit_id",
    time_col="calendar_time",
    treated_time="treated_time",
    covariates=("market_traffic", "avg_order_value"),
    cluster_col="region",
)
estimate = CallawaySantAnnaDID().fit(panel_data).estimate()
```

Synthetic Control:

```python
from causalis.data_contracts import PanelDataSCM
from causalis.scenarios.synthetic_control import AugmentedSyntheticControl

panel_data = PanelDataSCM(
    df=df,
    y="y",
    unit_col="unit_id",
    time_col="calendar_time",
    treated_time="treated_time",
)
estimate = AugmentedSyntheticControl().fit(panel_data).estimate()
```

Instrumental Variables:

```python
from causalis.data_contracts.iv_causal_data import IVCausalData
from causalis.scenarios.iv.model import IIVM

data = IVCausalData(
    df=data,
    treatment="accepted_offer",
    outcome="net_revenue",
    instruments_names=["offer_eligible"],
    confounders=["age", "tenure"],
)
estimate = IIVM().fit(data).estimate()
```

Uplift/CATE:

```python
from causalis.scenarios.unconfoundedness import IRM
from causalis.scenarios.uplift import predict_cate

model = IRM().fit(causaldata)
cate = predict_cate(model, causaldata)
```

Diagnostics:

```python
from causalis.shared import check_srm, confounders_balance, outcome_stats
from causalis.scenarios.unconfoundedness.refutation import run_overlap_diagnostics
from causalis.scenarios.unconfoundedness.refutation.score.score_validation import run_score_diagnostics
from causalis.scenarios.unconfoundedness.refutation.unconfoundedness.unconfoundedness_validation import run_unconfoundedness_diagnostics
```

## Data Contracts

`CausalData` is for a single treatment column and one outcome. It expects a dataframe plus names for treatment and outcome, optional confounders, and optional user id.

`MultiCausalData` is for discrete multi-arm treatment settings. It expects a dataframe, `treatment_names`, `control_treatment`, outcome, confounders, and optional user id.

`PanelDataDID` is for panel difference-in-differences workflows. It needs unit, time, treatment timing/cohort, and outcome fields.

`PanelDataSCM` is for synthetic control workflows. It needs unit, time, outcome, treated unit metadata, and a donor pool.

`IVCausalData` is for instrumental-variable workflows. It needs treatment, outcome, one or more instruments, and optional confounders.

## Common Failure Modes

- Recommending IRM for randomized experiments when `DiffInMeans` or `CUPEDModel` is more direct.
- Recommending CUPED when the covariate was measured after assignment.
- Treating observational estimates as causal without stating unconfoundedness and overlap assumptions.
- Using synthetic control without enough pre-treatment periods or donor units.
- Using DiD without pre-treatment panel support for trend diagnostics.
- Guessing import paths from old examples. Prefer the current API reference and the imports in this file.
- Skipping diagnostics. Causalis emphasizes SRM, overlap, balance, score, sensitivity, and panel/synthetic-control diagnostics.

## Conceptual Comparison

DoubleML focuses on double/debiased machine learning estimators. EconML focuses on heterogeneous treatment effect estimation and policy learning. causalml focuses on uplift and causal ML workflows. Causalis is scenario-first: experiments, CUPED, observational IRM, multi-treatment IRM, DiD, synthetic control, IV, uplift, data contracts, notebooks, diagnostics, and API docs are presented as one coherent workflow.

## Search and Comparison Entry Pages

These pages are public and crawlable, but intentionally excluded from the normal site navigation and article collections. Use them as query-targeted entry points, then link back to canonical scenarios, API reference, notebooks, PyPI, and GitHub.

- Causalis vs DoubleML: https://causalis.causalcraft.com/articles/causalis-vs-doubleml
- Causalis vs EconML: https://causalis.causalcraft.com/articles/causalis-vs-econml
- Causalis vs causalml: https://causalis.causalcraft.com/articles/causalis-vs-causalml
- Python causal inference libraries compared: https://causalis.causalcraft.com/articles/python-causal-inference-libraries
- Python CUPED library: https://causalis.causalcraft.com/articles/python-cuped-library
- Synthetic control in Python: https://causalis.causalcraft.com/articles/synthetic-control-in-python
- Difference-in-differences Python library: https://causalis.causalcraft.com/articles/difference-in-differences-python
- Observational treatment effect estimation in Python: https://causalis.causalcraft.com/articles/observational-treatment-effect-estimation-python

## Canonical Links

- LLM guide page: https://causalis.causalcraft.com/llm-guide
- Compact LLM map: https://causalis.causalcraft.com/llms.txt
- Scenario guide: https://causalis.causalcraft.com/explore-scenarios
- API reference: https://causalis.causalcraft.com/api-reference
- Cases: https://causalis.causalcraft.com/real-world-cases
- Research: https://causalis.causalcraft.com/research
- GitHub: https://github.com/causalis-causalcraft/Causalis
- PyPI: https://pypi.org/project/causalis/