okunfa 0.1.0__py3-none-any.whl

okunfa/__init__.py

@@ -0,0 +1,18 @@
+"""okunfa: synthetic control from scratch, with the inference that makes it
+honest.
+
+*Okunfa* is Yoruba for cause. The method (Abadie, Diamond, Hainmueller
+2010) answers "what would California's smoking have looked like without
+Proposition 99?" by building a weighted combination of untreated states
+that matches California before the law, then reading the difference after
+it. The weights are the transparency: you can see exactly who the
+counterfactual is made of.
+"""
+
+from .core import SyntheticControl, SCFit
+from .inference import (in_space_placebos, in_time_placebo, leave_one_out,
+                        rmspe, rmspe_ratios)
+
+__version__ = "0.1.0"
+__all__ = ["SyntheticControl", "SCFit", "in_space_placebos",
+           "in_time_placebo", "leave_one_out", "rmspe", "rmspe_ratios"]

okunfa/core.py

@@ -0,0 +1,143 @@
+"""The estimator: nested optimization, exactly as the paper frames it.
+
+Inner problem   w*(V) = argmin_{w in simplex} (X1 - X0 w)' V (X1 - X0 w)
+Outer problem   V*    = argmin_V  || Z1 - Z0 w*(V) ||^2  (pre-period MSPE)
+
+X are predictors (covariate averages plus outcome lags), Z the pre-period
+outcome path. V is a diagonal matrix saying how much matching each
+predictor matters; the outer loop chooses it so the resulting weights
+track the treated unit's actual pre-period outcome as closely as
+possible. The inner problem is a small QP solved with SLSQP and an
+analytic gradient; the outer is Nelder-Mead over a softmax
+parameterization of the simplex, so every candidate V is valid by
+construction.
+"""
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from scipy.optimize import minimize
+
+
+def _simplex_qp(H, f, n, x0=None):
+    """min 0.5 w'Hw + f'w  s.t.  w >= 0, sum w = 1."""
+    w0 = np.full(n, 1.0 / n) if x0 is None else x0
+
+    def obj(w):
+        return 0.5 * w @ H @ w + f @ w
+
+    def grad(w):
+        return H @ w + f
+
+    res = minimize(obj, w0, jac=grad, method="SLSQP",
+                   bounds=[(0.0, 1.0)] * n,
+                   constraints=[{"type": "eq", "fun": lambda w: w.sum() - 1,
+                                 "jac": lambda w: np.ones_like(w)}],
+                   options={"maxiter": 500, "ftol": 1e-12})
+    w = np.clip(res.x, 0, None)
+    return w / w.sum()
+
+
+def _inner_weights(X1, X0, v):
+    """w*(V) for diagonal V given as a vector v."""
+    A = X0 * np.sqrt(v)[:, None]
+    b = X1 * np.sqrt(v)
+    H = 2.0 * (A.T @ A)
+    f = -2.0 * (A.T @ b)
+    return _simplex_qp(H, f, X0.shape[1])
+
+
+@dataclass
+class SCFit:
+    weights: np.ndarray          # donor weights, sum to 1
+    v: np.ndarray                # predictor importances, sum to 1
+    donors: list                 # donor names, aligned with weights
+    predictors: list             # predictor names, aligned with v
+    synthetic: np.ndarray        # synthetic outcome path, all periods
+    treated: np.ndarray          # treated outcome path, all periods
+    periods: np.ndarray
+    pre_mask: np.ndarray
+    pre_rmspe: float = field(init=False)
+    post_rmspe: float = field(init=False)
+
+    def __post_init__(self):
+        gap = self.treated - self.synthetic
+        self.pre_rmspe = float(np.sqrt(np.mean(gap[self.pre_mask] ** 2)))
+        self.post_rmspe = float(np.sqrt(np.mean(gap[~self.pre_mask] ** 2)))
+
+    @property
+    def gap(self):
+        return self.treated - self.synthetic
+
+    def nonzero(self, tol=1e-3):
+        """The donors the counterfactual is actually made of."""
+        order = np.argsort(-self.weights)
+        return [(self.donors[i], float(self.weights[i]))
+                for i in order if self.weights[i] > tol]
+
+
+class SyntheticControl:
+    """Fit a synthetic control for one treated unit.
+
+    Parameters
+    ----------
+    X1, X0 : predictor vector (k,) for the treated unit and matrix (k, J)
+        for the donors. Rows are standardized internally so V weighs
+        comparable quantities.
+    Z1, Z0 : pre-period outcome path (T0,) and matrix (T0, J) used by the
+        outer loop.
+    """
+
+    def __init__(self, outer_restarts=4, seed=0):
+        self.outer_restarts = outer_restarts
+        self.seed = seed
+
+    def fit_weights(self, X1, X0, Z1, Z0):
+        k = X1.shape[0]
+        # standardize predictor rows over (treated + donors)
+        allx = np.column_stack([X1, X0])
+        mu, sd = allx.mean(1), allx.std(1)
+        sd[sd == 0] = 1.0
+        X1s = (X1 - mu) / sd
+        X0s = (X0 - mu[:, None]) / sd[:, None]
+
+        def outer_loss(theta):
+            v = np.exp(theta - theta.max())
+            v = v / v.sum()
+            w = _inner_weights(X1s, X0s, v)
+            return float(np.mean((Z1 - Z0 @ w) ** 2))
+
+        rng = np.random.default_rng(self.seed)
+        best = None
+        starts = [np.zeros(k)] + [rng.normal(0, 1, k)
+                                  for _ in range(self.outer_restarts - 1)]
+        for th0 in starts:
+            res = minimize(outer_loss, th0, method="Nelder-Mead",
+                           options={"maxiter": 2000, "xatol": 1e-6,
+                                    "fatol": 1e-10})
+            if best is None or res.fun < best.fun:
+                best = res
+        v = np.exp(best.x - best.x.max())
+        v = v / v.sum()
+        w = _inner_weights(X1s, X0s, v)
+        return w, v
+
+    def fit(self, *, outcome, periods, treated, donors, pre_mask,
+            predictors):
+        """outcome: dict name -> path over periods; predictors: dict
+        name -> dict unit -> scalar."""
+        periods = np.asarray(periods)
+        pre_mask = np.asarray(pre_mask, dtype=bool)
+        Z1 = np.asarray(outcome[treated], float)[pre_mask]
+        Z0 = np.column_stack([np.asarray(outcome[d], float)[pre_mask]
+                              for d in donors])
+        pnames = list(predictors)
+        X1 = np.array([predictors[p][treated] for p in pnames], float)
+        X0 = np.array([[predictors[p][d] for d in donors]
+                       for p in pnames], float)
+        w, v = self.fit_weights(X1, X0, Z1, Z0)
+        synth = np.column_stack([outcome[d] for d in donors]) @ w
+        return SCFit(weights=w, v=v, donors=list(donors),
+                     predictors=pnames, synthetic=synth,
+                     treated=np.asarray(outcome[treated], float),
+                     periods=periods, pre_mask=pre_mask)

okunfa/datasets.py

@@ -0,0 +1,98 @@
+"""The Proposition 99 panel: cigarette sales in 39 states, 1970-2000.
+
+The canonical dataset of Abadie, Diamond and Hainmueller (2010),
+originally from Orzechowski and Walker's *Tax Burden on Tobacco*
+(public government data), as distributed with the R Synth package and
+mirrored in Facure's *Causal Inference for the Brave and True*. State
+codes are the 39 donor-pool states in alphabetical order; the paper drops
+states with their own large tobacco programs and DC.
+"""
+
+import csv
+import io
+import urllib.request
+from collections import defaultdict
+from pathlib import Path
+
+import numpy as np
+
+URL = ("https://raw.githubusercontent.com/matheusfacure/"
+       "python-causality-handbook/master/"
+       "causal-inference-for-the-brave-and-true/data/smoking.csv")
+
+STATES = [
+    "Alabama", "Arkansas", "California", "Colorado", "Connecticut",
+    "Delaware", "Georgia", "Idaho", "Illinois", "Indiana", "Iowa",
+    "Kansas", "Kentucky", "Louisiana", "Maine", "Minnesota",
+    "Mississippi", "Missouri", "Montana", "Nebraska", "Nevada",
+    "New Hampshire", "New Mexico", "North Carolina", "North Dakota",
+    "Ohio", "Oklahoma", "Pennsylvania", "Rhode Island", "South Carolina",
+    "South Dakota", "Tennessee", "Texas", "Utah", "Vermont", "Virginia",
+    "West Virginia", "Wisconsin", "Wyoming",
+]
+
+TREATMENT_YEAR = 1989  # Prop 99 took effect January 1989
+
+
+def _cache_path():
+    d = Path.home() / ".cache" / "okunfa"
+    d.mkdir(parents=True, exist_ok=True)
+    return d / "smoking.csv"
+
+
+def load_prop99(path=None):
+    """Return the panel as {column: {state: {year: value}}} plus years."""
+    p = Path(path) if path else _cache_path()
+    if not p.exists():
+        with urllib.request.urlopen(URL, timeout=60) as r:
+            p.write_bytes(r.read())
+    rows = list(csv.DictReader(io.StringIO(p.read_text())))
+
+    cols = ["cigsale", "lnincome", "beer", "age15to24", "retprice"]
+    panel = {c: defaultdict(dict) for c in cols}
+    years = set()
+    for r in rows:
+        st = STATES[int(r["state"]) - 1]
+        yr = int(r["year"])
+        years.add(yr)
+        for c in cols:
+            v = r[c]
+            if v not in ("", "NA"):
+                panel[c][st][yr] = float(v)
+    return panel, np.array(sorted(years))
+
+
+def adh_design(panel, years):
+    """The exact design of ADH 2010, Table 1.
+
+    Predictors: 1980-88 averages of ln income, retail price, share aged
+    15-24; 1984-88 average beer consumption; and cigarette sales in 1975,
+    1980 and 1988 as outcome lags. Pre-period for the outer loop:
+    1970-1988.
+    """
+    treated = "California"
+    donors = [s for s in STATES if s != treated]
+    outcome = {s: np.array([panel["cigsale"][s][y] for y in years])
+               for s in STATES}
+    pre_mask = years <= 1988
+
+    def avg(col, lo, hi):
+        return {s: float(np.mean([panel[col][s][y]
+                                  for y in range(lo, hi + 1)
+                                  if y in panel[col][s]]))
+                for s in STATES}
+
+    predictors = {
+        "ln income": avg("lnincome", 1980, 1988),
+        "retail price": avg("retprice", 1980, 1988),
+        "share aged 15-24": avg("age15to24", 1980, 1988),
+        "beer consumption": avg("beer", 1984, 1988),
+        "cigarette sales 1975": {s: panel["cigsale"][s][1975]
+                                 for s in STATES},
+        "cigarette sales 1980": {s: panel["cigsale"][s][1980]
+                                 for s in STATES},
+        "cigarette sales 1988": {s: panel["cigsale"][s][1988]
+                                 for s in STATES},
+    }
+    return dict(outcome=outcome, periods=years, treated=treated,
+                donors=donors, pre_mask=pre_mask, predictors=predictors)

okunfa/inference.py

@@ -0,0 +1,80 @@
+"""The inference: synthetic control without placebos is just a curve.
+
+The method's own authors built its test: run the identical procedure on
+every untreated unit (in-space placebos). If the treated unit's post/pre
+RMSPE ratio towers over the placebo distribution, the effect is unlikely
+to be luck; the permutation p-value is the rank of that ratio. A second
+check runs the procedure at a fake earlier treatment date (in-time
+placebo), where a real design should find nothing.
+"""
+
+import numpy as np
+
+
+def rmspe(gap, mask):
+    return float(np.sqrt(np.mean(np.asarray(gap)[mask] ** 2)))
+
+
+def rmspe_ratios(fits):
+    """post/pre RMSPE ratio per fit dict {unit: SCFit}."""
+    return {u: f.post_rmspe / f.pre_rmspe for u, f in fits.items()}
+
+
+def in_space_placebos(sc, *, outcome, periods, treated, donors, pre_mask,
+                      predictors, verbose=False):
+    """Run the identical estimator with each donor cast as pseudo-treated.
+
+    Returns {unit: SCFit} including the genuinely treated unit.
+    """
+    fits = {}
+    units = [treated] + list(donors)
+    for u in units:
+        # a placebo's donor pool is the other CONTROL units only: the
+        # genuinely treated unit is post-treatment data and would
+        # contaminate every placebo counterfactual
+        pool = [d for d in donors if d != u]
+        fits[u] = sc.fit(outcome=outcome, periods=periods, treated=u,
+                         donors=pool, pre_mask=pre_mask,
+                         predictors=_reindex(predictors, units))
+        if verbose:
+            print(f"  placebo {u}: pre {fits[u].pre_rmspe:.2f} "
+                  f"post {fits[u].post_rmspe:.2f}")
+    return fits
+
+
+def _reindex(predictors, units):
+    return {p: {u: predictors[p][u] for u in units if u in predictors[p]}
+            for p in predictors}
+
+
+def permutation_pvalue(fits, treated):
+    """P(ratio >= treated's) under random permutation: rank / N."""
+    ratios = rmspe_ratios(fits)
+    r_t = ratios[treated]
+    rank = sum(1 for v in ratios.values() if v >= r_t)
+    return rank / len(ratios), ratios
+
+
+def leave_one_out(sc, fit, *, outcome, periods, treated, pre_mask,
+                  predictors, tol=1e-3):
+    """Refit dropping each nonzero-weight donor in turn: does the story
+    survive losing any single leg of the counterfactual?"""
+    out = {}
+    keep = [d for d, _ in fit.nonzero(tol)]
+    for drop in keep:
+        pool = [d for d in fit.donors if d != drop]
+        out[drop] = sc.fit(outcome=outcome, periods=periods,
+                           treated=treated, donors=pool, pre_mask=pre_mask,
+                           predictors=predictors)
+    return out
+
+
+def in_time_placebo(sc, *, outcome, periods, treated, donors,
+                    true_pre_mask, fake_treatment_period, predictors):
+    """Pretend treatment happened earlier; a sound design finds ~nothing
+    in the window that is actually untreated."""
+    periods = np.asarray(periods)
+    fake_pre = periods < fake_treatment_period
+    fake_pre &= true_pre_mask  # never let real post-treatment data in
+    return sc.fit(outcome=outcome, periods=periods, treated=treated,
+                  donors=donors, pre_mask=fake_pre, predictors=predictors)

okunfa-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: okunfa
+Version: 0.1.0
+Summary: Synthetic control from scratch: the ADH estimator with the placebo inference that makes it honest
+Author-email: Kenny Obidele <obidelek19@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Kenny0bi/okunfa
+Project-URL: Issues, https://github.com/Kenny0bi/okunfa/issues
+Keywords: causal-inference,synthetic-control,econometrics,policy-evaluation,placebo-tests
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+
+# okunfa
+
+Synthetic control from scratch, verified against the paper that defined
+the method, shipped as a library.
+
+```
+pip install okunfa
+```
+
+*Okunfa* is Yoruba for cause. The question causal inference keeps asking
+is "compared to what?", and the synthetic control method (Abadie, Diamond,
+Hainmueller 2010) gives the most transparent answer in the toolbox: build
+the counterfactual as a weighted average of untreated units, weights
+non-negative and summing to one, chosen to match the treated unit before
+the intervention. The counterfactual comes with an ingredients list you
+can argue with.
+
+I implemented the full estimator on numpy and scipy (no causal libraries
+anywhere), then pointed it at the method's founding result: California's
+Proposition 99 tobacco program.
+
+## The reproduction
+
+![The ghost](assets/ghost.svg)
+
+ADH 2010, Table 2, says synthetic California is Utah .334, Nevada .234,
+Montana .199, Colorado .164, Connecticut .069. This implementation, run
+on the same public panel with the same predictors, finds:
+
+| state | published | okunfa |
+|---|---|---|
+| Utah | 0.334 | 0.335 |
+| Nevada | 0.234 | 0.236 |
+| Montana | 0.199 | 0.201 |
+| Colorado | 0.164 | 0.160 |
+| Connecticut | 0.069 | 0.068 |
+
+All five within 0.005, every other state at zero, and the headline
+effect lands where the paper put it: California's cigarette sales about
+26 packs per capita below its ghost by 2000. A test pins each published
+weight to within 0.01, so the reproduction cannot silently rot.
+
+![The animation](assets/recipe.gif)
+
+(Source: [assets/manim_recipe.py](assets/manim_recipe.py), video in
+[assets/recipe.mp4](assets/recipe.mp4).)
+
+## The inference is the honest part
+
+A synthetic control without placebos is just a curve that goes down.
+The method's own significance test is to run the identical procedure on
+every state that never passed the law:
+
+![The placebo storm](assets/storm.svg)
+
+![One in thirty-nine](assets/rank.svg)
+
+California's post/pre RMSPE ratio is the most extreme of all 39 states,
+a permutation p-value of 1/39 = 0.026, matching the paper's inference
+exactly. Two more checks that the story is structural, not lucky:
+
+![Stress tests](assets/stress.svg)
+
+Leave-one-out refits drop each ingredient state in turn (the gap
+survives losing any single leg), and an in-time placebo pretends the law
+passed in 1980 using only pre-1980 information (the design finds almost
+nothing where nothing happened).
+
+## The estimator
+
+The paper's nested optimization, implemented directly:
+
+- **Inner problem**: given predictor importances V, the weights solve a
+  small quadratic program on the simplex, min (X1 - X0 w)' V (X1 - X0 w),
+  by SLSQP with an analytic gradient.
+- **Outer problem**: V itself is chosen to minimize pre-period outcome
+  MSPE, by Nelder-Mead over a softmax parameterization, so every
+  candidate V is a valid distribution by construction, with multiple
+  restarts because the surface is not convex.
+
+The chosen V is itself interpretable, and slightly deflating: the data
+puts 87% of the matching weight on retail price and most of the rest on
+the 1975 sales lag. The covariates everyone lists (income, beer, age
+structure) barely matter once the outcome lags are in, which is a known
+property of the method worth seeing with your own eyes.
+
+## Using it
+
+```python
+from okunfa import SyntheticControl, in_space_placebos, permutation_pvalue
+from okunfa.datasets import load_prop99, adh_design
+
+panel, years = load_prop99()      # fetches the public panel on demand
+design = adh_design(panel, years)
+
+sc = SyntheticControl()
+fit = sc.fit(**design)
+print(fit.nonzero())              # [('Utah', 0.335), ('Nevada', 0.236), ...]
+print(fit.gap[-1])                # about -26 packs in 2000
+
+fits = in_space_placebos(sc, **design)
+p, ratios = permutation_pvalue(fits, "California")
+print(p)                          # 0.026
+```
+
+The API takes plain dicts and numpy arrays (unit -> outcome path,
+predictor -> unit -> value), so it works on any panel, not just this one.
+
+## Honest limits
+
+- Permutation inference with 39 units cannot say anything smaller than
+  p = 1/39. That is a property of the design, not a bug, and it is why
+  the paper reports exactly this number.
+- The outer optimization is non-convex; different software finds slightly
+  different V (mine concentrates it more than the paper's table shows)
+  while landing on the same weights and the same gap. The reproduction
+  target is the weights and the effect, which are the identified objects.
+- Synthetic control needs a long pre-period, a treated unit inside the
+  donor convex hull, and no spillovers onto donors. None of that is
+  checked for you; the placebo and leave-one-out tools exist so you
+  check it.
+- One fit takes about three minutes on my 2014 CPU (the placebo sweep is
+  39 of them). SLSQP in the inner loop is the cost of writing it plainly.
+
+## Reproduce it
+
+```bash
+python -m venv .venv && .venv/bin/pip install numpy scipy pytest
+bash data/get_data.sh                       # or let the loader fetch it
+
+.venv/bin/python -m pytest tests/ -q        # 6 contracts
+.venv/bin/python benchmarks/repro_prop99.py # all stages, resumable
+.venv/bin/python assets/make_visuals.py     # the four figures
+```
+
+## Layout
+
+- [okunfa/core.py](okunfa/core.py) the nested estimator: simplex QP
+  inside, Nelder-Mead over V outside
+- [okunfa/inference.py](okunfa/inference.py) in-space placebos,
+  permutation p-values, leave-one-out, in-time placebo
+- [okunfa/datasets.py](okunfa/datasets.py) the Prop 99 panel and the
+  exact ADH predictor design
+- [benchmarks/repro_prop99.py](benchmarks/repro_prop99.py) the
+  reproduction, staged and resumable, everything into repro.json
+
+## Papers
+
+- Abadie, Diamond, Hainmueller (2010), *Synthetic Control Methods for
+  Comparative Case Studies: Estimating the Effect of California's
+  Tobacco Control Program*, JASA. The method and the target result.
+- Abadie & Gardeazabal (2003), *The Economic Costs of Conflict*. Where
+  the idea started.
+- Abadie (2021), *Using Synthetic Controls: Feasibility, Data
+  Requirements, and Methodological Aspects*, JEL. The honest-limits
+  survey.

okunfa-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+okunfa/__init__.py,sha256=kiQZ_p683h85zbMArLu5S_lPchOODUOd-dKNNcpgucc,790
+okunfa/core.py,sha256=aFeQMLDQoCHK1ncN5-q2q-jwWHavrgtUvVSJYd7jWSQ,5428
+okunfa/datasets.py,sha256=1VHayQGD_fgdYUaX9JwBrC7XzEovEPH0_vhF3TcGzJg,3701
+okunfa/inference.py,sha256=5NoDoJugpKuRVvfdjIfm1LjZVnVc7KaSORy0rxVSV58,3195
+okunfa-0.1.0.dist-info/METADATA,sha256=_gW0_YJrdruXyvRRSxPU2ZddYePIUO8Q42-XmwV2gp4,6936
+okunfa-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+okunfa-0.1.0.dist-info/top_level.txt,sha256=KN06BhTyhQZrFO3S5R4F1KtOVTK5-HoR4hPp9PGV6K0,7
+okunfa-0.1.0.dist-info/RECORD,,

okunfa-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

okunfa-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+okunfa