upliftlab 0.26.1__py3-none-any.whl

upliftlab/__init__.py

@@ -0,0 +1,5 @@
+"""UpliftLab engine: an explore/exploit targeting loop with pluggable algorithms.
+
+The same package runs in the browser (Pyodide) and natively (`python -m upliftlab serve`).
+"""
+__version__ = '0.26.1'

upliftlab/__main__.py

@@ -0,0 +1,119 @@
+import argparse
+import json
+import sys
+from pathlib import Path
+
+parser = argparse.ArgumentParser(prog='upliftlab', description='upliftlab local edition: the same UI and engine as uplift-lab.vercel.app, on your own Python. Run it with no command to open the UI.')
+sub = parser.add_subparsers(dest='command', metavar='{serve,run,check}')
+web = sub.add_parser('serve', help='open the web UI on localhost and run the engine natively (the default)')
+web.add_argument('--host', default='127.0.0.1')
+web.add_argument('--port', type=int, default=4180)
+web.add_argument('--web', help='folder with the UI (defaults to web/ in a source checkout, else the UI inside the package)')
+web.add_argument('--no-browser', action='store_true', help='do not open the browser')
+check = sub.add_parser('check', help='list the libraries an algorithm file uses, then fit it once on synthetic data')
+check.add_argument('file', metavar='FILE.py')
+run = sub.add_parser('run', help='run a head-to-head comparison without the UI and write the result as JSON')
+run.add_argument('--data', default='public/criteo', help='public/criteo (the bundled 200k-row sample) | synthetic/base | path to a CSV')
+run.add_argument('--algorithms', default='all', help='comma-separated built-in ids, or "all"')
+run.add_argument('--algorithm', action='append', default=[], metavar='FILE.py', help='add your own algorithm file (repeatable)')
+run.add_argument('--cycles', type=int, default=8)
+run.add_argument('--explore', type=float, default=.2)
+run.add_argument('--target', type=float, default=.4)
+run.add_argument('--seed', type=int, default=42)
+run.add_argument('--mode', choices=['quantile', 'budget', 'knapsack', 'roi', 'validation'], default='budget', help='budget (default): by score until the budget runs out. quantile: the top q%%. knapsack: value - price * cost > 0, priced to the budget. roi: by value / cost while the expected efficiency meets --efficiency. validation: up to the share where uplift peaked on validation rows')
+run.add_argument('--budget', type=float, default=.4, help='budget as a share of the expected cost of treating every candidate')
+run.add_argument('--efficiency', type=float, default=.2, help='with --mode roi: required efficiency gain over random selection')
+run.add_argument('--base-learner', choices=['ridge', 'tree'], default='ridge', help='base model of the built-in algorithms')
+run.add_argument('--out', help='write the result JSON here (open it in the web UI under 실행 기록 → 결과 JSON 열기)')
+
+
+def main(argv=None):
+    args = parser.parse_args(argv)
+    if args.command is None:  # plain `upliftlab` opens the UI
+        args = parser.parse_args(['serve'])
+    if args.command == 'serve':
+        from .server import serve
+        serve(args.host, args.port, args.web, open_browser=not args.no_browser)
+    elif args.command == 'check':
+        from . import bridge
+        from .server import detect_devices
+        devices = detect_devices()
+        bridge.state.update(runtime='local', device=devices[0], devices=devices)
+        path = Path(args.file)
+        code = path.read_text(encoding='utf-8')
+        out = bridge.check(code, path.stem)
+        print(f"{path.name} · {out.get('name') or path.stem}")
+        shown = {'ok': lambda l: f"{l['package']} {l['version'] or ''}".strip(), 'missing': lambda l: f"{l['package']} (missing · pip install {l['package']})"}
+        print('libraries: ' + (' · '.join(shown.get(l['status'], shown['missing'])(l) for l in out['libraries']) or 'standard library only'))
+        if out['ok']:
+            out = bridge.try_algorithm(code, path.stem, out.get('name'))
+        if not out['ok']:
+            sys.exit(f"{path}:{out.get('line') or '?'}: {out['error']}")
+        print(f"quick check: ok · test AUCC truth {out['auccTruth']:.3f} · observed {out['aucc']:.3f} · fit {out['ms']:.0f} ms on {out['split']['train']:,} rows · device {devices[0]}")
+    else:
+        from . import bridge, datasets
+        from .server import detect_devices
+        devices = detect_devices()
+        bridge.state.update(runtime='local', device=devices[0], devices=devices)
+        builtins = {a['id']: a for a in bridge.builtins()}
+        ids = list(builtins) if args.algorithms == 'all' else [a for a in args.algorithms.split(',') if a]
+        unknown = [a for a in ids if a not in builtins]
+        if unknown:
+            sys.exit(f'unknown algorithm: {", ".join(unknown)} (choose from {", ".join(builtins)})')
+        algorithms = [{'id': a, 'name': builtins[a]['name'], 'code': builtins[a]['code']} for a in ids]
+        for file in args.algorithm:
+            code = Path(file).read_text(encoding='utf-8')
+            check = bridge.check(code, Path(file).stem)
+            if not check['ok']:
+                sys.exit(f'{file}:{check.get("line") or "?"}: {check["error"]}')
+            algorithms.append({'id': 'file-' + Path(file).stem, 'name': check.get('name') or Path(file).stem, 'code': code})
+        dataset = args.data
+        if dataset.startswith('public/'):
+            bridge.fetch_dataset(dataset)
+        elif not dataset.startswith('synthetic/'):
+            path = Path(dataset)
+            dataset = 'upload/' + path.name
+            bridge.add_dataset(dataset, path.read_text(encoding='utf-8'), path.name)
+        print(f'{dataset} · {len(algorithms)} algorithms · {args.cycles} cycles · device {devices[0]}', file=sys.stderr)
+        bridge.set_reporter(lambda m: (lambda d: d.get('phase') == 'done' and print(f"  c{d['cycle']} {d['arm']} done", file=sys.stderr))(json.loads(m)))
+        result = bridge.run_all(dataset, algorithms, args.cycles, args.explore, args.target, args.seed, args.mode, args.budget, args.base_learner, args.efficiency)
+        by = result['summary']['by']
+        measure = ('incremental' if by.lower().endswith('incr') else 'gain') + (' (truth)' if by.startswith('truth') else ' (observed)')
+        volume = by.lower().endswith('incr')  # ranked by incremental outcome: the band is the gap to first place, as on the screen
+        print(f"\n{'rank':<5}{'algorithm':<26}{measure:>22}{'vs 1st, 95% CI' if volume else 'observed 95% CI':>30}{'AUCC':>8}{'Qini':>8}{'fit ms':>9}")
+        for s in sorted(result['summary']['arms'], key=lambda s: s['rank']):
+            g, ci, auc, ms = s[by], s['ci'], s['aucc'], s['trainMs']
+            gain = '—' if g is None else f'{g:,.0f}' if volume else f'{g:+.1%}'
+            q = '—' if s['qini'] is None else f"{s['qini']:.3f}"
+            gap = s.get('vsLeader') or {}
+            if volume:
+                band = '1st' if s['rank'] == 1 else '—' if gap.get('diff') is None or gap.get('ci', [None])[0] is None else f"{gap['diff']:+,.0f} [{gap['ci'][0]:+,.0f}, {gap['ci'][1]:+,.0f}]"
+            else:
+                band = '—' if ci[0] is None else f'[{ci[0]:+.1%}, {ci[1]:+.1%}]'
+            auc = '—' if auc is None else f'{auc:.3f}'
+            ms = '—' if ms is None else f'{ms:.0f}'
+            print(f"{s['rank']:<5}{s['name'][:25]:<26}{gain:>22}{band:>30}{auc:>8}{q:>8}{ms:>9}")
+        print('\n' + conclusion(result, args.mode))
+        if args.out:
+            Path(args.out).write_text(json.dumps({'format': 'upliftlab.run/1', **result}, ensure_ascii=False))
+            print(f'\nwrote {args.out}', file=sys.stderr)
+
+
+def conclusion(result, mode):
+    """One line under the table: who won, by how much over Random, on which basis."""
+    arms, by = result['summary']['arms'], result['summary']['by']
+    lead = min(arms, key=lambda s: s['rank'])
+    random = next((s for s in arms if s['arm'] == 'random_baseline' and s is not lead), None)
+    basis = 'true effect, known for synthetic data' if by.startswith('truth') else 'observed: treated minus control'
+    if lead.get(by) is None:
+        return f"{lead['name']} ranks first ({basis})."
+    if by.lower().endswith('incr'):
+        line = f"{lead['name']} ranks first with {lead[by]:,.0f} incremental outcome"
+        if random and random.get(by):
+            line += f", {lead[by] - random[by]:+,.0f} ({lead[by] / random[by] - 1:+.0%}) over Random"
+        return line + (' for the same budget' if mode in ('budget', 'knapsack') else '') + f' ({basis}).'
+    return f"{lead['name']} ranks first with {lead[by]:+.1%} cost efficiency over random selection ({basis})."
+
+
+if __name__ == '__main__':
+    main()

upliftlab/algorithms/__init__.py

@@ -0,0 +1,6 @@
+"""Built-in algorithms. Each file is a self-contained `class Model` that imports common libraries, never upliftlab.
+
+The files here use EconML (PyWhy) and run in the local edition. The browser has no EconML, so the web runs the files in
+lite/: the same methods written with scikit-learn only. Random has no lite version because it needs neither.
+The screen shows and runs these exact files."""
+ORDER = ['random_baseline', 'x_learner', 't_learner', 'r_learner', 'dml', 'duality_r_learner']

upliftlab/algorithms/dml.py

@@ -0,0 +1,35 @@
+"""Y와 T의 잔차를 cross-fitting으로 구하고, 그 관계로 CATE를 추정해요(Double Machine Learning). 비용은 보지 않아요.
+
+EconML의 LinearDML이에요. ỹ = y − m̂(x), t̃ = t − ê(x)를 3-fold cross-fitting으로 구하고 τ̂(x) = θ₀ + θ'x를 ỹ ≈ t̃·τ(x)로 맞춰요.
+R-Learner와 달리 마지막 단계가 선형이라 해석하기 쉽고, 처치가 공변량에 따라 달라지는 로그에서도 ê(x)로 보정해요.
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingClassifier, HistGradientBoostingRegressor
+from sklearn.linear_model import LogisticRegression, Ridge
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+from econml.dml import LinearDML
+
+NAME = 'DML'
+
+
+def regressor(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+def classifier(kind):
+    if kind == 'tree':
+        return HistGradientBoostingClassifier(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), LogisticRegression(max_iter=1000))
+
+
+class Model:
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        self.est = LinearDML(model_y=regressor(kind), model_t=classifier(kind), discrete_treatment=True, cv=3, random_state=context.model_seed)
+        self.est.fit(train.y, train.t, X=train.X)
+
+    def predict(self, X):
+        return np.asarray(self.est.const_marginal_effect(X)).reshape(len(X), -1)

upliftlab/algorithms/duality_r_learner.py

@@ -0,0 +1,86 @@
+"""성과와 비용의 CATE를 R-Learner로 학습하고 τ̂ʳ − λ·τ̂ᶜ 순으로 정렬해요. λ는 validation AUCC가 가장 높은 값으로 정해요.
+
+τ̂ʳ, τ̂ᶜ는 y / σ_y, cost / σ_c의 CATE이고, EconML의 NonParamDML(R-Learner)로 학습해요.
+σ_y, σ_c는 train의 표준편차예요. 정규화하므로 성과와 비용의 단위가 바뀌어도 순위가 같아요.
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingClassifier, HistGradientBoostingRegressor
+from sklearn.linear_model import LogisticRegression, Ridge
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+from econml.dml import NonParamDML
+
+NAME = 'Duality R-Learner'
+LAMBDAS = [0, 0.05, 0.1, 0.2, 0.4, 0.8, 1.6]  # 정규화한 성과와 비용 사이의 가중치
+
+
+def regressor(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+def classifier(kind):
+    if kind == 'tree':
+        return HistGradientBoostingClassifier(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), LogisticRegression(max_iter=1000))
+
+
+def final(kind):
+    """마지막 단계 회귀. EconML이 sample_weight를 넘기므로 파이프라인이 아닌 모델을 써요."""
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return Ridge(alpha=1.0)
+
+
+def r_learner(X, t, y, seed, kind):
+    est = NonParamDML(model_y=regressor(kind), model_t=classifier(kind), model_final=final(kind), discrete_treatment=True, cv=2, random_state=seed)
+    return est.fit(y, t, X=X)
+
+
+def aucc(score, t, y, cost, points=20):
+    """점수 순으로 상위 S를 골랐을 때 (증분 비용, 증분 성과) 곡선 아래 넓이를 0–1로 맞춘 값. 무작위 순서 ≈ 0.5."""
+    order = np.argsort(-score, kind='stable')
+    cut = np.round(np.arange(1, points + 1) * len(order) / points).astype(int) - 1
+    T = (t[order] > 0).astype(float)
+    nT, nC = np.cumsum(T)[cut], np.cumsum(1 - T)[cut]
+    ok = (nT > 0) & (nC > 0)
+
+    def lift(v):
+        with np.errstate(divide='ignore', invalid='ignore'):
+            return np.where(ok, nT * (np.cumsum(v[order] * T)[cut] / nT - np.cumsum(v[order] * (1 - T))[cut] / nC), 0.)
+    gain, spend = np.r_[0., lift(y)], np.r_[0., lift(cost)]
+    if gain.max() <= 0 or spend.max() <= 0:
+        return None
+    x, h = spend / spend.max(), gain / gain.max()
+    return float(np.sum(np.diff(x) * (h[1:] + h[:-1]) / 2))
+
+
+class Model:
+    score_is_effect = False  # 점수에 비용이 이미 들어 있어서 효과로 읽지 않아요. Knapsack과 효율 제약 선정에서 이 순서를 그대로 써요.
+
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        y, cost = train.y / (train.y.std() or 1), train.cost / (train.cost.std() or 1)
+        self.arms = []
+        for arm in range(1, train.treatments + 1):
+            rows = (train.t == arm) | (train.t == 0)
+            t = (train.t[rows] == arm).astype(int)
+            self.arms.append((r_learner(train.X[rows], t, y[rows], context.model_seed, kind), r_learner(train.X[rows], t, cost[rows], context.model_seed, kind)))
+        best = None
+        for i, lam in enumerate(LAMBDAS):
+            values = []
+            for arm, (gain, spend) in enumerate(self.arms, 1):
+                rows = (validation.t == arm) | (validation.t == 0)
+                X = validation.X[rows]
+                score = np.ravel(gain.const_marginal_effect(X)) - lam * np.ravel(spend.const_marginal_effect(X))
+                values.append(aucc(score, validation.t[rows], validation.y[rows], validation.cost[rows]))
+            values = [v for v in values if v is not None]
+            val = float(np.mean(values)) if values else None
+            context.report(step=i + 1, total=len(LAMBDAS), lam=lam, val=val if val is not None else 0)
+            if best is None or (val is not None and (best[0] is None or val > best[0])):
+                best = (val, lam)
+        self.lam = best[1]
+
+    def predict(self, X):
+        return np.column_stack([np.ravel(gain.const_marginal_effect(X)) - self.lam * np.ravel(spend.const_marginal_effect(X)) for gain, spend in self.arms])

upliftlab/algorithms/lite/dml.py

@@ -0,0 +1,53 @@
+"""Y와 T의 잔차를 cross-fitting으로 구하고, 그 관계로 CATE를 추정해요(Double Machine Learning). 비용은 보지 않아요.
+
+경량판: 브라우저에는 EconML이 없어서 웹에서는 같은 방법을 scikit-learn으로 직접 구현한 이 파일을 실행해요.
+로컬(upliftlab)에서는 EconML로 쓴 upliftlab/algorithms/dml.py를 실행해요.
+
+ỹ = y − m̂(x)        t̃ = t − ê(x)        τ̂(x) = θ₀ + θ'x        θ = argmin Σ (ỹ − t̃·τ(x))²
+m̂와 ê는 3-fold cross-fitting으로 구해요. 모델은 context.base_learner에 따라 Ridge·로지스틱 회귀 또는 Gradient Boosting이에요(scikit-learn).
+R-Learner와 달리 propensity ê(x)도 추정해서, 처치가 공변량에 따라 달라지는 로그에서도 쓸 수 있어요.
+무작위 배정 데이터에서는 ê(x)가 상수에 가까워 R-Learner와 비슷한 결과가 나와요.
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingClassifier, HistGradientBoostingRegressor
+from sklearn.linear_model import LogisticRegression, Ridge
+from sklearn.model_selection import KFold, cross_val_predict
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+
+NAME = 'DML'
+FOLDS = 3
+
+
+def outcome_model(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+def treatment_model(kind):
+    if kind == 'tree':
+        return HistGradientBoostingClassifier(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), LogisticRegression(max_iter=1000))
+
+
+def design(scaler, X):
+    return np.column_stack([np.ones(len(X)), scaler.transform(X)])
+
+
+class Model:
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        self.scaler = StandardScaler().fit(train.X)
+        self.finals = []
+        for arm in range(1, train.treatments + 1):
+            rows = (train.t == arm) | (train.t == 0)
+            X, y, t = train.X[rows], train.y[rows], (train.t[rows] == arm).astype(int)
+            folds = KFold(FOLDS, shuffle=True, random_state=context.model_seed)
+            y_res = y - cross_val_predict(outcome_model(kind), X, y, cv=folds)
+            t_res = t - np.clip(cross_val_predict(treatment_model(kind), X, t, cv=folds, method='predict_proba')[:, 1], .01, .99)
+            self.finals.append(Ridge(alpha=1.0, fit_intercept=False).fit(design(self.scaler, X) * t_res[:, None], y_res))
+
+    def predict(self, X):
+        Z = design(self.scaler, X)
+        return np.column_stack([final.predict(Z) for final in self.finals])

upliftlab/algorithms/lite/duality_r_learner.py

@@ -0,0 +1,78 @@
+"""성과와 비용의 CATE를 R-Learner로 학습하고 τ̂ʳ − λ·τ̂ᶜ 순으로 정렬해요. λ는 validation AUCC가 가장 높은 값으로 정해요.
+
+경량판: 브라우저에는 EconML이 없어서 웹에서는 같은 방법을 scikit-learn으로 직접 구현한 이 파일을 실행해요.
+로컬(upliftlab)에서는 EconML로 쓴 upliftlab/algorithms/duality_r_learner.py를 실행해요.
+
+score = τ̂ʳ(x) − λ·τ̂ᶜ(x)        τ̂ʳ, τ̂ᶜ는 y / σ_y, cost / σ_c의 CATE예요.
+σ_y, σ_c는 train의 표준편차예요. 정규화하므로 성과와 비용의 단위가 바뀌어도 순위가 같아요.
+회귀 모델은 context.base_learner에 따라 Ridge 또는 Gradient Boosting이에요(scikit-learn).
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingRegressor
+from sklearn.linear_model import Ridge
+from sklearn.model_selection import KFold, cross_val_predict
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+
+NAME = 'Duality R-Learner'
+LAMBDAS = [0, 0.05, 0.1, 0.2, 0.4, 0.8, 1.6]  # 정규화한 성과와 비용 사이의 가중치
+
+
+def base_model(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+def r_learner(X, t, y, propensity, seed, kind):
+    m = cross_val_predict(base_model(kind), X, y, cv=KFold(2, shuffle=True, random_state=seed))
+    w = t - propensity
+    weight = {'sample_weight': w ** 2} if kind == 'tree' else {'ridge__sample_weight': w ** 2}
+    return base_model(kind).fit(X, (y - m) / w, **weight)
+
+
+def aucc(score, t, y, cost, points=20):
+    """점수 순으로 상위 S를 골랐을 때 (증분 비용, 증분 성과) 곡선 아래 넓이를 0–1로 맞춘 값. 무작위 순서 ≈ 0.5."""
+    order = np.argsort(-score, kind='stable')
+    cut = np.round(np.arange(1, points + 1) * len(order) / points).astype(int) - 1
+    T = (t[order] > 0).astype(float)
+    nT, nC = np.cumsum(T)[cut], np.cumsum(1 - T)[cut]
+    ok = (nT > 0) & (nC > 0)
+
+    def lift(v):
+        with np.errstate(divide='ignore', invalid='ignore'):
+            return np.where(ok, nT * (np.cumsum(v[order] * T)[cut] / nT - np.cumsum(v[order] * (1 - T))[cut] / nC), 0.)
+    gain, spend = np.r_[0., lift(y)], np.r_[0., lift(cost)]
+    if gain.max() <= 0 or spend.max() <= 0:
+        return None
+    x, h = spend / spend.max(), gain / gain.max()
+    return float(np.sum(np.diff(x) * (h[1:] + h[:-1]) / 2))
+
+
+class Model:
+    score_is_effect = False  # 점수에 비용이 이미 들어 있어서 효과로 읽지 않아요. Knapsack과 효율 제약 선정에서 이 순서를 그대로 써요.
+
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        y, cost = train.y / (train.y.std() or 1), train.cost / (train.cost.std() or 1)
+        self.arms = []
+        for arm in range(1, train.treatments + 1):
+            rows = (train.t == arm) | (train.t == 0)
+            t = (train.t[rows] == arm).astype(float)
+            e = train.propensities[arm - 1]
+            self.arms.append((r_learner(train.X[rows], t, y[rows], e, context.model_seed, kind), r_learner(train.X[rows], t, cost[rows], e, context.model_seed, kind)))
+        best = None
+        for i, lam in enumerate(LAMBDAS):
+            values = []
+            for arm, (gain, spend) in enumerate(self.arms, 1):
+                rows = (validation.t == arm) | (validation.t == 0)
+                values.append(aucc(gain.predict(validation.X[rows]) - lam * spend.predict(validation.X[rows]), validation.t[rows], validation.y[rows], validation.cost[rows]))
+            values = [v for v in values if v is not None]
+            val = float(np.mean(values)) if values else None
+            context.report(step=i + 1, total=len(LAMBDAS), lam=lam, val=val if val is not None else 0)
+            if best is None or (val is not None and (best[0] is None or val > best[0])):
+                best = (val, lam)
+        self.lam = best[1]
+
+    def predict(self, X):
+        return np.column_stack([gain.predict(X) - self.lam * spend.predict(X) for gain, spend in self.arms])

upliftlab/algorithms/lite/r_learner.py

@@ -0,0 +1,43 @@
+"""결과와 처치의 잔차로 CATE를 학습해요(R-Learner). 비용은 보지 않아요.
+
+경량판: 브라우저에는 EconML이 없어서 웹에서는 같은 방법을 scikit-learn으로 직접 구현한 이 파일을 실행해요.
+로컬(upliftlab)에서는 EconML로 쓴 upliftlab/algorithms/r_learner.py를 실행해요.
+
+y − m(x) = (t − e)·τ(x) + ε
+m(x)는 2-fold cross-fitting으로 구하고, e는 propensity(상수)예요. τ(x)는 목표 (y − m) / (t − e), 가중치 (t − e)²인 회귀로 풀어요.
+회귀 모델은 context.base_learner에 따라 Ridge 또는 Gradient Boosting이에요(scikit-learn).
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingRegressor
+from sklearn.linear_model import Ridge
+from sklearn.model_selection import KFold, cross_val_predict
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+
+NAME = 'R-Learner'
+
+
+def base_model(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+def r_learner(X, t, y, propensity, seed, kind):
+    """τ(x)를 예측하는 모델을 반환해요."""
+    m = cross_val_predict(base_model(kind), X, y, cv=KFold(2, shuffle=True, random_state=seed))
+    w = t - propensity
+    weight = {'sample_weight': w ** 2} if kind == 'tree' else {'ridge__sample_weight': w ** 2}
+    return base_model(kind).fit(X, (y - m) / w, **weight)
+
+
+class Model:
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        self.taus = []
+        for arm in range(1, train.treatments + 1):
+            rows = (train.t == arm) | (train.t == 0)
+            self.taus.append(r_learner(train.X[rows], (train.t[rows] == arm).astype(float), train.y[rows], train.propensities[arm - 1], context.model_seed, kind))
+
+    def predict(self, X):
+        return np.column_stack([tau.predict(X) for tau in self.taus])

upliftlab/algorithms/lite/t_learner.py

@@ -0,0 +1,33 @@
+"""처치군과 대조군에 결과 모델을 따로 학습하고, 두 예측의 차이를 CATE로 써요(T-Learner). 비용은 보지 않아요.
+
+경량판: 브라우저에는 EconML이 없어서 웹에서는 같은 방법을 scikit-learn으로 직접 구현한 이 파일을 실행해요.
+로컬(upliftlab)에서는 EconML로 쓴 upliftlab/algorithms/t_learner.py를 실행해요.
+
+τ̂ₖ(x) = μ̂ₖ(x) − μ̂₀(x)        처치가 여러 종류면 처치마다 계산하고, 점수가 가장 큰 처치를 골라요.
+μ̂는 context.base_learner에 따라 Ridge 또는 Gradient Boosting이에요(scikit-learn).
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingRegressor
+from sklearn.linear_model import Ridge
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+
+NAME = 'T-Learner'
+
+
+def base_model(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+class Model:
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        control = train.t == 0
+        self.mu0 = base_model(kind).fit(train.X[control], train.y[control])
+        self.mu = [base_model(kind).fit(train.X[train.t == arm], train.y[train.t == arm]) for arm in range(1, train.treatments + 1)]
+
+    def predict(self, X):
+        base = self.mu0.predict(X)
+        return np.column_stack([mu.predict(X) - base for mu in self.mu])

upliftlab/algorithms/lite/x_learner.py

@@ -0,0 +1,42 @@
+"""처치군과 대조군의 결과 모델로 사용자별 처치 효과를 대체(impute)하고, 두 효과 모델을 propensity로 가중 평균해요(X-Learner). 비용은 보지 않아요.
+
+경량판: 브라우저에는 EconML이 없어서 웹에서는 같은 방법을 scikit-learn으로 직접 구현한 이 파일을 실행해요.
+로컬(upliftlab)에서는 EconML로 쓴 upliftlab/algorithms/x_learner.py를 실행해요.
+
+Dᵀ = y − μ̂₀(x)  (처치군)        Dᶜ = μ̂₁(x) − y  (대조군)
+τ̂(x) = e·τ̂ᶜ(x) + (1 − e)·τ̂ᵀ(x)
+μ̂와 τ̂는 context.base_learner에 따라 Ridge 또는 Gradient Boosting이고(scikit-learn), e는 propensity예요.
+Ridge에서는 T-Learner와 거의 같은 점수가 나와요. 두 방법의 차이는 비선형 모델과 처치 비율이 불균형할 때 커져요.
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingRegressor
+from sklearn.linear_model import Ridge
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+
+NAME = 'X-Learner'
+
+
+def base_model(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+class Model:
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        control = train.t == 0
+        X0, y0 = train.X[control], train.y[control]
+        mu0 = base_model(kind).fit(X0, y0)
+        self.arms = []
+        for arm in range(1, train.treatments + 1):
+            treated = train.t == arm
+            X1, y1 = train.X[treated], train.y[treated]
+            mu1 = base_model(kind).fit(X1, y1)
+            tau1 = base_model(kind).fit(X1, y1 - mu0.predict(X1))
+            tau0 = base_model(kind).fit(X0, mu1.predict(X0) - y0)
+            self.arms.append((tau1, tau0, float(train.propensities[arm - 1])))
+
+    def predict(self, X):
+        return np.column_stack([e * tau0.predict(X) + (1 - e) * tau1.predict(X) for tau1, tau0, e in self.arms])

upliftlab/algorithms/r_learner.py

@@ -0,0 +1,45 @@
+"""결과와 처치의 잔차로 CATE를 학습해요(R-Learner). 비용은 보지 않아요.
+
+EconML의 NonParamDML이에요. y − m̂(x) = (t − ê(x))·τ(x) + ε에서 m̂, ê를 2-fold cross-fitting으로 구하고,
+τ(x)는 목표 (y − m̂) / (t − ê), 가중치 (t − ê)²인 회귀로 풀어요. 처치가 여러 종류면 처치마다 대조군과 따로 학습해요.
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingClassifier, HistGradientBoostingRegressor
+from sklearn.linear_model import LogisticRegression, Ridge
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+from econml.dml import NonParamDML
+
+NAME = 'R-Learner'
+
+
+def regressor(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+def classifier(kind):
+    if kind == 'tree':
+        return HistGradientBoostingClassifier(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), LogisticRegression(max_iter=1000))
+
+
+def final(kind):
+    """마지막 단계 회귀. EconML이 sample_weight를 넘기므로 파이프라인이 아닌 모델을 써요."""
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return Ridge(alpha=1.0)
+
+
+class Model:
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        self.taus = []
+        for arm in range(1, train.treatments + 1):
+            rows = (train.t == 0) | (train.t == arm)
+            est = NonParamDML(model_y=regressor(kind), model_t=classifier(kind), model_final=final(kind), discrete_treatment=True, cv=2, random_state=context.model_seed)
+            self.taus.append(est.fit(train.y[rows], (train.t[rows] == arm).astype(int), X=train.X[rows]))
+
+    def predict(self, X):
+        return np.column_stack([np.ravel(est.const_marginal_effect(X)) for est in self.taus])

upliftlab/algorithms/random_baseline.py

@@ -0,0 +1,15 @@
+"""무작위 점수로 정렬해요. 비교 기준선(baseline)이고, Cost Curve는 대각선에 가까워요."""
+import numpy as np
+
+NAME = 'Random'
+
+
+class Model:
+    score_is_effect = False  # 점수가 무작위라서 효과로 읽지 않아요. Knapsack과 효율 제약 선정에서 이 순서를 그대로 써요.
+
+    def fit(self, train, validation, context):
+        self.rng = np.random.default_rng(context.seed)
+        self.treatments = train.treatments
+
+    def predict(self, X):
+        return self.rng.random((len(X), self.treatments))

upliftlab/algorithms/t_learner.py

@@ -0,0 +1,28 @@
+"""처치군과 대조군에 결과 모델을 따로 학습하고, 두 예측의 차이를 CATE로 써요(T-Learner). 비용은 보지 않아요.
+
+EconML의 TLearner예요. τ̂ₖ(x) = μ̂ₖ(x) − μ̂₀(x)이고, 처치가 여러 종류면 처치마다 계산해 점수가 가장 큰 처치를 골라요.
+μ̂는 context.base_learner에 따라 Ridge 또는 Gradient Boosting이에요.
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingRegressor
+from sklearn.linear_model import Ridge
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+from econml.metalearners import TLearner
+
+NAME = 'T-Learner'
+
+
+def regressor(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+class Model:
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        self.est = TLearner(models=regressor(kind)).fit(train.y, train.t, X=train.X)
+
+    def predict(self, X):
+        return np.asarray(self.est.const_marginal_effect(X)).reshape(len(X), -1)

upliftlab/algorithms/x_learner.py

@@ -0,0 +1,34 @@
+"""처치군과 대조군의 결과 모델로 사용자별 처치 효과를 대체(impute)하고, 두 효과 모델을 propensity로 가중 평균해요(X-Learner). 비용은 보지 않아요.
+
+EconML의 XLearner예요. Dᵀ = y − μ̂₀(x), Dᶜ = μ̂₁(x) − y로 효과 모델 τ̂ᵀ, τ̂ᶜ를 학습하고 τ̂(x) = e(x)·τ̂ᶜ(x) + (1 − e(x))·τ̂ᵀ(x)로 합쳐요.
+모델은 context.base_learner에 따라 Ridge·로지스틱 회귀 또는 Gradient Boosting이에요.
+"""
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingClassifier, HistGradientBoostingRegressor
+from sklearn.linear_model import LogisticRegression, Ridge
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+from econml.metalearners import XLearner
+
+NAME = 'X-Learner'
+
+
+def regressor(kind):
+    if kind == 'tree':
+        return HistGradientBoostingRegressor(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), Ridge(alpha=1.0))
+
+
+def classifier(kind):
+    if kind == 'tree':
+        return HistGradientBoostingClassifier(max_depth=3, max_iter=100, early_stopping=False, random_state=0)
+    return make_pipeline(StandardScaler(), LogisticRegression(max_iter=1000))
+
+
+class Model:
+    def fit(self, train, validation, context):
+        kind = getattr(context, 'base_learner', 'ridge')
+        self.est = XLearner(models=regressor(kind), propensity_model=classifier(kind)).fit(train.y, train.t, X=train.X)
+
+    def predict(self, X):
+        return np.asarray(self.est.const_marginal_effect(X)).reshape(len(X), -1)