cleverly 0.2.0__tar.gz → 0.2.1__tar.gz

{cleverly-0.2.0 → cleverly-0.2.1}/.github/actions/setup-env/action.yml

@@ -11,6 +11,13 @@ inputs:
     description: Which optional-dependency group to install; "dev" for anything running pytest.
     required: false
     default: dev
+  resolution:
+    description: >-
+      "locked" installs the versions in `uv.lock`. "latest" resolves the newest releases the
+      `pyproject.toml` floors allow, so CI sees a new numpy, scipy or scikit-learn the day it
+      ships rather than at the next lock refresh.
+    required: false
+    default: locked
   packages:
     description: >-
       Further requirements to install after the locked project, space-separated.
@@ -46,7 +53,17 @@ runs:
       env:
         PYTHON_VERSION: ${{ inputs.python-version }}
 
-    - run: uv sync --locked --extra "${EXTRA}"
+    - if: ${{ inputs.resolution == 'locked' }}
+      run: uv sync --locked --extra "${EXTRA}"
+      shell: bash
+      env:
+        EXTRA: ${{ inputs.extra }}
+
+    # `--upgrade` re-resolves in the runner's checkout and leaves the committed lock alone.
+    - if: ${{ inputs.resolution == 'latest' }}
+      run: |
+        uv sync --upgrade --extra "${EXTRA}"
+        uv pip list
       shell: bash
       env:
         EXTRA: ${{ inputs.extra }}

{cleverly-0.2.0 → cleverly-0.2.1}/.github/workflows/ci.yml

@@ -74,9 +74,17 @@ jobs:
       - uses: actions/checkout@v4
       # The matrix version is threaded through to `uv venv --python`; without that, every
       # row of the matrix would install into `/usr`'s interpreter and exercise the same one.
+      #
+      # 3.11 and 3.12 install the locked versions. 3.13 installs the newest releases the
+      # floors allow (Eric, 2026-11-06: let library versions move, and pin only when a release
+      # breaks a method). A red here that the locked rows do not share is a new release
+      # changing behaviour: fix the code, or add an upper bound in `pyproject.toml` with the
+      # failure named beside it. It never runs `test_method_evidence.py`, so last-digit
+      # rounding in a published table cannot turn it red.
       - uses: ./.github/actions/setup-env
         with:
           python-version: ${{ matrix.python-version }}
+          resolution: ${{ matrix.python-version == '3.13' && 'latest' || 'locked' }}
       # `-n auto` resolves through psutil, else `os.cpu_count()` -- neither of which reads a
       # container's CFS quota, so on a quota-limited runner it asks for the *host's* cores.
       # `tests.parallel` goes through joblib/loky, which does read it.
@@ -117,16 +125,23 @@ jobs:
 
   # The all-study property differential and its clause binding (RM39b2 rev 3 section 8). Every
   # committed study's property rows are perturbed and summarized by the study's own code, and
-  # the declared failure-accounting rules must give the same verdicts. Measured at 5,892 cases,
-  # about 7,600 CPU-seconds and about 35 minutes on four workers, far over the fast tier's
-  # budget, so it runs here (the R3-2 fallback) and never as a sample. Later study additions
-  # brought main to 91% at the former 105-minute timeout. Allow 180 minutes for the complete
-  # check. The fast tier checks that its parametrization lists every committed study. The
-  # job always reports, so it can be a required check: on a pull request that touches none of
-  # the paths below its steps are skipped.
+  # the declared failure-accounting rules must give the same verdicts. It runs here (the R3-2
+  # fallback) and never as a sample. On one four-core runner it reached 2 hours 8 minutes
+  # (about 30,700 CPU-seconds, 9,858 cases, November 2026), so it is split into four parts on
+  # four runners. `PROPERTY_DIFFERENTIAL_PART` selects a part, and `property_differential.parts`
+  # assigns each worker group to exactly one part, balanced by estimated work, so the four
+  # parts run every case between them. Each part has 90 minutes. The fast tier checks that the
+  # parametrization lists every committed study. The job always reports, so it can be a required
+  # check: on a pull request that touches none of the paths below its steps are skipped, and
+  # `property-differential-verdict` reports the parts as one check named `property-differential`.
   property-differential:
+    name: property-differential (part ${{ matrix.part }} of 4)
     runs-on: ubuntu-latest
-    timeout-minutes: 180
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        part: [1, 2, 3, 4]
     steps:
       - uses: actions/checkout@v4
         with:
@@ -155,8 +170,20 @@ jobs:
       - name: Size the worker pool from the cores this job may actually use
         if: steps.scope.outputs.run == 'true'
         run: echo "PYTEST_XDIST_AUTO_NUM_WORKERS=$(python -m tests.parallel --workers)" >> "$GITHUB_ENV"
+      # `--durations` names the slowest cases, so a part that grows shows where.
       - if: steps.scope.outputs.run == 'true'
-        run: pytest -q -n auto --dist loadgroup tests/canonical/property_differential.py
+        env:
+          PROPERTY_DIFFERENTIAL_PART: ${{ matrix.part }}/${{ strategy.job-total }}
+        run: pytest -q -n auto --dist loadgroup --durations=20 tests/canonical/property_differential.py
+  # One check for branch protection: green only when every part of the differential succeeded.
+  property-differential-verdict:
+    name: property-differential
+    if: always()
+    needs: property-differential
+    runs-on: ubuntu-latest
+    steps:
+      - name: Every part of the differential passed
+        run: test "${{ needs.property-differential.result }}" = success
 
   # One backend at a time, which the `tests` job above cannot check: it installs `.[dev]`,
   # which pulls pandas *and* polars, so the single-backend and neither-installed branches of

{cleverly-0.2.0 → cleverly-0.2.1}/CLAUDE.md

@@ -63,6 +63,9 @@ objects, or `CausalStudy` objects, and not for the public API.
   result-neutral edit in `tests/canonical/provenance-revisions.md` rather than rewriting a
   recorded hash, which would leave the manifest describing bytes that never ran.
   `docs/development/method-benchmarking.md` says how to tell the two kinds of change apart.
+- Libraries are not pinned aggressively; versions float. A test must tolerate rounding changes
+  from library versions and fail only on a real change. Pin a version only when a release breaks
+  a method. `docs/development/contributing.md` states the policy.
 - Ruff and mypy are pinned once in `pyproject.toml`'s `dev` extra, which resolves to
   `cleverly[all]` plus tooling. For a new extra, follow
   [Add an optional dependency](docs/development/contributing.md#add-an-optional-dependency).

{cleverly-0.2.0 → cleverly-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cleverly
-Version: 0.2.0
+Version: 0.2.1
 Summary: A Python toolbox for causal studies based on targeted maximum likelihood estimation (TMLE).
 Project-URL: Homepage, https://esbraun.github.io/cleverly-tmle/
 Project-URL: Documentation, https://esbraun.github.io/cleverly-tmle/
@@ -31,32 +31,32 @@ Requires-Dist: matplotlib>=3.7; extra == 'all'
 Requires-Dist: pandas>=1.5; extra == 'all'
 Requires-Dist: polars>=0.20; extra == 'all'
 Provides-Extra: dev
-Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: ipykernel>=6.29; extra == 'dev'
 Requires-Dist: matplotlib>=3.7; extra == 'dev'
 Requires-Dist: mypy==1.19.1; extra == 'dev'
-Requires-Dist: nbclient<1,>=0.10; extra == 'dev'
-Requires-Dist: nbformat<6,>=5.10; extra == 'dev'
+Requires-Dist: nbclient>=0.10; extra == 'dev'
+Requires-Dist: nbformat>=5.10; extra == 'dev'
 Requires-Dist: nox>=2024.3; extra == 'dev'
-Requires-Dist: numpydoc<2,>=1.10; extra == 'dev'
+Requires-Dist: numpydoc>=1.10; extra == 'dev'
 Requires-Dist: pandas>=1.5; extra == 'dev'
 Requires-Dist: polars>=0.20; extra == 'dev'
 Requires-Dist: pyarrow>=15; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
 Requires-Dist: pytest>=7.4; extra == 'dev'
 Requires-Dist: ruff==0.16.1; extra == 'dev'
-Requires-Dist: twine<8,>=7; extra == 'dev'
+Requires-Dist: twine>=7; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: matplotlib>=3.7; extra == 'docs'
-Requires-Dist: myst-nb<2,>=1.2; extra == 'docs'
-Requires-Dist: myst-parser<5,>=4.0; extra == 'docs'
-Requires-Dist: numpydoc<2,>=1.10; extra == 'docs'
+Requires-Dist: myst-nb>=1.2; extra == 'docs'
+Requires-Dist: myst-parser>=4.0; extra == 'docs'
+Requires-Dist: numpydoc>=1.10; extra == 'docs'
 Requires-Dist: pandas>=1.5; extra == 'docs'
 Requires-Dist: polars>=0.20; extra == 'docs'
-Requires-Dist: pydata-sphinx-theme<0.17,>=0.16; extra == 'docs'
-Requires-Dist: sphinx-copybutton<0.6,>=0.5; extra == 'docs'
-Requires-Dist: sphinx-design<1,>=0.6; extra == 'docs'
-Requires-Dist: sphinx<9,>=8.1; extra == 'docs'
+Requires-Dist: pydata-sphinx-theme>=0.16; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
+Requires-Dist: sphinx-design>=0.6; extra == 'docs'
+Requires-Dist: sphinx>=8.1; extra == 'docs'
 Provides-Extra: pandas
 Requires-Dist: pandas>=1.5; extra == 'pandas'
 Provides-Extra: plot
@@ -65,6 +65,8 @@ Provides-Extra: polars
 Requires-Dist: polars>=0.20; extra == 'polars'
 Description-Content-Type: text/markdown
 
+<p align="center"><em>It is named for TMLE's clever covariate. Even the jokes in this toolbox are targeted.</em></p>
+
 # cleverly
 
 [![PyPI](https://img.shields.io/pypi/v/cleverly.svg)](https://pypi.org/project/cleverly/)
@@ -72,82 +74,51 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/esbraun/cleverly-tmle/actions/workflows/ci.yml/badge.svg)](https://github.com/esbraun/cleverly-tmle/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-087f8c.svg)](https://github.com/esbraun/cleverly-tmle/blob/main/LICENSE)
 
-**[Read the documentation](https://esbraun.github.io/cleverly-tmle/)** for the getting-started
-guide, the user guide, worked examples, and the API reference. To see a complete analysis first,
-start with [one treatment, one outcome](https://esbraun.github.io/cleverly-tmle/examples/point-treatment-tmle.html).
-
-`cleverly` is a Python library for estimating what a treatment, an offer, or a policy did, from
-data where nobody assigned it at random. It answers questions such as "did the program lower
-readmissions?", "what would sales be if every customer got the discount?", or "which patients
-should get the offer?", and it reports each answer with a confidence interval.
-
-In such data, a plain comparison of treated and untreated people mixes the treatment's effect with
-differences in who got it. Those differences come from confounders: variables, such as age or
-prior risk, that affect both who gets the treatment and the outcome. `cleverly` adjusts for the
-confounders you recorded. Before it fits anything, it writes down what must be true for the
-answer to count as a causal effect, such as "no important confounder is missing". After the fit,
-it checks the models and asks how strong a missing confounder would have to be to change the
-answer.
+`cleverly` estimates what a treatment, an offer, or a policy did, from data where nobody assigned
+it at random, with a confidence interval for each answer. It adjusts for the confounders you
+recorded, mostly with targeted maximum likelihood estimation (TMLE). Afterward it checks how
+strong a missing confounder would have to be to change the result. Read the **[documentation](https://esbraun.github.io/cleverly-tmle/)**, or start with a
+[complete analysis](https://esbraun.github.io/cleverly-tmle/examples/point-treatment-tmle.html).
 
-Most estimates come from targeted maximum likelihood estimation (TMLE). TMLE fits two models: an
-outcome model, which predicts the outcome from the treatment and the confounders, and a treatment
-model, which predicts who got the treatment. When the outcome model is imperfect, its estimate of
-the effect is biased. A correction step uses the treatment model to remove that bias. Either model
-can be any scikit-learn-compatible estimator, including gradient boosting or a stack of several
-models.
-
-*The name comes from TMLE's "clever covariate", the variable that drives that correction step.
-Even the jokes in this library are targeted.*
-
-> **Versions:** releases use `0.2.N` versions, and the public API can still change between them,
-> so pin a version for reproducible work.
+> Releases use `0.2.N` versions, and the public API can still change between them. Pin a version
+> for reproducible work.
 
 ## Key features
 
-- Effects of a one-time treatment: the average effect for everyone, for the treated, or for the
-  untreated, as a difference, a risk ratio, or an odds ratio, with two or more treatment levels.
-  Missing outcomes and missing treatments can be declared and handled.
-- Effects of policies: treating only some people by a rule, following a rule learned from the
-  data, raising each person's chance of treatment, or shifting a continuous dose or price.
-- Treatments over time: treatments that repeat, outcomes measured at the end or every period, and
-  time until an event, including events that another event, such as death, can prevent.
-- Out-of-fold model fitting, so flexible machine-learning models can be used: each row's
-  predictions come from models trained without that row, as in cross-validation. Intervals can
-  also account for sampling weights, and for groups whose members are not independent, such as
-  patients of one team.
-- Checks after the fit: an overlap check of whether similar people received each option, attempts
-  to break the result (for example, shuffling the treatment, so the estimate should be about
-  zero), and sensitivity analyses for a missing confounder.
+- One-time treatments: average effects for everyone, the treated, or the untreated, as a
+  difference, risk ratio, or odds ratio, with missing outcomes and treatments handled.
+- Effects that vary with baseline columns such as age: declared curves with intervals, or a
+  flexible curve (the EP learner) without them.
+- Policies: treating by a rule, following a learned rule, raising the chance of treatment, or
+  shifting a dose.
+- Treatments over time, including time until an event with competing events such as death.
+- Out-of-fold model fitting for flexible machine-learning models, with sampling weights and
+  clustered data.
+- Checks after the fit: overlap, attempts to break the result, and sensitivity to a missing
+  confounder.
 - Refusals instead of approximations: a request the library cannot answer correctly fails before
   any model is fit, and the error says why.
-- Other estimators beside TMLE, for comparison or for special cases, such as collaborative TMLE,
-  doubly robust TMLE, and, over time, sequential doubly robust estimation, sequential
-  g-computation and weighting, and the parametric g-formula.
-- pandas, polars, Arrow-backed pandas, and `pyarrow.Table` inputs, through
+- Other estimators for comparison or special cases, such as collaborative TMLE and the parametric
+  g-formula.
+- pandas, polars, and `pyarrow.Table` inputs, through
   [narwhals](https://narwhals-dev.github.io/narwhals/).
 
 The [technical reference](https://esbraun.github.io/cleverly-tmle/technical-reference/) lists every
-method the package ships, with its source papers and its evidence.
+method with its source papers and evidence.
 
 ## Install
 
 ```bash
-python -m pip install cleverly
+python -m pip install cleverly          # Python 3.11 or newer
+python -m pip install "cleverly[all]"   # adds pandas, polars, and plotting
 ```
 
-Python 3.11 or newer is required. Add pandas, polars, and plotting support with the `all` extra:
-
-```bash
-python -m pip install "cleverly[all]"
-```
-
-Other scikit-learn-compatible models, such as XGBoost or LightGBM, work once you install them
-yourself. The [installation guide](https://esbraun.github.io/cleverly-tmle/getting-started/installation.html)
-covers development installs and version pinning.
+The [installation guide](https://esbraun.github.io/cleverly-tmle/getting-started/installation.html)
+covers other learners, development installs, and version pinning.
 
 ## Quick start
 
-This example uses simulated data in which the true average effect is 1.5.
+Simulated data with a true average effect of 1.5:
 
 ```python
 import numpy as np
@@ -188,8 +159,7 @@ print(result["ate"].ci, "population ATE:", truth["ate"])
 print(result.assess().summary())
 ```
 
-The estimate summary gives the answer, an average effect of 1.513 with a 95% interval from 1.422
-to 1.603, which contains the true 1.5:
+The estimate is 1.513 with a 95% interval from 1.422 to 1.603, which contains the truth:
 
 ```text
                             Effect estimate (TMLE)
@@ -207,35 +177,25 @@ ate      1.513        0.046   [1.422, 1.603]    <0.0001
 ==============================================================================
 ```
 
-The summary of the question, printed first, lists four conditions the answer rests on: the
-treatment is well defined, one person's treatment does not change another's outcome, no
-confounder is missing, and every kind of person had some chance of each treatment (overlap). The
-data cannot confirm the first three, and they can only partly check overlap.
-
-The simulated data come from a linear outcome model and a logistic treatment model, so the two
-models above are correct. Because they are also simple, fitting and predicting on the same rows
-still gives a valid interval, so this fit turns off out-of-fold predictions (`cross_fit=False`).
-On your own data the right models are unknown. Use flexible models and keep the default
-out-of-fold fitting. For a continuous outcome, that fit needs the smallest and largest values the
-outcome can take, declared with `Targeting(q_bounds=(lower, upper))`; the
-[full quickstart](https://esbraun.github.io/cleverly-tmle/getting-started/quickstart.html) explains
-the settings. The intervals are valid in large samples when the models are reasonably accurate and
-the overlap condition holds.
-
-The final assessment reports that no check needs attention. Its E-value says that a missing
-confounder would need a risk ratio of 3.52 with both the treatment and the outcome, beyond the
-recorded confounders, to explain the effect away. The larger that number, the stronger a hidden
-confounder must be to overturn the answer.
-
-To choose a different estimator, call `effect.available_methods()`, which lists the methods that
-can answer the question and says why the others cannot. The
+The question summary lists the conditions the answer rests on: a well-defined treatment, no
+interference between people, no missing confounder, and overlap (every kind of person had some
+chance of each treatment). The data cannot confirm the first three.
+
+The two models here match how the data were simulated, so `cross_fit=False` is safe. On your own
+data, use flexible models and keep the default out-of-fold fitting; a continuous outcome then needs
+`Targeting(q_bounds=(lower, upper))`. The
+[full quickstart](https://esbraun.github.io/cleverly-tmle/getting-started/quickstart.html)
+explains the settings. The assessment's E-value of 3.52 means a missing confounder would need a
+risk ratio of 3.52 with both treatment and outcome to explain the effect away.
+
+`effect.available_methods()` lists the estimators that can answer the question and why the others
+cannot; the
 [methods and learners guide](https://esbraun.github.io/cleverly-tmle/user-guide/methods-learners.html)
-shows how to configure each one.
+shows how to configure them.
 
 ## Examples
 
-Each example is a complete analysis on simulated data with a known true answer, except the last,
-which uses real birth records.
+Each example uses simulated data with a known answer, except the last (real birth records).
 
 - [One treatment, one outcome](https://esbraun.github.io/cleverly-tmle/examples/point-treatment-tmle.html):
   why a simple treated-versus-untreated comparison misleads, and what happens when a model is wrong.
@@ -253,22 +213,18 @@ which uses real birth records.
 - [Smoking and twins' birth weight](https://esbraun.github.io/cleverly-tmle/examples/twins-causal-inference.html):
   a full analysis of real records, where no true answer is known.
 
-The [examples index](https://esbraun.github.io/cleverly-tmle/examples/) has the full list, sorted by
-the problem each one solves.
+The [examples index](https://esbraun.github.io/cleverly-tmle/examples/) lists them all.
 
 ## How cleverly is tested
 
-More than 100 registered simulation studies check the shipped methods on data where the true answer
-is known. Each one tests whether the estimates center on the truth and whether the 95% intervals
-contain it as often as they should. Where an established package computes the same quantity, such
-as the R packages `tmle`, `tmle3`, `ltmle`, `lmtp`, `drtmle`, `ctmle`, and `survtmle` or the
-Python packages zEpid and EconML, the study also compares `cleverly`'s answers with that package's.
-Many methods have no such package, and their studies rely on the known truth and on the behavior
-the method's theory predicts. For a few methods the comparison with another package has not run
-yet, and their pages say so. `cleverly` marks a result experimental when no study covers its
+More than 100 registered simulation studies check the shipped methods on data with a known answer:
+whether estimates center on the truth and 95% intervals cover it as often as they should. Where
+an established package computes the same quantity (R `tmle`, `tmle3`, `ltmle`, `lmtp`, `drtmle`,
+`ctmle`, `survtmle`; Python zEpid and EconML), the study compares answers too. Some comparisons
+have not run yet, and those pages say so. A result is marked experimental when no study covers its
 setup. The
 [validation grid](https://esbraun.github.io/cleverly-tmle/technical-reference/method-evidence/validation-grid.html)
-lists every study and its results.
+lists every study.
 
 ## Documentation
 
@@ -286,22 +242,19 @@ lists every study and its results.
 
 ## Contributing
 
-Bug reports and questions go to the
-[issue tracker](https://github.com/esbraun/cleverly-tmle/issues).
-[CONTRIBUTING.md](https://github.com/esbraun/cleverly-tmle/blob/main/CONTRIBUTING.md) gives the
-development setup, the checks each change needs, and the commit style.
+Report bugs and questions on the
+[issue tracker](https://github.com/esbraun/cleverly-tmle/issues). See
+[CONTRIBUTING.md](https://github.com/esbraun/cleverly-tmle/blob/main/CONTRIBUTING.md) for setup,
+checks, and commit style.
 
 ## Citing
 
-There is no DOI yet. Cite the version or repository commit you used, and the method papers that
-the [technical reference](https://esbraun.github.io/cleverly-tmle/technical-reference/) and the
-[references page](https://esbraun.github.io/cleverly-tmle/references.html) list.
+There is no DOI yet. Cite the version or commit you used and the method papers listed in the
+[technical reference](https://esbraun.github.io/cleverly-tmle/technical-reference/).
 
 ## License
 
-`cleverly` is under the
-[MIT License](https://github.com/esbraun/cleverly-tmle/blob/main/LICENSE). The R comparison
-runners under `tests/canonical/` are under the
-[GNU General Public License v3.0](https://github.com/esbraun/cleverly-tmle/blob/main/tests/canonical/LICENSE),
-because they call reference R packages in the same process and one of those packages is AGPL-3.
-No published distribution includes them, so an installed copy of `cleverly` is MIT alone.
+MIT. The R comparison runners under `tests/canonical/` are
+[GPL-3.0](https://github.com/esbraun/cleverly-tmle/blob/main/tests/canonical/LICENSE) because they
+call AGPL-3 R packages in-process; they are not distributed, so an installed `cleverly` is MIT
+alone.

cleverly-0.2.1/README.md

@@ -0,0 +1,193 @@
+<p align="center"><em>It is named for TMLE's clever covariate. Even the jokes in this toolbox are targeted.</em></p>
+
+# cleverly
+
+[![PyPI](https://img.shields.io/pypi/v/cleverly.svg)](https://pypi.org/project/cleverly/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-1565c0.svg)](https://www.python.org/)
+[![CI](https://github.com/esbraun/cleverly-tmle/actions/workflows/ci.yml/badge.svg)](https://github.com/esbraun/cleverly-tmle/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-087f8c.svg)](https://github.com/esbraun/cleverly-tmle/blob/main/LICENSE)
+
+`cleverly` estimates what a treatment, an offer, or a policy did, from data where nobody assigned
+it at random, with a confidence interval for each answer. It adjusts for the confounders you
+recorded, mostly with targeted maximum likelihood estimation (TMLE). Afterward it checks how
+strong a missing confounder would have to be to change the result. Read the **[documentation](https://esbraun.github.io/cleverly-tmle/)**, or start with a
+[complete analysis](https://esbraun.github.io/cleverly-tmle/examples/point-treatment-tmle.html).
+
+> Releases use `0.2.N` versions, and the public API can still change between them. Pin a version
+> for reproducible work.
+
+## Key features
+
+- One-time treatments: average effects for everyone, the treated, or the untreated, as a
+  difference, risk ratio, or odds ratio, with missing outcomes and treatments handled.
+- Effects that vary with baseline columns such as age: declared curves with intervals, or a
+  flexible curve (the EP learner) without them.
+- Policies: treating by a rule, following a learned rule, raising the chance of treatment, or
+  shifting a dose.
+- Treatments over time, including time until an event with competing events such as death.
+- Out-of-fold model fitting for flexible machine-learning models, with sampling weights and
+  clustered data.
+- Checks after the fit: overlap, attempts to break the result, and sensitivity to a missing
+  confounder.
+- Refusals instead of approximations: a request the library cannot answer correctly fails before
+  any model is fit, and the error says why.
+- Other estimators for comparison or special cases, such as collaborative TMLE and the parametric
+  g-formula.
+- pandas, polars, and `pyarrow.Table` inputs, through
+  [narwhals](https://narwhals-dev.github.io/narwhals/).
+
+The [technical reference](https://esbraun.github.io/cleverly-tmle/technical-reference/) lists every
+method with its source papers and evidence.
+
+## Install
+
+```bash
+python -m pip install cleverly          # Python 3.11 or newer
+python -m pip install "cleverly[all]"   # adds pandas, polars, and plotting
+```
+
+The [installation guide](https://esbraun.github.io/cleverly-tmle/getting-started/installation.html)
+covers other learners, development installs, and version pinning.
+
+## Quick start
+
+Simulated data with a true average effect of 1.5:
+
+```python
+import numpy as np
+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)
+
+# 1. Describe the data: the outcome, the treatment, and the confounders to adjust for.
+study = CausalStudy(
+    frame,
+    design=PointTreatment(
+        outcome="Y",
+        treatment="A",
+        adjustment=("W1", "W2", "W3", "W4"),
+    ),
+)
+
+# 2. Name the question: the average effect of A = 1 compared with A = 0 (ATE).
+#    The summary lists the conditions the answer rests on and the methods that can fit it.
+effect = study.identify(ATE(reference=0))
+print(effect.summary())
+
+# 3. Fit the outcome model and the treatment model, then apply the correction step.
+result = effect.estimate(
+    outcome_learner=LinearRegression(),
+    # An unpenalized logistic regression, which matches how the data were simulated.
+    treatment_learner=LogisticRegression(C=np.inf, max_iter=1000),
+    cross_fit=False,
+    random_state=7,
+)
+print(result.summary())
+# The truth is known only because the data are simulated.
+print(result["ate"].ci, "population ATE:", truth["ate"])
+
+# 4. Check the fit and how sensitive the answer is to a missing confounder.
+print(result.assess().summary())
+```
+
+The estimate is 1.513 with a 95% interval from 1.422 to 1.603, which contains the truth:
+
+```text
+                            Effect estimate (TMLE)
+==============================================================================
+Question:      average effect of A on   Rows:                            2,000
+               Y (1 compared with 0)    Treated share:                   0.506
+Outcome:       Y (continuous)           Out-of-fold predictions:            no
+Adjusted for:  W1, W2, W3, W4           Outcome model:       linear regression
+Method:        targeted maximum         Treatment model:   logistic regression
+               likelihood (TMLE)        Probability limits:  [0.01471, 0.9853]
+==============================================================================
+      estimate   std. error           95% CI    p-value
+------------------------------------------------------------------------------
+ate      1.513        0.046   [1.422, 1.603]    <0.0001
+==============================================================================
+```
+
+The question summary lists the conditions the answer rests on: a well-defined treatment, no
+interference between people, no missing confounder, and overlap (every kind of person had some
+chance of each treatment). The data cannot confirm the first three.
+
+The two models here match how the data were simulated, so `cross_fit=False` is safe. On your own
+data, use flexible models and keep the default out-of-fold fitting; a continuous outcome then needs
+`Targeting(q_bounds=(lower, upper))`. The
+[full quickstart](https://esbraun.github.io/cleverly-tmle/getting-started/quickstart.html)
+explains the settings. The assessment's E-value of 3.52 means a missing confounder would need a
+risk ratio of 3.52 with both treatment and outcome to explain the effect away.
+
+`effect.available_methods()` lists the estimators that can answer the question and why the others
+cannot; the
+[methods and learners guide](https://esbraun.github.io/cleverly-tmle/user-guide/methods-learners.html)
+shows how to configure them.
+
+## Examples
+
+Each example uses simulated data with a known answer, except the last (real birth records).
+
+- [One treatment, one outcome](https://esbraun.github.io/cleverly-tmle/examples/point-treatment-tmle.html):
+  why a simple treated-versus-untreated comparison misleads, and what happens when a model is wrong.
+- [Flexible models and shared teams](https://esbraun.github.io/cleverly-tmle/examples/cross-fitting.html):
+  gradient boosting, out-of-fold predictions, and patients whose results move together.
+- [Three offer policies](https://esbraun.github.io/cleverly-tmle/examples/interventions.html):
+  offering a program only to high-risk patients, raising each patient's chance of an offer, or
+  raising how much each patient gets.
+- [Who should get the offer](https://esbraun.github.io/cleverly-tmle/examples/treatment-rules.html):
+  learning a treatment rule and scoring it on patients it was not learned from.
+- [Readmission when death can come first](https://esbraun.github.io/cleverly-tmle/examples/longitudinal-survival.html):
+  time until an event, with a competing event and dropout.
+- [Weekly offer policies](https://esbraun.github.io/cleverly-tmle/examples/sequential-offers.html):
+  a treatment repeated every week, where earlier offers change later behavior.
+- [Smoking and twins' birth weight](https://esbraun.github.io/cleverly-tmle/examples/twins-causal-inference.html):
+  a full analysis of real records, where no true answer is known.
+
+The [examples index](https://esbraun.github.io/cleverly-tmle/examples/) lists them all.
+
+## How cleverly is tested
+
+More than 100 registered simulation studies check the shipped methods on data with a known answer:
+whether estimates center on the truth and 95% intervals cover it as often as they should. Where
+an established package computes the same quantity (R `tmle`, `tmle3`, `ltmle`, `lmtp`, `drtmle`,
+`ctmle`, `survtmle`; Python zEpid and EconML), the study compares answers too. Some comparisons
+have not run yet, and those pages say so. A result is marked experimental when no study covers its
+setup. The
+[validation grid](https://esbraun.github.io/cleverly-tmle/technical-reference/method-evidence/validation-grid.html)
+lists every study.
+
+## Documentation
+
+- [Getting started](https://esbraun.github.io/cleverly-tmle/getting-started/): install, a first
+  fit, and how to read a result.
+- [Workflow](https://esbraun.github.io/cleverly-tmle/workflow.html): one analysis from the
+  question to the report.
+- [User guide](https://esbraun.github.io/cleverly-tmle/user-guide/): data, questions, models,
+  methods, treatments over time, results, and refusals.
+- [Examples](https://esbraun.github.io/cleverly-tmle/examples/): complete analyses to adapt.
+- [Technical reference](https://esbraun.github.io/cleverly-tmle/technical-reference/): for
+  statisticians, the exact quantities, conditions, papers, and evidence behind each method.
+- [Python API](https://esbraun.github.io/cleverly-tmle/api/): every public object and its
+  signature.
+
+## Contributing
+
+Report bugs and questions on the
+[issue tracker](https://github.com/esbraun/cleverly-tmle/issues). See
+[CONTRIBUTING.md](https://github.com/esbraun/cleverly-tmle/blob/main/CONTRIBUTING.md) for setup,
+checks, and commit style.
+
+## Citing
+
+There is no DOI yet. Cite the version or commit you used and the method papers listed in the
+[technical reference](https://esbraun.github.io/cleverly-tmle/technical-reference/).
+
+## License
+
+MIT. The R comparison runners under `tests/canonical/` are
+[GPL-3.0](https://github.com/esbraun/cleverly-tmle/blob/main/tests/canonical/LICENSE) because they
+call AGPL-3 R packages in-process; they are not distributed, so an installed `cleverly` is MIT
+alone.

{cleverly-0.2.0 → cleverly-0.2.1}/docs/api/estimands.md

@@ -30,5 +30,7 @@ that reading adds.
    cleverly.IncrementalEffect
    cleverly.MSMProjection
    cleverly.msm.MSM
+   cleverly.msm.working_model_means
+   cleverly.ConditionalContrast
    cleverly.ControlledDirectEffect
 ```

{cleverly-0.2.0 → cleverly-0.2.1}/docs/api/index.md

@@ -18,6 +18,7 @@ results-assessment
 learners
 interventions
 sensitivity-validation
+plotting
 datasets
 exceptions
 object-index