Skip to content

Matching

anastasiiafed24 edited this page Jul 24, 2025 · 5 revisions

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.

How Matching Works in HypEx

  1. 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.)
  2. 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

Key Causal Effect Metrics

After matching, these metrics interpret treatment effect (e.g., new features, promotions):

1. ATT (Average Treatment effect on Treated)

ATT measures average effect on those who actually received treatment (test group).

Formula:
$ATT = \frac{1}{N_T} \sum_{i \in T} \left( Y_i^{\text{treated}} - Y_{i, \text{matched}}^{\text{control}} \right)$

  • $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.

2. ATC (Average Treatment effect on Controls)

ATC estimates average effect if control group received treatment.

Formula:
$ATC = \frac{1}{N_C} \sum_{j \in C} \left( Y_{j, \text{matched}}^{\text{treated}} - Y_j^{\text{control}} \right)$

  • $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?"

3. ATE (Average Treatment Effect)

ATE measures overall average treatment effect, combining ATT and ATC.

Formula:
$ATE = \frac{N_T}{N} \cdot ATT + \frac{N_C}{N} \cdot ATC$

  • $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.

HypEx Output Example

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

When to Use Each Metric

  • 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)

Summary:

  • ATT: Effect for treated objects
  • ATC: Effect for control objects
  • ATE: Weighted overall effect

HypEx reports selected metric under Effect Size.

Post-Matching Group Homogeneity Check

  • 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.

Code Example

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)

Sample Report

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

Matching Flexibility in HypEx

  • 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

Matching — это инструмент для корректного сравнения групп в ситуациях, когда стандартный A/B-тест невозможен. Мэтчинг позволяет устранить искажения, связанные с различиями в базовых признаках, и получить более честную оценку эффекта.

Как работает Matching в HypEx

  1. Назначение ролей

    • FeatureRole — признаки, по которым производится подбор пар.
    • TreatmentRole — бинарная колонка с принадлежностью к тестовой группе.
    • TargetRole — целевая метрика (например, выручка).
    • InfoRole — вспомогательная информация (ID и т.д.).
  2. Пайплайн мэтчинга

    • Категориальные признаки кодируются.
    • Вычисляется расстояние между объектами (Mahalanobis или L2).
    • Для каждого объекта ищется пара из другой группы с минимальным расстоянием (поиск с помощью faiss).
    • Оцениваются эффекты: ATT, ATC, ATE.

Основные метрики

В задачах оценки причинно-следственного эффекта (causal effect) после мэтчинга важно уметь интерпретировать, как именно воздействие (например, новая фича, акция, изменение продукта) влияет на разные группы пользователей. Для этого используются три ключевые метрики:

1. ATT (Average Treatment effect on Treated)

ATT — это средний эффект воздействия на тех, кто реально получил воздействие (был в тестовой группе).

Формула:

$ATT = \frac{1}{N_T} \sum_{i \in T} \left( Y_i^{\text{treated}} - Y_{i, \text{matched}}^{\text{control}} \right)$

  • $N_T$ — количество объектов в тестовой (treated) группе.
  • $Y_i^{\text{treated}}$ — результат (метрика) для объекта $i$ из тестовой группы.
  • $Y_{i, \text{matched}}^{\text{control}}$ — результат для подобранного по мэтчингу объекта из контрольной группы.

Простыми словами:
ATT показывает, насколько в среднем изменилась целевая метрика у тех, кто получил воздействие, по сравнению с максимально похожими на них из контрольной группы.

2. ATC (Average Treatment effect on Controls)

ATC — это средний эффект, который был бы у контрольной группы, если бы они получили воздействие.

Формула:

$ATC = \frac{1}{N_C} \sum_{j \in C} \left( Y_{j, \text{matched}}^{\text{treated}} - Y_j^{\text{control}} \right)$

  • $N_C$ — количество объектов в контрольной (control) группе.
  • $Y_j^{\text{control}}$ — результат для объекта $j$ из контрольной группы.
  • $Y_{j, \text{matched}}^{\text{treated}}$ — результат для подобранного по мэтчингу объекта из тестовой группы.

Простыми словами:
ATC отвечает на вопрос: "А что было бы, если бы мы применили воздействие к тем, кто его не получил?"

3. ATE (Average Treatment Effect)

ATE — это средний эффект воздействия по всей выборке, то есть обобщение ATT и ATC.

Формула:

$ATE = \frac{N_T}{N} \cdot ATT + \frac{N_C}{N} \cdot ATC$

  • $N = N_T + N_C$ — общее число объектов.

Простыми словами:
ATE — это средневзвешенная разница между тестовой и контрольной группой, учитывающая их размеры. Это главный показатель общего эффекта воздействия.

Пример из HypEx

В отчёте 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

Гибкость Matching в HypEx

  • Можно выбирать метрику оценки (metric="ate", "att", "atc").
  • Можно менять способ вычисления расстояния (distance="mahalanobis" или "l2").
  • Можно настраивать качество подбора пар с помощью дополнительных тестов баланса.

Matching в HypEx — это быстрый и прозрачный способ получить честную оценку эффекта с учетом всех важных признаков, даже если группы изначально не были сопоставимы!