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.

[!WARNING] cleverly is alpha software, and releases use 0.1.N versions. Pin a version for reproducible work. Unsupported combinations fail before nuisance fitting instead of returning an approximation to another causal question.

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 observed-data design and the causal estimand separately, inspect identification, then estimate:

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

frame, truth = make_nonlinear_ate(n=2_000, seed=7)
study = CausalStudy(
    frame,
    design=PointTreatment(
        outcome="Y",
        treatment="A",
        adjustment=("W1", "W2", "W3", "W4"),
    ),
)

effect = study.identify(ATE())
print(effect.summary())

result = effect.estimate(random_state=7)
print(result.summary())
print(result["ate"].ci)

The identified effect states the observed-data functional, assumptions, nuisance requirements, and available methods before any learner is fit. The result retains estimates, influence curves, joint covariance, structured parameter keys, normalized method configuration, provenance, and post-fit assessment.

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 test tiers and gates, and the method-benchmarking strategy. The test-enforced evidence manifest lives in the Technical reference.

Implemented analysis families

This table summarises 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(n_folds=5, learner_folds=3),
    inference=Inference(alpha=0.05, simultaneous=False),
    runtime=Runtime(random_state=7, n_jobs=1),
)
result = effect.estimate(method=method)

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 -m "not slow" -q
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 named slow statistical 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.