cleverly

Read the cleverly documentation →

cleverly is the Python toolbox for causal studies built on targeted maximum likelihood estimation (TMLE), organized around the causal question before the estimation method.

It is named for TMLE's clever covariate. Even the jokes in this toolbox are targeted.

study design -> typed estimand -> identified effect -> estimation method -> causal result

cleverly supports point and longitudinal treatment settings, influence-curve inference, cross-fitting, diagnostics, sensitivity analysis, and structured persistence. It accepts pandas, polars, Arrow-backed pandas, and pyarrow.Table inputs through narwhals.

Install

Install the core package from PyPI:

python -m pip install cleverly

Add pandas, polars, and plotting support with the all extra. Third-party nuisance estimators such as XGBoost or LightGBM can be installed separately and passed as sklearn-compatible objects:

python -m pip install "cleverly[all]"

Python 3.11 or newer is required. See Installation for a development environment and reproducible version-pinned installs.

Quickstart

Declare the design and the estimand separately, inspect identification, estimate, then assess:

from sklearn.linear_model import LinearRegression, LogisticRegression
from cleverly import ATE, CausalStudy, PointTreatment
from cleverly.datasets import make_linear_ate

frame, truth = make_linear_ate(n=2_000, seed=7)
study = CausalStudy(
    frame,
    design=PointTreatment(
        outcome="Y",
        treatment="A",
        adjustment=("W1", "W2", "W3", "W4"),
    ),
)
effect = study.identify(ATE(reference=0))
print(effect.summary())
result = effect.estimate(
    outcome_learner=LinearRegression(),
    treatment_learner=LogisticRegression(max_iter=1000),
    cross_fit=False,
    random_state=7,
)
print(result.summary())
print(result["ate"].ci, "population ATE:", truth["ate"])
print(result.assess().summary())

Both nuisance functions of make_linear_ate are linear, so these learners are correctly specified. A correctly specified parametric learner needs no cross-fitting, so this fit uses none. Cross-fitting a continuous outcome needs its support declared, because q_bounds=None reads the held-out rows to set the scale. The identified effect states its functional and assumptions before any learner is fit.

Continue with the full quickstart or the analysis workflow.

Documentation

The Sphinx/MyST documentation is published on GitHub Pages and builds from docs/.

The development reference contains the roadmap, the architecture invariants, the fast-test and validation-study rules, and the method-benchmarking strategy. The test-enforced evidence manifest lives in the Technical reference.

Implemented analysis families

This table summarizes the package. The technical implementation matrix is the authoritative inventory, and it names the evidence for each row.

Roadmap

• Extend sensitivity and validation with source-backed refutations and longitudinal analyses.
• Add optional DoWhy identification and graph validation while the core package stays standalone.
• Add EP learning for conditional average treatment effects and conditional relative risks.
• Extend current methods through persistence, design, splitting, and new evidenced estimands.
• Build the nested Riesz engine and expand its catalog one evidenced target at a time.

These are accepted directions, not implemented release claims. The roadmap gives their binding order. It keeps work without published theory in a separate future grid.

Method configuration

Named shortcuts normalize into immutable configuration groups:

from cleverly import CrossFitting, Inference, ModelSpec, Runtime, TMLEMethod

method = TMLEMethod(
    models=ModelSpec(
        outcome_learner=LinearRegression(), treatment_learner=LogisticRegression(max_iter=1000)
    ),
    cross_fitting=CrossFitting(enabled=False, learner_folds=3),
    inference=Inference(alpha=0.05, simultaneous=False),
    runtime=Runtime(random_state=7, n_jobs=1),
)
result = effect.estimate(method=method)

CrossFitting(enabled=False) here for the reason the quickstart gives. To cross-fit this fit instead, declare the outcome support with Targeting(q_bounds=(lower, upper)), or use a law whose outcome is bounded.

CollaborativeTMLEMethod and DRTMLEMethod select estimator variants without changing the identified causal question. effect.available_methods() reports support and refusal reasons.

Development

uv venv
uv pip install -e ".[dev,docs]"
ruff check .
ruff format --check .
python -m tests.prose
mypy
pytest -q -n auto --dist loadgroup
sphinx-build -W --keep-going -b html docs docs/_build/html

mypy reads its own configuration, which covers src/cleverly and scripts. nox -s docs runs the warning-as-error build in an isolated environment. CI uses this command. The direct call is faster, so the installation command above includes the docs extra.

python -m tests.prose reports on the reader-facing prose. It does not rewrite anything and it does not fail on what it finds. Read each finding, then either change the sentence or record accepted: <reason> against it in tests/prose-report.md. The fast tier fails only on a finding with no recorded judgment, which keeps the decision with the writer. Sentence length is advisory output and carries no row at all. tests/prose.py says which rules were rejected and why.

The fast tier compiles every Python fence and executes the registered reader-facing guides. It also resolves relative links and checks that generated API source represents the root API. Scientific behavior belongs in ordinary fast tests or registered validation studies. Regenerate only the affected studies. Run the relevant checks locally before handoff. A green GitHub Actions CI run is the final merge signal.

CONTRIBUTING.md gives the branch names, the checks each kind of change needs, and the commit style.

Citing

There is no DOI yet. Cite the repository commit used in the analysis and the primary method papers listed in the technical reference and references.

License

MIT License.

The R comparison runners under tests/canonical/ are under the GNU General Public License v3.0. They call reference R packages in the same process, and one package is AGPL-3. No published distribution carries them, so an installed copy of cleverly is MIT alone.