Results

A match returns a MatchSet (nearest neighbor), a KernelSet (kernel or ridge) or a CEMSet (coarsened exact matching). None of them needs an outcome. effect() turns any of them into a MatchResult, and balance() into a BalanceTable.

class match_stream.MatchSet

Matched pairs and weights from match_nn.

Attributes:

• spec (the request as parsed (formula, strata, calipers, order, …))

• memory (the path that ran, “in_memory” or “by_stratum”)

• n_source (rows read from the source)

• n_dropped (rows left out for a missing value or a null score)

• n_strata (exact-matching strata (1 without exact=))

• score_fit (the score model (an hdfe-stream result) when one was fitted)

• score_sd (the standard deviation of the score over all kept units, the) – unit of a caliper on the score

__init__(spec, nar, pairs, memory, source=None)

matches()

The match table, one row per pair: treated_row and control_row (positions in the source, from 0), the ids when id= was given (treated_<id>, control_<id>), rank (1 for the focal unit’s nearest match), distance (the score gap) and subclass (one per focal unit, given with and without replacement).

weights()

Matching weights of the matched units: a matched focal unit weighs 1; a unit matched to focal units weighs the sum, over those units, of 1 / (their number of matches), rescaled so that these weights sum to the number of such units. Unmatched units (weight 0) are left out. Columns: row, the id (when id= was given), treated, weight and subclass (the focal unit’s group; for a unit used by several focal units, with replacement, the lowest).

effect(outcome, *, estimand=None, n_variance_matches=0, bias_adjustment=False, vcov=None, score_correction=None, lone_unit_variance=None, potential_outcomes=False)

The treatment effect on outcome, with Abadie-Imbens or influence-function standard errors.

Parameters:

• outcome (str or list of str) – The outcome column in the source, or several: read in one pass, one estimate each, with their joint vcov. The covariances are those the variances imply (each variance is a quadratic form in the outcome): for influence-function SEs the stacked covariance; for Abadie-Imbens SEs the covariance that makes the variance of the effect on any combination a y1 + b y2 its Abadie-Imbens variance.

• estimand ({"att", "atc", "ate", "nate"} or list of them, optional) – Default: the match’s own. Another one matches again (the ATE matches both ways). A list (["ate", "att", "atc", "nate"]) estimates them in one call, with their joint vcov: the coefficients are ordered by outcome, then estimand. "nate" is the naive effect: the plain difference of means of the units used in matching, no weights. Several estimands, “nate” and potential_outcomes need influence-function standard errors (vcov="if" or {"CRV1": ...}, on source columns, not the subclass, when there are several tables); the estimands covary through the units they share (docs/implementations.md).

• n_variance_matches (int, default 0) – 0: homoskedastic conditional variance; J > 0: each unit’s own, from its J nearest units in the same arm.

• bias_adjustment (bool, str or list of str, default False) – Abadie and Imbens’s (2011) bias adjustment: each match’s outcome is moved to its focal unit’s covariates with a regression of the outcome on these columns, fitted (weighted by the times a unit is used) over the matched units of each arm. True adjusts on the matching covariates of the formula; a list names the columns (numeric, no missing values among the units used). The regression pools the strata; to let it differ by stratum, add stratum indicator columns. Needs vcov="ai".

• vcov (str or dict, optional) – "ai": Abadie and Imbens (2006), for matching with replacement (the default then). "if": the influence function of the weighted mean difference with the weights held fixed, by unit (HC1 on the rows of effect’s table). {"CRV1": "subclass"} (the default without replacement), {"CRV1": "subclass+id"} (advised with replacement), or any source columns: clustered, multi-way with +. "subclass" means the match’s subclass, never a source column of that name.

• score_correction (bool, optional) – Correct the Abadie-Imbens variance for a propensity score that match-stream estimated (Abadie and Imbens 2016). Default: whenever it applies (a fitted score, with or without absorbed fixed effects, n_variance_matches >= 1, no bias adjustment), with a warning when a fitted score goes uncorrected. When a caliper leaves focal units unmatched, the correction concerns the matched units (the score model’s variance stays its own). A score column passed as distance is taken as known.

• lone_unit_variance ({None, "nearest", "pooled"}, optional) – With n_variance_matches >= 1, each unit’s conditional variance comes from its nearest same-arm units within its exact stratum, so a unit alone in its arm there has none. None (the default): the standard error is NaN, with a warning, when the variance needs such a unit (the ATT needs the matched controls’; the ATC, the ATE and the Abadie-Imbens 2016 correction the treated units’ too). "nearest": its n_variance_matches nearest same-arm units in any stratum, on the matching distance (the score, or the whitened covariates); this assumes the variance changes smoothly across strata. "pooled": the mean of its arm’s other conditional variances. The 2016 correction’s own-arm sets for such a unit are, likewise, its nearest units of its arm in any stratum, or its whole arm. Such a unit is often the match of many focal units, so the choice can move the standard error a lot.

• potential_outcomes (bool, default False) – Also report each estimand’s potential-outcome means: the weighted mean outcome of its treated units, "ATT:y(1)", and of its control units, "ATT:y(0)", whose difference is the effect. Influence-function standard errors only.

Returns:

• MatchResult – hdfe-stream’s result API: summary(), tidy(), confint(), etable.

• The Abadie-Imbens variance needs matching with replacement (as in the

• literature it follows). The influence-function variance treats the matches as

• given (see match_stream.effects).

balance(covariates=None)

Balance before and after matching: a BalanceTable. Rows: the score (distance, for score distances) and covariates (default: the formula’s).

counts()

Units by arm: available (after missing values were dropped), matched, unmatched, discarded (common support; the unmatched exclude the discarded); the number of pairs.

summary()

Print what was matched and how.

classmethod __new__(*args, **kwargs)

class match_stream.KernelSet

Kernel or ridge matching from match_kernel: the matched units and their weights. Each focal unit is compared with a weighted average of the other arm’s units of its stratum within the bandwidth, so there is no match table and no subclass.

Attributes:

• spec (the request as parsed (kernel, ridge parameter, bandwidth rule))

• bandwidth (the bandwidth used, in score units)

• bandwidth_info (how it was chosen (_kernel.Bandwidth: the rule, the) – pair-distance bandwidth, and for “cross_validation” the grid with its criterion, .cv)

• memory, n_source, n_dropped, n_strata, score_fit, score_sd (as MatchSet)

__init__(spec, nar, units, bw, memory, source=None)

weights()

The matched units: row, the id (when id= was given), treated, weight. A matched focal unit weighs 1; another unit weighs the sum of its kernel (or ridge) weights over the focal units it serves, rescaled so these weights sum to the number of such units (an estimate uses only their ratios). Ridge weights can be negative. Unmatched units are left out.

effect(outcome, *, estimand=None, vcov=None, potential_outcomes=False)

The treatment effect on outcome (a column, or a list: several outcomes in one pass with their joint vcov, see MatchSet.effect): the difference of the weighted means of the matched units, with the influence-function variance, weights held fixed (see match_stream.effects). vcov: "if" (by unit, the default) or {"CRV1": "a+b"} on source columns. estimand “ate” matches the other way too (each direction with its own bandwidth rule); a list of estimands, with “nate”, and potential_outcomes as in MatchSet.effect. Returns a MatchResult.

balance(covariates=None)

Balance before and after matching, weighting by weights; no pair distance. Rows: the score (distance) and covariates (default: the formula’s).

counts()

Units by arm: available, matched, unmatched.

summary()

Print what was matched and how.

classmethod __new__(*args, **kwargs)

class match_stream.CEMSet

Coarsened exact matching from match_cem: the matched units and their weights. CEM matches cells, not pairs, so there is no match table; subclass is the cell.

Attributes:

• spec (the request as parsed)

• cutpoints (the bins asked for, by covariate)

__init__(spec, units, counts, cutpoints, used=None, source=None)

weights()

The matched units: row (position in the source), the id, treated, weight (matched treated units 1; controls scaled to the same total) and subclass (the cell, numbered 1..). Units in cells without both arms weigh 0 and are left out.

balance(covariates=None)

Balance before and after matching; the pair distance is over all treated-control pairs within each cell. Rows: covariates (default: the formula’s).

effect(outcome, *, estimand=None, vcov=None, potential_outcomes=False)

The treatment effect on outcome (a column, or a list: several outcomes in one pass with their joint vcov, see MatchSet.effect) for the matched estimand: the difference of the CEM-weighted means, with the influence-function variance (weights fixed). vcov: "if" (by unit, the default: clustering on the cell is not advised), or {"CRV1": "a+b"} with "subclass" (the cell) or source columns. estimand may add "nate" (the plain difference of means of the units used) to the matched estimand, and potential_outcomes the treated and control means (see MatchSet.effect). Returns a MatchResult.

counts()

Units by arm (available, matched, unmatched) and matched cells.

summary()

Print what was matched.

classmethod __new__(*args, **kwargs)

class match_stream.MatchResult

A treatment effect estimated from matches, on hdfe-stream’s RegressionResult: its reporting (summary, tidy, confint, wald_test, summary_dict, to_pyfixest) and hdfe_stream.etable work as for the sibling packages’ results.

beta holds one estimate, named "<ATT|ATC|ATE>:<outcome>" (in the pyfixest view, and so in etable, just the estimand: the outcome heads the column); vcov its variance, of the kind vcov names. Inference is normal (tidy’s “t value” column, hdfe-stream’s name for it, is a z statistic).

n_obs is what the estimate uses: for Abadie-Imbens SEs the units (the focal units and their matches); for influence-function SEs the rows of the estimation table (MatchIt’s get_matches(): with replacement a control used by several focal units has a row in each subclass; for CEM and kernel matching the units with a nonzero weight). n_clusters follows hdfe-stream: the clustering ("subclass", "subclass+id") to the number of clusters of each dimension, {"unit": (n,)} by unit, empty for Abadie-Imbens.

Attributes:

• estimand (str) – “att”, “atc” or “ate”.

• n_variance_matches (int) – Same-arm matches for the conditional variances (Abadie-Imbens).

• n_focal (int) – Focal units matched (both arms for the ATE).

• bias_adjustment (list of str or None) – The bias-adjustment covariates.

• bias_coefs (dict) – The bias-adjustment slopes, by the arm they were fitted in.

• vcov_type (str) – “ai”, “if” or “CRV1:<dims>” (hdfe-stream’s attribute).

• score_correction (bool) – Whether the Abadie-Imbens (2016) correction for the estimated score was applied.

• n_lone (int) – Units alone in their arm within their exact stratum, whose conditional variance (n_variance_matches >= 1) has no same-arm neighbor.

• estimands (list of str or None) – With several estimands (or potential outcomes), the estimands, in the order of the coefficients; estimand then joins them.

• n_focal_by (dict) – With several estimands, the focal units of each (“nate”: the units compared).

• labels (list of str or None) – The coefficients’ names in the pyfixest view (etable), when they are not just “<outcome> (<estimand>)”.

• lone_unit_variance (str or None) – How their variances were filled (“nearest” or “pooled”); None if there were none, or none was asked for (the SE is then NaN when the variance needs them).

__init__(n_clusters=<factory>, estimand='att', n_variance_matches=0, n_focal=0, bias_adjustment=None, bias_coefs=<factory>, score_correction=False, n_lone=0, lone_unit_variance=None, outcomes=None, estimands=None, n_focal_by=<factory>, labels=None, *, fml, depvar, coefnames, beta, vcov, vcov_type, df_t, n_obs, all_vcovs=<factory>, collin_vars=<factory>, diagnostics=<factory>, weights=None, weights_type='aweights')

classmethod __new__(*args, **kwargs)

class match_stream.BalanceTable

Balance before and after matching.

Attributes:

• all (polars.DataFrame) – Every unit used, before matching: one row per term, with the columns (Means Treated, Means Control, Std. Mean Diff., Var. Ratio, eCDF Mean, eCDF Max; Std. Pair Dist. is null).

• matched (polars.DataFrame) – The matched units, weighted by the matching weights.

• sizes (polars.DataFrame) – Sample sizes by arm: all, matched (and its effective size, (sum w)^2 / sum w^2), unmatched.

__init__(all_, matched, sizes)

summary()

Print both tables and the sample sizes.

classmethod __new__(*args, **kwargs)

MatchResult is a subclass of hdfe-stream’s RegressionResult, so summary(), tidy(), confint(), wald_test() and etable work as they do for hdfe-stream’s regressions.