Repository navigation
Matching
Matching is a tool for accurate group comparison when standard A/B testing isn't feasible. It eliminates bias from baseline feature differences, enabling fairer effect estimation.
-
Role Assignment
- FeatureRole - Characteristics used for pair matching
- TreatmentRole - Binary column indicating test group membership
- TargetRole - Target metric (e.g., revenue)
- InfoRole - Auxiliary information (IDs, etc.)
-
Matching Pipeline
- Encodes categorical features
- Computes distances between objects (Mahalanobis or L2)
- Finds minimal-distance pairs from opposite groups using faiss search
- Estimates effects: ATT, ATC, ATE
After matching, these metrics interpret treatment effect (e.g., new features, promotions):
ATT measures average effect on those who actually received treatment (test group).
Formula:
-
$N_T$ : Test group size -
$Y_i^{\text{treated}}$ : Outcome for test group object$i$ -
$Y_{i, \text{matched}}^{\text{control}}$ : Outcome for matched control group object
Put simply:
ATT shows how the target metric changed for treated users compared to similar control users.
ATC estimates average effect if control group received treatment.
Formula:
-
$N_C$ : Control group size -
$Y_j^{\text{control}}$ : Outcome for control group object$j$ -
$Y_{j, \text{matched}}^{\text{treated}}$ : Outcome for matched test group object
Put simply:
ATC answers: "What would happen if we treated the control group?"
ATE measures overall average treatment effect, combining ATT and ATC.
Formula:
-
$N = N_T + N_C$ : Total population size
Put simply:
ATE is the size-weighted average difference between groups - the primary indicator of overall impact.
In result.resume:
| Effect Size | Standard Error | P-value | CI Lower | CI Upper | Metric | |
|---|---|---|---|---|---|---|
| ATT | 63.37 | 2.45 | 0.0 | 58.57 | 68.16 | post_spends |
| ATC | 96.47 | 1.57 | 0.0 | 93.40 | 99.55 | post_spends |
| ATE | 80.13 | 1.44 | 0.0 | 77.31 | 82.95 | post_spends |
- ATT = 63.37: Average effect for test group
- ATC = 96.47: Estimated effect for control group
- ATE = 80.13: Overall population effect
- ATT: When focusing on actual treatment recipients (e.g., users who saw new feature)
- ATC: When estimating control group impact
- ATE: For general population effects (default)
In HypEx, select metrics via metric parameter:
test = Matching(metric="att") # ATT
test = Matching(metric="atc") # ATC
test = Matching(metric="ate") # ATE (default)- ATT: Effect for treated objects
- ATC: Effect for control objects
- ATE: Weighted overall effect
HypEx reports selected metric under
Effect Size.
-
T-test and KS-test for numerical features:
- Verify feature distribution similarity after matching
-
OK= homogeneity achieved -
NOT OK= possible imbalance (check pair quality)
- p-value: Probability of random difference (p-value). p-value > 0.05 indicates homogeneity.
from hypex import Matching
from hypex.dataset import Dataset, FeatureRole, InfoRole, TargetRole, TreatmentRole
data = Dataset(
roles={
"user_id": InfoRole(int),
"treat": TreatmentRole(int),
"post_spends": TargetRole(float)
},
data="data.csv",
default_role=FeatureRole(),
)
data = data.fillna(method="bfill")
test = Matching(quality_tests=['t-test', 'ks-test'])
result = test.execute(data)
print(result.resume)
print(result.quality_results)Effect Estimation:
| Effect Size | Standard Error | P-value | CI Lower | CI Upper | Metric | |
|---|---|---|---|---|---|---|
| ATT | 63.37 | 2.45 | 0.0 | 58.57 | 68.16 | post_spends |
| ATC | 96.47 | 1.57 | 0.0 | 93.40 | 99.55 | post_spends |
| ATE | 80.13 | 1.44 | 0.0 | 77.31 | 82.95 | post_spends |
Group Homogeneity Check:
| feature | TTest pass | TTest p-value | KSTest pass | KSTest p-value |
|---|---|---|---|---|
| signup_month | NOT OK | 0.00 | NOT OK | 0.00 |
| pre_spends | NOT OK | 1.8e-212 | NOT OK | 3.2e-231 |
| age | OK | 0.96 | OK | 0.72 |
- Select effect metrics (
metric="ate","att","atc") - Choose distance metrics (
distance="mahalanobis"or"l2") - Configure balance tests for pair quality
Matching in HypEx provides fast, transparent effect estimation accounting for key features - even with initially imbalanced groups!
Matching — это инструмент для корректного сравнения групп в ситуациях, когда стандартный A/B-тест невозможен. Мэтчинг позволяет устранить искажения, связанные с различиями в базовых признаках, и получить более честную оценку эффекта.
-
Назначение ролей
- FeatureRole — признаки, по которым производится подбор пар.
- TreatmentRole — бинарная колонка с принадлежностью к тестовой группе.
- TargetRole — целевая метрика (например, выручка).
- InfoRole — вспомогательная информация (ID и т.д.).
-
Пайплайн мэтчинга
- Категориальные признаки кодируются.
- Вычисляется расстояние между объектами (Mahalanobis или L2).
- Для каждого объекта ищется пара из другой группы с минимальным расстоянием (поиск с помощью faiss).
- Оцениваются эффекты: ATT, ATC, ATE.
В задачах оценки причинно-следственного эффекта (causal effect) после мэтчинга важно уметь интерпретировать, как именно воздействие (например, новая фича, акция, изменение продукта) влияет на разные группы пользователей. Для этого используются три ключевые метрики:
ATT — это средний эффект воздействия на тех, кто реально получил воздействие (был в тестовой группе).
Формула:
-
$N_T$ — количество объектов в тестовой (treated) группе. -
$Y_i^{\text{treated}}$ — результат (метрика) для объекта$i$ из тестовой группы. -
$Y_{i, \text{matched}}^{\text{control}}$ — результат для подобранного по мэтчингу объекта из контрольной группы.
Простыми словами:
ATT показывает, насколько в среднем изменилась целевая метрика у тех, кто получил воздействие, по сравнению с максимально похожими на них из контрольной группы.
ATC — это средний эффект, который был бы у контрольной группы, если бы они получили воздействие.
Формула:
-
$N_C$ — количество объектов в контрольной (control) группе. -
$Y_j^{\text{control}}$ — результат для объекта$j$ из контрольной группы. -
$Y_{j, \text{matched}}^{\text{treated}}$ — результат для подобранного по мэтчингу объекта из тестовой группы.
Простыми словами:
ATC отвечает на вопрос: "А что было бы, если бы мы применили воздействие к тем, кто его не получил?"
ATE — это средний эффект воздействия по всей выборке, то есть обобщение ATT и ATC.
Формула:
-
$N = N_T + N_C$ — общее число объектов.
Простыми словами:
ATE — это средневзвешенная разница между тестовой и контрольной группой, учитывающая их размеры. Это главный показатель общего эффекта воздействия.
В отчёте HypEx (result.resume) вы увидите такие строки:
| Effect Size | Standard Error | P-value | CI Lower | CI Upper | |
|---|---|---|---|---|---|
| ATT | 63.37 | 2.45 | 0.0 | 58.57 | 68.16 |
| ATC | 96.47 | 1.57 | 0.0 | 93.40 | 99.55 |
| ATE | 80.13 | 1.44 | 0.0 | 77.31 | 82.95 |
- ATT = 63.37: средний эффект для тестовой группы.
- ATC = 96.47: средний эффект, если бы контрольная группа получила воздействие.
- ATE = 80.13: общий средний эффект по всей выборке.
- ATT — если вас интересует только эффект на тех, кто реально получил воздействие (например, только пользователи, увидевшие новую фичу).
- ATC — если важно понять, что было бы с контрольной группой при воздействии.
- ATE — если нужен общий эффект для всей популяции (наиболее универсальный случай).
В HypEx вы можете выбрать нужную метрику при запуске мэтчинга через параметр metric:
test = Matching(metric="att") # ATT
test = Matching(metric="atc") # ATC
test = Matching(metric="ate") # ATE (по умолчанию)- ATT (Average Treatment effect on Treated) — средний эффект для тестовых объектов.
- ATC (Average Treatment effect on Controls) — средний эффект для контрольных объектов.
- ATE (Average Treatment Effect) — средневзвешенное между ATT и ATC, общий эффект воздействия.
В HypEx колонка
Effect Sizeв отчете — это значение ATT, ATC или ATE в зависимости от выбранной метрики.
-
T-test и KS-test для числовых признаков:
- Проверяют, насколько сопоставимы распределения признаков в группах после мэтчинга.
- Если
pass = OK— однородность по признаку достигнута. - Если
pass = NOT OK— возможен дисбаланс, стоит проверить качество подбора пар.
- p-value — вероятность случайного различия (подробнее: p-value). Если p-value > 0.05, однородность считается достигнутой.
from hypex import Matching
from hypex.dataset import Dataset, FeatureRole, InfoRole, TargetRole, TreatmentRole
data = Dataset(
roles={
"user_id": InfoRole(int),
"treat": TreatmentRole(int),
"post_spends": TargetRole(float)
},
data="data.csv",
default_role=FeatureRole(),
)
data = data.fillna(method="bfill")
test = Matching(quality_tests=['t-test', 'ks-test'])
result = test.execute(data)
print(result.resume)
print(result.quality_results)Оценка эффекта:
| Effect Size | Standard Error | P-value | CI Lower | CI Upper | |
|---|---|---|---|---|---|
| ATT | 63.37 | 2.45 | 0.0 | 58.57 | 68.16 |
| ATC | 96.47 | 1.57 | 0.0 | 93.40 | 99.55 |
| ATE | 80.13 | 1.44 | 0.0 | 77.31 | 82.95 |
Проверка однородности групп:
| feature | TTest pass | TTest p-value | KSTest pass | KSTest p-value |
|---|---|---|---|---|
| signup_month | NOT OK | 0.00 | NOT OK | 0.00 |
| pre_spends | NOT OK | 1.8e-212 | NOT OK | 3.2e-231 |
| age | OK | 0.96 | OK | 0.72 |
- Можно выбирать метрику оценки (
metric="ate","att","atc"). - Можно менять способ вычисления расстояния (
distance="mahalanobis"или"l2"). - Можно настраивать качество подбора пар с помощью дополнительных тестов баланса.
Matching в HypEx — это быстрый и прозрачный способ получить честную оценку эффекта с учетом всех важных признаков, даже если группы изначально не были сопоставимы!