Matching

class hypex.matching.Matching(group_match=False, distance='mahalanobis', bias_estimation=True, quality_tests='auto', faiss_mode='auto', n_neighbors=1, weights=None, encode_categories=True)[source]

Bases: ExperimentShell

A class for performing matching analysis with configurable distance metrics and quality tests.

This class provides functionality to identify groups that are similar to each other using various distance metrics and quality assessment methods.

Parameters:

  • group_match (bool, optional) – Whether to perform group matching. Defaults to False.

  • distance (Literal["mahalanobis", "l2"], optional) – Distance metric to use for matching. Options are “mahalanobis” or “l2”. Defaults to “mahalanobis”.

  • metric (Literal["atc", "att", "ate"], optional) – Type of treatment effect to estimate. “atc” = average treatment effect on controls “att” = average treatment effect on treated “ate” = average treatment effect Defaults to “ate”.

  • bias_estimation (bool, optional) – Whether to estimate bias. Defaults to True.

  • quality_tests (Union[str, List[str]], optional) – Quality tests to perform. Options are “smd”, “psi”, “ks-test”, “repeats”, “t-test”, or “auto”. Can be a single test or list of tests. Defaults to “auto”.

  • faiss_mode (Literal["base", "fast", "auto"], optional) – Faiss mode to use for matching. Options are “base”, “fast”, or “auto”. Defaults to “auto”.

  • n_neighbors (int, optional) – Number of neighbors to use for matching. Defaults to 1.

Examples

# Basic matching with default settings
matching = Matching()
results = matching.execute(data)

# Matching with L2 distance and specific quality tests
matching = Matching(
    distance="l2",
    quality_tests=["t-test", "ks-test"]
)
results = matching.execute(data)

# Group matching with ATT estimation
matching = Matching(
    group_match=True,
    metric="att",
    bias_estimation=True
)
results = matching.execute(data)