Refactor OPE API for reusable schemas and simplify tutorial

Author: Yurashku

README.md

@@ -1,103 +1,40 @@
-# Policyscope: офлайн-оценка рекомендательных систем
+# Policyscope: офлайн‑оценка политик рекомендаций (переиспользуемый пайплайн)
 
-**Policyscope** помогает сравнивать рекомендательные модели без запуска дорогостоящих A/B‑тестов.
-Библиотека переиспользует логи текущей политики и оценивает, насколько другая политика могла бы увеличить целевую метрику.
-Все оценщики ведут подробное логирование на русском языке.
+`Policyscope` помогает оценивать новую политику **B** по логам текущей политики **A** без онлайн A/B‑теста.
 
-## Как это работает
-
-1. **Собираем логи** текущей политики A: какое действие показали, с какой вероятностью и как реагировал пользователь.
-2. **Определяем новую политику B** — например, другую модель рекомендаций.
-3. **Пере‑взвешиваем** наблюдения из логов A и получаем приближённое значение метрики под политикой B.
-
-## Реализованные алгоритмы
-
-- **Replay** — учитывает только те логи, где B совпадает с A.
-- **IPS** — взвешивает отклики по отношению вероятностей выбора в B и A.
-- **SNIPS** — нормализует веса IPS для меньшей дисперсии.
-- **DM (Direct Method)** — строит модель отклика и прогнозирует исходы под политикой B.
-- **Doubly Robust (DR)** — комбинирует Direct Method и IPS; достаточно корректности хотя бы одной из них.
-- **SN-DR** — нормализует поправку IPS на общий вес, улучшая устойчивость.
-- **Switch-DR** — вариант DR, использующий DM для наблюдений с очень большим весом IPS, чтобы уменьшить разброс.
-
-## Предположения и ограничения
-
-- **Replay** — новая политика должна часто совпадать со старой, иначе большинство логов отбрасывается.
-- **IPS** — требует точного знания вероятностей действий в обеих политиках; большие веса увеличивают дисперсию.
-- **SNIPS** — нормализует веса IPS и снижает дисперсию, но остаётся чувствительным к ошибкам вероятностей и малым объёмам данных.
-- **DM (Direct Method)** — зависит от точности модели отклика и может смещаться вне обучающей области.
-- **Doubly Robust (DR)** — корректность достигается, если верна хотя бы модель отклика или пропенсити, но метод чувствителен к ошибкам обеих моделей и выбору клиппинга.
-- **SN-DR** — нормализует поправку IPS на общий вес, уменьшает дисперсию DR, но наследует его предположения.
-- **Switch-DR** — отбрасывает экстремальные веса, сочетая DM и DR, но выбор порога влияет на смещение.
-
-## Jupyter-туториал
-
-Интерактивный ноутбук с теорией и примером расчёта ATE доступен в файле [examples/tutorial.ipynb](examples/tutorial.ipynb).
-В нём разница между политиками вычисляется как `V_DR(B) - V_DR(A)`,
-а истинный эффект оценивается по 100 MC-сэмплам симулятора.
+Главное в текущей версии:
+- API стал **универсальным**: названия колонок (`a_A`, `a_B`, целевая метрика, `user_id`) и список признаков задаются аргументами.
+- Туториал стал короче и практичнее: есть компактный сценарий «взял свой DataFrame → получил все OPE‑оценки».
+- Бутстрэп для DR можно вызывать одной функцией (`dr_with_bootstrap_ci`) без ручной сборки циклов.
 
 ## Установка
 
 ```bash
-python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
+python -m venv .venv && source .venv/bin/activate
 pip install -r requirements.txt
-```
-
-или как пакет:
-
-```bash
+# или
 pip install -e .
 ```
 
-## Пример: синтетический эксперимент
-
-В репозитории есть скрипт, который генерирует пользователей и сравнивает две политики.
-
-```bash
-python examples/run_synthetic_experiment.py \
-  --n_users 50000 \
-  --seed 42 \
-  --policyA epsilon_greedy --epsilon 0.15 \
-  --policyB softmax --tau 0.7 \
-  --horizon 90 \
-  --weight_clip 20
-```
-
-После запуска создаётся папка `artifacts` с логами, оценками и коротким текстовым отчётом.
-
-При работе на синтетике полезно сравнивать офлайн‑оценки с истинным эффектом (oracle). Такое сравнение позволяет проверить состоятельность методов OPE и убедиться, что оценщики не дают систематического смещения.
-
-## Требования к входным данным
-
-Логи политики A должны содержать обязательные поля:
+## Что реализовано
 
-- `user_id` — идентификатор пользователя;
-- `a_A` — действие, которое показала политика A;
-- `propensity_A` — вероятность выбора этого действия политикой A;
-- `accept` и/или `cltv` — отклик и ценность;
-- признаки пользователя (возраст, доход и др.), используемые моделью.
+- Replay
+- IPS / SNIPS
+- DM (Direct Method)
+- DR / SNDR / Switch-DR
+- Кластерный и обычный бутстрэп (если `cluster_col=None`)
 
-Числовые поля `age`, `risk` и `income` можно передавать в исходном масштабе:
-функции обучения (`train_pi_hat`, `train_mu_hat`) автоматически выполняют их
-нормализацию.
+## Минимальный формат данных
 
-## Анализ входных данных
+Нужны:
+- колонка действия, зафиксированного в логах A (по умолчанию `a_A`),
+- целевая метрика (например, `accept`, `cltv` или ваша `reward`),
+- признаки (`feature_cols`),
+- опционально `user_id` для кластерного бутстрэпа.
 
-Чтобы быстро проверить логи и понять, какие методы off-policy оценки доступны,
-воспользуйтесь утилитой:
+Дополнительно можно хранить `a_B` (действие рекомендованное B) для диагностики и таблиц в туториале.
 
-```python
-from policyscope.report import analyze_logs
-print(analyze_logs(df, policyB))
-```
-
-Функция сообщит о наличии ключевых колонок, пересечении политик для Replay и
-подскажет, что требуется для IPS/SNIPS, DM и DR.
-
-## Пример применения на своих данных
-
-Функции обучения выполняют внутреннюю нормализацию числовых признаков,
-поэтому в DataFrame достаточно сырых столбцов `age`, `risk` и `income`.
+## Универсальный пример на своих данных
 
 ```python
 import numpy as np
@@ -107,63 +44,81 @@ from policyscope.estimators import (
     pi_hat_predict,
     train_mu_hat,
     prepare_piB_taken,
-    replay_value,
+    take_action_probabilities,
     ips_value,
     snips_value,
     dm_value,
     dr_value,
-    sndr_value,
-    switch_dr_value,
+    dr_with_bootstrap_ci,
 )
-from policyscope.policies import make_policy
 
-df = pd.read_csv("logs_without_propensity.csv")
-policyB = make_policy("softmax", tau=0.7)
-piB_taken = prepare_piB_taken(df, policyB)
-pi_model = train_pi_hat(df)
-pA_all = pi_hat_predict(pi_model, df)
-pA_taken = pA_all[np.arange(len(df)), df["a_A"].values]
-mu_hat = train_mu_hat(df, target="accept")
-V_replay = replay_value(df, policyB, target="accept")
-V_ips, ess_ips, clip_ips = ips_value(df, piB_taken, pA_taken, target="accept")
-V_snips, ess_snips, clip_snips = snips_value(df, piB_taken, pA_taken, target="accept")
-V_dm = dm_value(df, policyB, mu_hat, target="accept")
-V_dr, ess_dr, clip_dr = dr_value(df, policyB, mu_hat, pA_taken, target="accept")
-V_sndr, ess_sndr, clip_sndr = sndr_value(df, policyB, mu_hat, pA_taken, target="accept")
-V_switch, ess_switch, share_switch = switch_dr_value(df, policyB, mu_hat, pA_taken, tau=20, target="accept")
-print(V_replay, V_ips, V_snips, V_dm, V_dr, V_sndr, V_switch)
-```
+# ваш датасет
+# df columns example:
+# user_col, logged_action, candidate_action, reward, f1, f2, f3
 
-## Валидация оценок
+df = pd.read_csv("my_logs.csv")
 
-- **ESS** — проверяйте эффективный размер выборки, чтобы убедиться в достаточном покрытии новой политики.
-- **Клиппинг** — ограничивайте большие веса IPS, чтобы уменьшить дисперсию и влияние выбросов.
-- **Бутстрэп** — оценивайте доверительные интервалы путём повторной выборки логов.
+feature_cols = ["f1", "f2", "f3"]
+action_col = "logged_action"
+target_col = "reward"
 
-## Логирование
+policyB = ...  # объект с методом action_probs(df) -> (n, k)
 
-Функции‑оценщики выводят подробные сообщения на русском языке. Для каждого
-алгоритма логируется начало работы, проверки корректности пропенсити,
-значение ESS с предупреждением при низком покрытии, доля клиппинга
-и итоговое значение метрики. По умолчанию логирование настроено (формат
-`%(message)s`), поэтому дополнительные настройки не требуются.
+# 1) Вероятность того, что B выбрала бы логированное действие
+piB_taken = prepare_piB_taken(df, policyB, action_col=action_col)
 
-## Разработка
+# 2) Оценка модели поведения A: pA(a|x)
+pi_model = train_pi_hat(df, feature_cols=feature_cols, action_col=action_col)
+pA_all = pi_hat_predict(pi_model, df)
+pA_taken = take_action_probabilities(
+    pA_all,
+    df[action_col].values,
+    action_space=pi_model.classes_,
+)
 
-Перед коммитом выполните проверки стиля и тесты:
+# 3) Модель исхода mu(x, a)
+mu = train_mu_hat(df, target=target_col, feature_cols=feature_cols, action_col=action_col)
+
+# 4) OPE-оценки
+v_ips, ess_ips, clip_ips = ips_value(df, piB_taken, pA_taken, target=target_col, action_col=action_col)
+v_snips, ess_snips, clip_snips = snips_value(df, piB_taken, pA_taken, target=target_col, action_col=action_col)
+v_dm = dm_value(df, policyB, mu, target=target_col)
+v_dr, ess_dr, clip_dr = dr_value(df, policyB, mu, pA_taken, target=target_col, action_col=action_col)
+
+# 5) DR + bootstrap CI одной функцией
+dr_ci = dr_with_bootstrap_ci(
+    df,
+    policyB,
+    target=target_col,
+    feature_cols=feature_cols,
+    action_col=action_col,
+    cluster_col="user_col",   # либо None
+    n_boot=300,
+)
+print(v_ips, v_snips, v_dm, v_dr, dr_ci)
+```
+
+## Быстрый синтетический запуск
 
 ```bash
-python -m flake8 src tests
-pytest
+python examples/run_synthetic_experiment.py --n_users 50000 --seed 42 --policyA epsilon_greedy --policyB softmax
 ```
 
-CI также запускает синтетический эксперимент `examples/run_synthetic_experiment.py`, чтобы убедиться в корректной работе библиотеки.
+Скрипт сохраняет артефакты в `artifacts/`.
+
+## Туториал
 
-## Ссылки
+- Основной notebook: `examples/tutorial.ipynb`
+- В нём показано:
+  1. проверка логов,
+  2. таблица с фичами + `a_A` + `a_B`,
+  3. компактный расчёт всех метрик,
+  4. bootstrap через `dr_with_bootstrap_ci`.
 
-- Joachims et al., *Unbiased Learning-to-Rank with Biased Feedback* (WSDM 2017)
-- Dudík et al., *Doubly Robust Policy Evaluation and Learning* (ICML 2011)
-- Farajtabar et al., *More Robust Doubly Robust Off-policy Evaluation* (arXiv:2205.13421)
-- [Counterfactual Evaluation for Recommendation Systems](https://eugeneyan.com/writing/offline-recsys/)
+## Проверки перед коммитом
 
-Policyscope распространяется по лицензии MIT.
+```bash
+python -m flake8 src tests
+pytest
+jupyter nbconvert --to notebook --execute examples/tutorial.ipynb --inplace
+```

examples/run_synthetic_experiment.py

@@ -23,10 +23,6 @@
 
 import argparse
 import os
-import json
-import numpy as np
-import pandas as pd
-from typing import Tuple
 
 from policyscope.synthetic import SynthConfig, SyntheticRecommenderEnv
 from policyscope.policies import make_policy
@@ -41,9 +37,9 @@
     train_mu_hat,
     train_pi_hat,
     pi_hat_predict,
-    ate_from_values,
+    take_action_probabilities,
+    dr_with_bootstrap_ci,
 )
-from policyscope.bootstrap import paired_bootstrap_ci
 from policyscope.report import decision_summary, dump_json
 
 
@@ -77,6 +73,7 @@ def main() -> None:
 
     # Генерируем логи A
     logsA = env.simulate_logs_A(policyA, X)
+    logsA["a_B"] = policyB.action_argmax(X)
 
     # On‑policy значения для A
     vA_accept = value_on_policy(logsA, target="accept")
@@ -90,7 +87,7 @@ def main() -> None:
     mu_cltv = train_mu_hat(logsA, target="cltv")
     pi_model = train_pi_hat(logsA)
     pA_all = pi_hat_predict(pi_model, logsA)
-    pA_taken = pA_all[np.arange(len(logsA)), logsA["a_A"].values]
+    pA_taken = take_action_probabilities(pA_all, logsA["a_A"].values, action_space=pi_model.classes_)
 
     # Replay (на совпадающих действиях)
     vB_replay_accept = replay_value(logsA, policyB.action_argmax(X), target="accept")
@@ -133,21 +130,27 @@ def main() -> None:
     dr_abs_error_accept = abs(vB_dr_accept - vB_accept_true)
     dr_abs_error_cltv = abs(vB_dr_cltv - vB_cltv_true)
 
-    # Paired bootstrap for DR
-    def estimator_pair_accept(df_part: pd.DataFrame) -> Tuple[float, float, float]:
-        mu_acc = train_mu_hat(df_part, target="accept")
-        vA = value_on_policy(df_part, target="accept")
-        vB, _, _ = dr_value(df_part, policyB, mu_acc, target="accept", weight_clip=args.weight_clip)
-        return vA, vB, ate_from_values(vB, vA)
-
-    def estimator_pair_cltv(df_part: pd.DataFrame) -> Tuple[float, float, float]:
-        mu = train_mu_hat(df_part, target="cltv")
-        vA = value_on_policy(df_part, target="cltv")
-        vB, _, _ = dr_value(df_part, policyB, mu, target="cltv", weight_clip=args.weight_clip)
-        return vA, vB, ate_from_values(vB, vA)
-
-    res_accept = paired_bootstrap_ci(logsA, estimator_pair_accept, cluster_col="user_id", n_boot=300, alpha=0.05)
-    res_cltv = paired_bootstrap_ci(logsA, estimator_pair_cltv, cluster_col="user_id", n_boot=300, alpha=0.05)
+    # Paired bootstrap for DR (внутренняя обёртка)
+    res_accept = dr_with_bootstrap_ci(
+        logsA,
+        policyB,
+        target="accept",
+        feature_cols=["loyal", "age", "risk", "income"],
+        action_col="a_A",
+        n_boot=300,
+        alpha=0.05,
+        weight_clip=args.weight_clip,
+    )
+    res_cltv = dr_with_bootstrap_ci(
+        logsA,
+        policyB,
+        target="cltv",
+        feature_cols=["loyal", "age", "risk", "income"],
+        action_col="a_A",
+        n_boot=300,
+        alpha=0.05,
+        weight_clip=args.weight_clip,
+    )
 
     # Диагностика весов
     diagnostics = {