geoexp 0.1.0__tar.gz

geoexp-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.hypothesis/
+
+# Type checking / lint caches
+.mypy_cache/
+.ruff_cache/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# R artifacts (validation runs)
+.Rhistory
+.RData
+.Ruserdata
+
+# Claude Code (local agent state, settings, scratch plans)
+.claude/
+.claudeignore
+CLAUDE.local.md
+docs/plans/
+
+# Git worktrees (local isolated workspaces)
+.worktrees/

geoexp-0.1.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# 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]
+
+Nothing yet.
+
+## [0.1.0] - 2026-09-20
+
+### Added
+
+- **Public API for single-cell market selection** (project milestone v0.5),
+  per `docs/design-2026-09-05-v0.5-api.md`: `rank_designs()` ranks explicit
+  candidate treated sets x durations by what each design can detect, and
+  `DesignRanking` carries the ranking frame plus the underlying
+  `augsynth_py.PowerResults`. Consumes augsynth-py through its public API only,
+  with one child generator per candidate via `rng.spawn` and candidate-level
+  parallelism.
+- `mde` interpolated off the power curve, with the upstream grid point kept
+  alongside as `mde_grid`. The grid value takes only four distinct values
+  across the 39 fixture candidates, which makes it useless as a sort key; see
+  `docs/methodology.md`.
+- `investment` column when `cpic` is supplied — exactly parity-testable.
+- `enumerate_candidates()`, pulled forward from 0.2.x: ranks units by
+  correlation with the rest of the panel and draws capped combinations of the
+  requested sizes, with `include`/`exclude` and optional reproducible random
+  sampling. A separate function, not a `rank_designs` parameter, so bringing
+  your own candidates stays the primary path.
+- `null_bias` and `h1_calibration_error` diagnostics, adapted from
+  mrcsvg/augsynth-py#22. `null_bias` is the honest analog of GeoLift's
+  `abs_lift_in_zero`; `h1_calibration_error` catches a design that detects at
+  the wrong magnitude. The two overlap on well-behaved panels — see
+  `docs/methodology.md`.
+- Parity suite against R `GeoLiftMarketSelection` on the power curve at 240
+  cells, with self-calibrating tolerances derived from the measured noise
+  floor rather than from a single draw.
+- `docs/geolift-oracle-characterization.md`: measured input/output surface of
+  the R oracle, which of its columns cannot be reproduced under the clean-room
+  rule, and the rejected cross-package benchmark experiment.
+
+### Changed
+
+- `CLAUDE.md` validation rule now requires parity only for features with a
+  reproducible oracle counterpart; features without one must be listed with a
+  reason and covered by unit tests plus a methodology entry.
+- The `validation` extra no longer pulls `pandas` or `pyarrow`: the R bridge
+  converts to Polars directly (adapted from mrcsvg/augsynth-py#22).
+
+### Added (skeleton)
+
+- Repository skeleton per `docs/geoexp-bootstrap-spec.md`: src layout with
+  `py.typed`, tooling ported from augsynth-py (ruff, mypy strict, pytest),
+  CI workflows (lint/type/unit + min-deps, GeoLift validation, tag-triggered
+  PyPI trusted publishing), and placeholder `selection` module. No public
+  API yet — that lands with the v0.5 design doc.
+
+[Unreleased]: https://github.com/mrcsvg/geoexp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mrcsvg/geoexp/releases/tag/v0.1.0

geoexp-0.1.0/CLAUDE.md

@@ -0,0 +1,124 @@
+# geoexp
+
+Geo-experiment design on top of `augsynth-py`: market selection, power-based
+design ranking, and experiment reporting. This file is the entry point for AI
+coding assistants working on this repo. Read it before starting any task.
+
+---
+
+## Project goal
+
+Answer *which design should I run?* for single-cell (and later multi-cell)
+geo-experiments: rank candidate treated sets × experiment durations by what
+each design can detect, with GeoLift-shaped reporting.
+
+The **authoritative statement of the package boundary** lives in the
+package-boundary section of
+[augsynth-py's CLAUDE.md](https://github.com/mrcsvg/augsynth-py/blob/main/CLAUDE.md):
+*"given a design"* (augsynth-py: estimators, inference, power/MDE) vs.
+*"choose a design"* (geoexp: market selection, budget/ROI, multi-cell,
+reporting). Do not add estimators, inference, or power simulation here.
+
+## Consumption rule (the one rule augsynth-py doesn't need)
+
+geoexp consumes augsynth-py **through its public API only**:
+
+- Never import an underscore-prefixed name from `augsynth_py`.
+- If market selection appears to need something the public API cannot
+  express, the fix is a proposal against augsynth-py's API — never a
+  private-attribute reach-in, never a fork of the logic.
+- Contract patterns (documented in `augsynth_py.simulate_power`'s Notes):
+  one child generator per candidate via `rng.spawn(n)`; parallelize across
+  candidates with `n_jobs=1` passed down (joblib does not nest workers);
+  recommend `AugSynth(lambda_=...)` in docs for large grids.
+
+## Implementation strategy: clean-room from published material
+
+Implemented from published material (Abadie 2021 §5 in-time placebos; the
+GeoLift methodology publications; CWZ 2021 via augsynth-py). The R `GeoLift`
+package is a **parity oracle only**, driven via `rpy2` in
+`tests/validation_against_r/` — its source is never translated and never
+copied into this repo. MIT license; no association with Meta's GeoLift is
+implied (the working name `geolift-py` was dropped for exactly that reason).
+
+## Validation rule (non-negotiable)
+
+Every public ranking/selection feature **that has a reproducible
+`GeoLiftMarketSelection` counterpart** must have at least one test in
+`tests/validation_against_r/` that runs the same input through this package
+and through R `GeoLiftMarketSelection` via rpy2, asserting numerical
+agreement within a documented tolerance (default `atol=1e-6, rtol=1e-5`;
+relax with justification only), on the `GeoLift_PreTest` fixture.
+
+A feature with no reproducible counterpart is **not exempt by default**: it
+must be listed in `docs/geolift-oracle-characterization.md` §6 with the
+reason it cannot be compared, and covered by unit tests plus a
+`docs/methodology.md` entry stating what it is and what it is not. Adding an
+entry to that list is a maintainer decision, not a contributor's.
+
+PRs that add a public feature without either a parity test or a recorded
+exclusion should be rejected.
+
+## Version map
+
+| Project milestone | geoexp release | Content |
+|---|---|---|
+| v0.5 | 0.1.x | Single-cell market selection, candidate enumeration, cpic |
+| v0.5+ | 0.2.x | Budget-constrained selection |
+| v0.6 | 0.3.x+ | Multi-cell designs |
+
+augsynth-py's own releases number independently; geoexp's dependency floor
+is `augsynth-py>=0.5.0` (the release that froze the power-API contract —
+see `docs/power-api-contract-review.md` in that repo).
+
+## Repository layout
+
+```
+geoexp/
+├── CLAUDE.md                       <- you are here
+├── README.md
+├── CHANGELOG.md                    <- Keep a Changelog format
+├── LICENSE                         <- MIT
+├── pyproject.toml                  <- hatchling, PEP 621, src layout
+├── src/geoexp/
+│   ├── __init__.py                 <- public exports
+│   ├── _version.py                 <- single source of truth for the version
+│   ├── py.typed                    <- PEP 561 marker
+│   ├── exceptions.py               <- domain exceptions
+│   └── selection.py                <- v0.5 module (split into a package
+│                                      only when a second module earns it)
+├── tests/
+│   ├── conftest.py
+│   ├── unit/                       <- no R required
+│   └── validation_against_r/       <- GeoLift parity via rpy2
+├── docs/
+│   ├── methodology.md              <- maps code to Abadie 2021 §5 / GeoLift docs
+│   ├── releasing.md                <- PyPI release runbook
+│   └── geoexp-bootstrap-spec.md    <- the bootstrap spec (relocated here)
+└── .github/workflows/
+    ├── ci.yml                      <- lint, mypy, unit tests, min-deps job
+    ├── validation.yml              <- R + GeoLift parity
+    └── release.yml                 <- tag-triggered PyPI trusted publishing
+```
+
+## Code and testing conventions
+
+Identical to augsynth-py's — type hints everywhere in `src/` with
+`mypy --strict`; NumPy docstrings citing paper + section for known methods;
+no `print()` in library code; no global mutable state; every stochastic
+function takes `rng: np.random.Generator`; `ValueError` for bad input and
+`geoexp.exceptions` subclasses for domain errors; `tests/unit/` runs without
+R (`pytest.importorskip("rpy2")` guards the validation suite); `ruff` for
+lint + format. When in doubt, match augsynth-py.
+
+## Out of scope (inherited wholesale from augsynth-py)
+
+Estimators/inference/power (import them), Bayesian variants, GPU
+acceleration, Rust/C extensions.
+
+## Things to confirm with the maintainer before doing
+
+- Adding a dependency.
+- Changing the public API of anything exported from `__init__.py`.
+- Relaxing a validation tolerance.
+- Starting multi-cell work (project v0.6).

geoexp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 geoexp 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.

geoexp-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.5
+Name: geoexp
+Version: 0.1.0
+Summary: Geo-experiment design on top of augsynth-py: market selection, power-based design ranking, and experiment reporting.
+Project-URL: Repository, https://github.com/mrcsvg/geoexp
+Project-URL: Issues, https://github.com/mrcsvg/geoexp/issues
+Project-URL: Changelog, https://github.com/mrcsvg/geoexp/blob/main/CHANGELOG.md
+Author: geoexp contributors
+License: MIT License
+        
+        Copyright (c) 2026 geoexp 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,geo-experiments,market-selection,marketing-science,synthetic-control
+Classifier: Development Status :: 2 - Pre-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: augsynth-py>=0.5.0
+Requires-Dist: joblib>=1.3
+Requires-Dist: numpy>=1.26
+Requires-Dist: polars>=1.0
+Provides-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: validation
+Requires-Dist: rpy2>=3.5; extra == 'validation'
+Description-Content-Type: text/markdown
+
+# geoexp
+
+Geo-experiment **design** on top of
+[augsynth-py](https://github.com/mrcsvg/augsynth-py): market selection,
+power-based design ranking, and experiment reporting.
+
+The boundary between the two packages is *"given a design"* vs. *"choose a
+design"*:
+
+- **augsynth-py** answers *what can this design detect?* — synthetic-control
+  estimators, conformal inference, and power/MDE for a treated set the caller
+  already fixed.
+- **geoexp** (this package) answers *which design should I run?* — ranking
+  candidate treated sets x durations by what each can detect, with
+  GeoLift-shaped reporting. It consumes augsynth-py through its public API
+  only.
+
+## Quickstart
+
+```python
+import numpy as np
+import polars as pl
+from augsynth_py import AugSynth
+
+from geoexp import enumerate_candidates, rank_designs
+
+# Build candidates, or pass your own explicit sets.
+candidates = enumerate_candidates(
+    panel,
+    unit="location",
+    time="time",
+    outcome="Y",
+    sizes=[1, 2],
+    max_per_size=15,
+)
+
+res = rank_designs(
+    panel,  # long format: unit, time, outcome
+    estimator=AugSynth(lambda_=1.0),  # freeze the penalty for large grids
+    unit="location",
+    time="time",
+    outcome="Y",
+    candidates=candidates,
+    durations=[15, 30],
+    lookback_window=10,
+    permutation_type="iid",
+    rng=np.random.default_rng(7),
+    n_jobs=-1,  # parallel across candidates
+)
+
+res.ranking  # one row per candidate x duration, best first
+res.power("chicago, portland", 15)  # the underlying augsynth_py.PowerResults
+```
+
+`res.ranking` carries `candidate`, `duration`, `n_units`, `mde`, `mde_grid`,
+`power_at_target`, `empirical_size`, `rmspe_pre`, `null_bias`,
+`h1_calibration_error`, `proportion_total_y`, `holdout`, `rank`, and
+`investment` when `cpic` is given.
+
+Two things worth knowing before you read the output:
+
+- **`mde` is interpolated off the power curve**, not a grid point, because the
+  grid value leaves most candidates tied. It is a geoexp construct and is not
+  R GeoLift's `Average_MDE`. `mde_grid` carries the upstream grid point.
+- **Rank order by `mde` is stable within an implementation, not across them.**
+  Small differences near ties carry no information. See
+  [`docs/methodology.md`](docs/methodology.md).
+- **`null_bias` and `h1_calibration_error` are near-duplicates** on
+  well-behaved panels; they separate only when the estimator's bias depends on
+  the effect size.
+
+## Scope
+
+0.1.x is single-cell market selection: candidate enumeration by similarity,
+power-based ranking, and cost per incremental conversion. Budget-constrained
+selection is 0.2.x; multi-cell designs are 0.3.x+.
+
+`enumerate_candidates` is a convenience, not a gate — `rank_designs` takes any
+list of sets, so bring your own candidates if you prefer.
+
+## Validation
+
+Every feature with a reproducible R `GeoLiftMarketSelection` counterpart is
+asserted against it via rpy2 on the `GeoLift_PreTest` fixture. Parity is
+established on the power curve at 240 cells (40 candidates x 6 effect sizes):
+the two implementations agree with each other as well as either agrees with
+itself, with no systematic bias. Features with no reproducible counterpart are
+listed with their reason in
+[`docs/geolift-oracle-characterization.md`](docs/geolift-oracle-characterization.md).
+
+Clean-room: the R `GeoLift` package is a numerical oracle only, driven via
+rpy2. Its source is never read for implementation and never translated.
+
+## Development and AI use
+
+This package was written by its maintainer working with
+[Claude Code](https://claude.com/claude-code), Anthropic's coding agent. That
+is disclosed here because it should shape how you read the rest of this page,
+not as a novelty.
+
+The working rule throughout was that nothing gets asserted that was not
+measured. The parity figures above come from real runs against the R oracle and
+are reproducible from `tests/validation_against_r/`; the noise floor they are
+judged against was measured rather than assumed, after fixed thresholds
+calibrated on a single draw turned out to flake. Where a quantity could not be
+validated — GeoLift's `Average_MDE` and most of its ranking columns — that is
+recorded as a limitation in
+[`docs/geolift-oracle-characterization.md`](docs/geolift-oracle-characterization.md)
+rather than papered over, and a cross-package benchmark that did not work is
+written up there as a negative result instead of being quietly dropped. The
+public API was designed and signed off before implementation, the
+implementation was written test-first, and the clean-room rule stated above
+held throughout: the R GeoLift source was never read.
+
+## Install
+
+```bash
+pip install geoexp
+```
+
+Requires `augsynth-py>=0.5.0` (the release that froze the power-API contract
+this package is written against).
+
+## License
+
+MIT. No association with Meta's GeoLift is implied; the R package is used
+strictly as a numerical validation oracle.

geoexp-0.1.0/README.md

@@ -0,0 +1,127 @@
+# geoexp
+
+Geo-experiment **design** on top of
+[augsynth-py](https://github.com/mrcsvg/augsynth-py): market selection,
+power-based design ranking, and experiment reporting.
+
+The boundary between the two packages is *"given a design"* vs. *"choose a
+design"*:
+
+- **augsynth-py** answers *what can this design detect?* — synthetic-control
+  estimators, conformal inference, and power/MDE for a treated set the caller
+  already fixed.
+- **geoexp** (this package) answers *which design should I run?* — ranking
+  candidate treated sets x durations by what each can detect, with
+  GeoLift-shaped reporting. It consumes augsynth-py through its public API
+  only.
+
+## Quickstart
+
+```python
+import numpy as np
+import polars as pl
+from augsynth_py import AugSynth
+
+from geoexp import enumerate_candidates, rank_designs
+
+# Build candidates, or pass your own explicit sets.
+candidates = enumerate_candidates(
+    panel,
+    unit="location",
+    time="time",
+    outcome="Y",
+    sizes=[1, 2],
+    max_per_size=15,
+)
+
+res = rank_designs(
+    panel,  # long format: unit, time, outcome
+    estimator=AugSynth(lambda_=1.0),  # freeze the penalty for large grids
+    unit="location",
+    time="time",
+    outcome="Y",
+    candidates=candidates,
+    durations=[15, 30],
+    lookback_window=10,
+    permutation_type="iid",
+    rng=np.random.default_rng(7),
+    n_jobs=-1,  # parallel across candidates
+)
+
+res.ranking  # one row per candidate x duration, best first
+res.power("chicago, portland", 15)  # the underlying augsynth_py.PowerResults
+```
+
+`res.ranking` carries `candidate`, `duration`, `n_units`, `mde`, `mde_grid`,
+`power_at_target`, `empirical_size`, `rmspe_pre`, `null_bias`,
+`h1_calibration_error`, `proportion_total_y`, `holdout`, `rank`, and
+`investment` when `cpic` is given.
+
+Two things worth knowing before you read the output:
+
+- **`mde` is interpolated off the power curve**, not a grid point, because the
+  grid value leaves most candidates tied. It is a geoexp construct and is not
+  R GeoLift's `Average_MDE`. `mde_grid` carries the upstream grid point.
+- **Rank order by `mde` is stable within an implementation, not across them.**
+  Small differences near ties carry no information. See
+  [`docs/methodology.md`](docs/methodology.md).
+- **`null_bias` and `h1_calibration_error` are near-duplicates** on
+  well-behaved panels; they separate only when the estimator's bias depends on
+  the effect size.
+
+## Scope
+
+0.1.x is single-cell market selection: candidate enumeration by similarity,
+power-based ranking, and cost per incremental conversion. Budget-constrained
+selection is 0.2.x; multi-cell designs are 0.3.x+.
+
+`enumerate_candidates` is a convenience, not a gate — `rank_designs` takes any
+list of sets, so bring your own candidates if you prefer.
+
+## Validation
+
+Every feature with a reproducible R `GeoLiftMarketSelection` counterpart is
+asserted against it via rpy2 on the `GeoLift_PreTest` fixture. Parity is
+established on the power curve at 240 cells (40 candidates x 6 effect sizes):
+the two implementations agree with each other as well as either agrees with
+itself, with no systematic bias. Features with no reproducible counterpart are
+listed with their reason in
+[`docs/geolift-oracle-characterization.md`](docs/geolift-oracle-characterization.md).
+
+Clean-room: the R `GeoLift` package is a numerical oracle only, driven via
+rpy2. Its source is never read for implementation and never translated.
+
+## Development and AI use
+
+This package was written by its maintainer working with
+[Claude Code](https://claude.com/claude-code), Anthropic's coding agent. That
+is disclosed here because it should shape how you read the rest of this page,
+not as a novelty.
+
+The working rule throughout was that nothing gets asserted that was not
+measured. The parity figures above come from real runs against the R oracle and
+are reproducible from `tests/validation_against_r/`; the noise floor they are
+judged against was measured rather than assumed, after fixed thresholds
+calibrated on a single draw turned out to flake. Where a quantity could not be
+validated — GeoLift's `Average_MDE` and most of its ranking columns — that is
+recorded as a limitation in
+[`docs/geolift-oracle-characterization.md`](docs/geolift-oracle-characterization.md)
+rather than papered over, and a cross-package benchmark that did not work is
+written up there as a negative result instead of being quietly dropped. The
+public API was designed and signed off before implementation, the
+implementation was written test-first, and the clean-room rule stated above
+held throughout: the R GeoLift source was never read.
+
+## Install
+
+```bash
+pip install geoexp
+```
+
+Requires `augsynth-py>=0.5.0` (the release that froze the power-API contract
+this package is written against).
+
+## License
+
+MIT. No association with Meta's GeoLift is implied; the R package is used
+strictly as a numerical validation oracle.