augsynth-py 0.3.0__tar.gz

augsynth_py-0.3.0/.gitignore

@@ -0,0 +1,91 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb_checkpoints
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project-specific
+notebooks/scratch/
+notebooks/*.ipynb
+!notebooks/README.md
+
+# R artifacts (in case someone runs R locally for validation)
+.Rhistory
+.RData
+.Ruserdata
+
+# Claude Code (local agent state, settings, scratch plans)
+.claude/
+.claudeignore
+CLAUDE.local.md
+docs/plans/
+
+# Paper working material (local only — not part of the package)
+paper/
+
+# Git worktrees (local isolated workspaces)
+.worktrees/
+
+# papers/: only SOURCES.md is tracked; keep local reading copies untracked
+papers/*.pdf

augsynth_py-0.3.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+(with the usual 0.x caveat: minor versions may break the API).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-03
+
+First public release on PyPI. Everything below is new in the sense that no
+earlier version was ever published; internally this tree evolved through the
+v0.1 (classical SCM) and v0.2 (ridge ASCM) design milestones.
+
+### Added
+
+- `Synth`: classical simplex-constrained synthetic control
+  (Abadie, Diamond & Hainmueller 2010; outcome-only Doudchenko & Imbens 2016
+  form, analogue of R `augsynth(progfunc = "None", scm = TRUE)`), with
+  optional unit fixed effects (`fixedeff=True` default).
+- `AugSynth`: ridge-augmented synthetic control (Ben-Michael, Feller &
+  Rothstein 2021, §2.3–2.4), with leave-one-out cross-validation of the
+  ridge penalty (auto-grid or user grid) or a fixed `lambda_`.
+- `conformal_pvalue` / `conformal_interval`: exact conformal inference for a
+  constant post-period effect (Chernozhukov, Wuthrich & Zhu 2021, §3), with
+  moving-block (default) and iid permutation schemes and refit-under-the-null
+  residuals.
+- Multi-treated fits: `treated` accepts an iterable of units; the effect is
+  estimated on the treated-group mean.
+- `conformal_interval` detects a non-contiguous acceptance region (accepted
+  grid points with interior rejected gaps — demonstrated on the Basque panel,
+  where the gap contains the point estimate itself) and emits a `UserWarning`
+  clarifying that the returned bounds are the conservative min/max envelope
+  (clean-room audit D-6, Recommendation 4).
+- Numerical parity suite against R `augsynth` (`tests/validation_against_r/`),
+  including exact p-value-curve parity on the Basque panel.
+- PEP 561 `py.typed` marker; `mypy --strict` clean on `src/`.
+
+[Unreleased]: https://github.com/mrcsvg/augsynth-py/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/mrcsvg/augsynth-py/releases/tag/v0.3.0

augsynth_py-0.3.0/CLAUDE.md

@@ -0,0 +1,211 @@
+# augsynth-py
+
+A Python implementation of Augmented Synthetic Control Methods (ASCM) and related
+geo-experimentation methodology. The end goal is feature parity with the R
+`augsynth` package and a higher-level orchestration layer comparable to Meta's
+GeoLift (R).
+
+This file is the entry point for AI coding assistants working on this repo.
+Read it before starting any task.
+
+---
+
+## Project goal
+
+Provide a Python-native, methodologically faithful implementation of:
+
+1. Classical synthetic control (Abadie, Diamond & Hainmueller, 2010).
+2. Augmented synthetic control with ridge augmentation (Ben-Michael, Feller & Rothstein, 2021).
+3. Generalized synthetic control (Xu, 2017).
+4. Power analysis and market selection for geo-experiments (the orchestration
+   layer that GeoLift provides on top of `augsynth`).
+
+The package must be usable in production data science workflows. Methodology
+correctness is the top priority, performance is secondary, ergonomics third.
+
+## Implementation strategy: clean-room from papers
+
+All algorithms are implemented **from the published papers**, not by translating
+the R `augsynth` source code. This keeps the project under a permissive license
+(MIT) and forces a deeper understanding of the methods.
+
+Reference implementations in R (`augsynth`, `gsynth`, `Synth`, `GeoLift`) are
+used **only as oracles for validation tests**, never as a source to translate
+from. Do not copy R source code into this repo.
+
+## Canonical references
+
+The implementation must be traceable to these papers. New code should cite the
+relevant paper and equation in docstrings.
+
+- Abadie, Diamond & Hainmueller (2010). *Synthetic Control Methods for
+  Comparative Case Studies*. JASA.
+- Abadie (2021). *Using Synthetic Controls: Feasibility, Data Requirements,
+  and Methodological Aspects*. JEL.
+- Ben-Michael, Feller & Rothstein (2021). *The Augmented Synthetic Control
+  Method*. JASA.
+- Xu (2017). *Generalized Synthetic Control Method*. Political Analysis.
+- Doudchenko & Imbens (2016). *Balancing, Regression, Difference-in-Differences
+  and Synthetic Control Methods: A Synthesis*. NBER WP 22791.
+- Chernozhukov, Wuthrich & Zhu (2021). *An Exact and Robust Conformal Inference
+  Method for Counterfactual and Synthetic Controls*. JASA.
+
+## Architectural decisions (already made — do not relitigate without reason)
+
+| Concern              | Choice                            | Why                                                    |
+|----------------------|-----------------------------------|--------------------------------------------------------|
+| Language             | Python 3.11+                      | Practical adoption, scientific ecosystem               |
+| Numerics             | `numpy`, `scipy`                  | Native BLAS/LAPACK, stable APIs                        |
+| Convex optimization  | `cvxpy` (OSQP / Clarabel backends)| Cleanest expression of constrained QPs                 |
+| Tabular data         | `polars`                          | Fast, sane API, scales to panel datasets               |
+| Parallelism          | `joblib`                          | Power analysis is embarrassingly parallel              |
+| Build backend        | `hatchling`                       | Modern, simple, PEP 621 native                         |
+| Layout               | `src/` layout                     | Avoids accidental imports during testing               |
+| Lint + format        | `ruff`                            | One tool, fast                                         |
+| Type checking        | `mypy --strict` on `src/`         | Catch shape/contract bugs early                        |
+| Tests                | `pytest`                          | Standard                                               |
+| Validation oracle    | R `augsynth` via `rpy2`           | Ground truth for parity tests                          |
+
+**Do not introduce new dependencies without justification in the PR.**
+**Do not reach for Rust/C extensions before profiling identifies a real hot
+loop.** This is a project rule, not a suggestion. Premature optimization in a
+foreign language has killed similar projects.
+
+## Validation rule (non-negotiable)
+
+Every public estimator must have at least one test in
+`tests/validation_against_r/` that:
+
+1. Runs the same input through both the Python implementation and the R
+   reference (`augsynth` / `gsynth` / `Synth`) via `rpy2`.
+2. Asserts numerical agreement on weights, counterfactuals, and ATT estimates
+   within a documented tolerance (default `atol=1e-6, rtol=1e-5`; relax with
+   justification only).
+3. Uses a fixture from the `GeoLift_PreTest` panel (40 US cities, 90 days)
+   loaded once per session.
+
+PRs that add a new estimator without a parity test should be rejected.
+
+## Roadmap and scope
+
+Shipped so far: classical `Synth` (v0.1), ridge-augmented `AugSynth` with
+LOO-CV (v0.2), conformal inference per CWZ 2021 (v0.3) — each with unit +
+R-parity tests and a clean-room audit in `docs/`.
+
+Critical path toward end-to-end geo-experiments (the project's reason to
+exist), in order:
+
+1. **v0.4 — power analysis / MDE** (`augsynth_py.power`): effect injection +
+   refit + detection rate via conformal inference; parallel grid with joblib.
+   Parity oracle: `GeoLiftPower`.
+2. **v0.5 — market selection**: candidate ranking over treatment sets ×
+   durations, `GeoLiftMarketSelection` analogue. Completes the single-cell
+   GeoLift flow.
+3. **v0.6+ — multi-cell experiments**; then, if demand appears, auxiliary
+   covariates $X_i$ and GSC (Xu 2017, incl. BFR 2021 §4 augmentation).
+
+Deferred until further notice (do not start without maintainer sign-off):
+
+- AugSynth with auxiliary covariates / predictors $X_i$ — needs `Synth`
+  predictor support first.
+- Matrix-completion augmentation (Athey et al. 2021) — would land as a
+  sibling estimator.
+- GSC / gsynth (Xu 2017) and BFR 2021 §4 GSC augmentation.
+
+Permanently out of scope:
+
+- Bayesian variants — that's CausalPy's territory.
+- GPU acceleration — not needed.
+- Rust extensions — not needed, see above.
+
+## Repository layout
+
+```
+augsynth-py/
+├── CLAUDE.md                       <- you are here
+├── README.md
+├── CHANGELOG.md                    <- Keep a Changelog format
+├── LICENSE                         <- MIT
+├── pyproject.toml
+├── src/augsynth_py/
+│   ├── __init__.py                 <- public exports
+│   ├── _version.py                 <- single source of truth for the version
+│   ├── exceptions.py               <- domain exceptions
+│   ├── inference.py                <- conformal inference (CWZ 2021)
+│   ├── py.typed                    <- PEP 561 marker
+│   └── synth/                      <- estimator implementations
+├── tests/
+│   ├── conftest.py                 <- shared fixtures
+│   ├── unit/                       <- pure-Python unit tests, no R required
+│   └── validation_against_r/       <- parity tests, require R + augsynth
+├── docs/
+│   ├── methodology.md              <- maps code to paper sections/equations
+│   ├── known-issues.md             <- open investigations register
+│   ├── releasing.md                <- PyPI release runbook
+│   └── clean-room-audit-*.md       <- one audit per estimator/module
+├── papers/
+│   └── SOURCES.md                  <- link index (PDFs are not tracked)
+├── notebooks/                      <- exploratory notebooks, not shipped
+└── .github/workflows/
+    ├── ci.yml                      <- lint, type, unit tests
+    ├── validation.yml              <- parity tests against R
+    └── release.yml                 <- tag-triggered PyPI trusted publishing
+```
+
+## Code conventions
+
+- Type hints everywhere in `src/`. Public APIs use `numpy.typing.NDArray` for
+  arrays.
+- Docstrings: NumPy style. Every public function cites paper + equation when
+  implementing a known method.
+- No `print()` in library code. Use the `logging` module at INFO/DEBUG.
+- No global mutable state. Estimators are classes with `fit()` populating
+  trailing-underscore fitted attributes (`att_`, `weights_`, ...); a separate
+  `predict()` has not been needed so far — introduce one only with maintainer
+  sign-off on the API shape.
+- Random seeds: every stochastic function takes `rng: np.random.Generator`,
+  never reads global state.
+- Errors: raise `ValueError` for bad input, custom exceptions in
+  `augsynth_py.exceptions` for domain errors.
+
+## Testing conventions
+
+- `tests/unit/` runs in CI on every push, no R required.
+- `tests/validation_against_r/` runs in a separate CI job that installs R
+  and the reference packages. Use `pytest.importorskip("rpy2")` so local
+  developers without R can still run the unit suite.
+- Parity fixtures are loaded from the R packages themselves via `rpy2`
+  (`GeoLift_PreTest` in `tests/validation_against_r/conftest.py`) or from
+  public CSVs under `notebooks/_data/` (Basque panel). There is no
+  `tests/fixtures/` directory today; create one only if a fixture cannot
+  live in either of those places.
+- Snapshot tests for plotting outputs are NOT used; we test data, not pixels.
+
+## Common task recipes
+
+### Adding a new estimator
+
+1. Create `src/augsynth_py/synth/<name>.py` with a class implementing `fit` and
+   `predict`.
+2. Cite the paper and equation in the class docstring.
+3. Add unit tests in `tests/unit/test_<name>.py` covering edge cases (single
+   treated unit, perfect pre-period fit, degenerate donor pool).
+4. Add a parity test in `tests/validation_against_r/test_<name>.py` against the
+   R reference.
+5. Document the estimator in `docs/methodology.md` with the mapping to paper
+   sections.
+6. Export from `src/augsynth_py/__init__.py`.
+
+### Updating dependencies
+
+- Edit `pyproject.toml`, not `requirements.txt` (we don't have one).
+- Justify the dependency in the PR description.
+- Prefer `scipy` / `numpy` primitives over new packages.
+
+## Things to confirm with the maintainer before doing
+
+- Adding a dependency.
+- Changing the public API of any class already exported from `__init__.py`.
+- Relaxing a validation tolerance.
+- Adding a Rust / Cython / C extension.
+- Adding GPU support.

augsynth_py-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 augsynth-py contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

augsynth_py-0.3.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: augsynth-py
+Version: 0.3.0
+Summary: Augmented Synthetic Control Methods and geo-experimentation tooling for Python.
+Project-URL: Repository, https://github.com/mrcsvg/augsynth-py
+Project-URL: Issues, https://github.com/mrcsvg/augsynth-py/issues
+Project-URL: Changelog, https://github.com/mrcsvg/augsynth-py/blob/main/CHANGELOG.md
+Author: augsynth-py contributors
+License: MIT License
+        
+        Copyright (c) 2026 augsynth-py contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: causal-inference,econometrics,geo-experiments,marketing-science,synthetic-control
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cvxpy>=1.5
+Requires-Dist: joblib>=1.3
+Requires-Dist: numpy>=1.26
+Requires-Dist: polars>=1.0
+Requires-Dist: scipy>=1.12
+Provides-Extra: dev
+Requires-Dist: ipykernel; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Provides-Extra: validation
+Requires-Dist: pandas>=2.0; extra == 'validation'
+Requires-Dist: pyarrow>=14.0; extra == 'validation'
+Requires-Dist: rpy2>=3.5; extra == 'validation'
+Description-Content-Type: text/markdown
+
+# augsynth-py
+
+A Python implementation of Augmented Synthetic Control Methods and
+geo-experimentation tooling. Methodologically faithful to the published
+literature, validated against the R reference implementations.
+
+> **Status: alpha.** The estimator API is functional and validated against R,
+> but not yet stable across releases. Pin the exact version in production.
+
+## What this is
+
+Synthetic control methods for causal inference, with a focus on the use case
+that matters most in modern marketing science: measuring the lift of geo-level
+ad campaigns. The roadmap targets feature parity with:
+
+- The R [`augsynth`](https://github.com/ebenmichael/augsynth) package
+  (estimators).
+- Meta's R [`GeoLift`](https://github.com/facebookincubator/GeoLift) package
+  (orchestration: power analysis, market selection, multi-cell).
+
+## Why another synthetic control package
+
+There are good Python options for parts of this problem (`CausalPy`,
+`pysyncon`, `tfcausalimpact`), but none provides Augmented Synthetic Control
+Methods (Ben-Michael, Feller & Rothstein 2021) together with the
+GeoLift-style orchestration layer in a single Python-native package.
+
+## Installation
+
+```bash
+pip install augsynth-py
+```
+
+For the validation test suite (requires R and the `augsynth` R package):
+
+```bash
+pip install "augsynth-py[validation]"
+```
+
+## Quickstart
+
+```python
+import numpy as np
+import polars as pl
+
+from augsynth_py import AugSynth, conformal_pvalue
+
+# Simulated geo panel: 20 markets x 90 days, +10% lift in geo_00 from day 70.
+rng = np.random.default_rng(7)
+days = np.arange(90)
+base = rng.uniform(80, 120, 20)
+trend = rng.normal(0.1, 0.05, 20)
+seasonal = 5 * np.sin(2 * np.pi * days / 7)
+
+panel = pl.concat(
+    pl.DataFrame(
+        {
+            "geo": f"geo_{i:02d}",
+            "day": days,
+            "sales": base[i] + trend[i] * days + seasonal + rng.normal(0, 1.0, 90),
+        }
+    )
+    for i in range(20)
+).with_columns(
+    pl.when((pl.col("geo") == "geo_00") & (pl.col("day") >= 70))
+    .then(pl.col("sales") * 1.10)
+    .otherwise(pl.col("sales"))
+    .alias("sales")
+)
+
+fit = AugSynth(lambda_=1.0).fit(
+    panel,
+    unit="geo",
+    time="day",
+    outcome="sales",
+    treated="geo_00",
+    treatment_time=70,
+)
+
+print(f"ATT: {fit.att_:.2f} ({fit.att_pct_:+.1%})")
+# ATT: 10.29 (+9.8%)
+
+# The noise in this simulated panel is iid; on real (autocorrelated) series
+# keep the default permutation_type="block".
+p = conformal_pvalue(fit, permutation_type="iid", rng=np.random.default_rng(0))
+print(f"conformal p-value: {p:.4f}")
+# conformal p-value: 0.0120
+```
+
+What's available today:
+
+- `Synth` — classical simplex-constrained synthetic control
+  (outcome-only form, `augsynth(progfunc = "None", scm = TRUE)` analogue),
+  with optional unit fixed effects.
+- `AugSynth` — ridge-augmented synthetic control (Ben-Michael, Feller &
+  Rothstein 2021), with leave-one-out CV for the ridge penalty by default.
+- `conformal_pvalue` / `conformal_interval` — exact conformal inference for
+  a constant post-period effect (Chernozhukov, Wuthrich & Zhu 2021), block
+  and iid permutation schemes.
+- Multi-treated fits: pass an iterable of units as `treated` to estimate the
+  effect on the treated-group mean.
+
+The GeoLift-style orchestration layer (power analysis, market selection) is
+the next milestone on the roadmap.
+
+## Methodological references
+
+The implementation is based on the published literature, not translated from
+the R sources. Key references:
+
+- Abadie, Diamond & Hainmueller (2010). Synthetic Control Methods for
+  Comparative Case Studies. *JASA*.
+- Ben-Michael, Feller & Rothstein (2021). The Augmented Synthetic Control
+  Method. *JASA*.
+- Xu (2017). Generalized Synthetic Control Method. *Political Analysis*.
+- Chernozhukov, Wuthrich & Zhu (2021). An Exact and Robust Conformal Inference
+  Method for Counterfactual and Synthetic Controls. *JASA*.
+
+See `docs/methodology.md` for the mapping between code and equations.
+
+## Validation against R
+
+Every estimator in this package is validated numerically against the R
+reference implementation. The validation suite lives in
+`tests/validation_against_r/` and runs as a separate CI job.
+
+If you find a discrepancy with the R output beyond documented tolerances,
+please open an issue — that is a bug.
+
+## Contributing
+
+Read [`CLAUDE.md`](CLAUDE.md) first. It contains the architectural decisions,
+coding conventions, and the validation rule that PRs must satisfy.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).