*! version 1.2.4 20261103 github.com/mdroste/stata-ctools program define cpsmatch, rclass sortpreserve version 14.1 * Check observation limit (Stata plugin API limitation) if _N > 2147483647 { di as error "ctools does not support datasets exceeding 2^31 (2.147 billion) observations" di as error "This is a limitation of Stata's plugin API" exit 920 } capture noisily syntax varlist(min=1 numeric fv) [if] [in], /// [OUTcome(varname numeric) Pscore(varname numeric) /// Logit Probit /// Neighbor(integer 1) Caliper(real 0) Radius Kernel /// Kerneltype(string) Bwidth(real 0.06) /// Common NOREPlacement Ties Descending /// Verbose THReads(integer 0)] if _rc == 109 { exit 2000 } else if _rc != 0 { exit _rc } * The if is evaluated now, before any helper replaces the r() or e() * results it may name; the matching sample is completed below. marksample touse * ========================================================================= * UPFRONT VALIDATION * ========================================================================= * Split varlist into treatment variable and covariates gettoken depvar treatvar : varlist * depvar = treatment variable (first var) * treatvar = covariates (remaining vars); factor variables are allowed, * as in psmatch2, and expanded by the score model _fv_check_depvar `depvar' local treatvar = strtrim(`"`treatvar'"') * psmatch2's option checks, in its order if "`pscore'" != "" & "`treatvar'" != "" { di as error "You cannot specify both a varlist AND a propensity score" exit 198 } if "`descending'" != "" & "`noreplacement'" == "" { di as error "Option descending makes only sense when matching without replacement" exit 198 } * As in psmatch2, the treatment needs no particular coding: rows with * _treated == 1 are matched to rows with _treated == 0, and other codes * stay in the sample, on support, with _weight = _treated. if `neighbor' <= 0 { di as error "variable _n1 not found" exit 111 } if !inlist("`kerneltype'", "", "epan", "normal", "biweight", "uniform", "tricube") { di as error "Kerneltype `kerneltype' not recognized" exit 198 } local inputs `varlist' `pscore' `outcome' foreach input of local inputs { if inlist("`input'", "_weight", "_id", "_support", "_pscore", "_treated", "_nn") { di as error "input variable `input' conflicts with a matching output" exit 111 } } * Determine matching method. As in psmatch2, radius takes precedence * over kernel. local method = 0 /* 0=nearest, 1=radius, 2=kernel */ if "`kernel'" != "" { local method = 2 } if "`radius'" != "" { local method = 1 if `caliper' == 0 { local caliper = 0.25 /* Default radius */ } } if "`noreplacement'" != "" & (`method' != 0 | `neighbor' != 1) { di as error "cpsmatch: noreplacement requires nearest-neighbor matching with neighbor(1)" exit 198 } * Kernel type local kernelcode = 0 /* 0=epan, 1=normal, 2=biweight, 3=uniform, 4=tricube */ if "`kerneltype'" != "" { if "`kerneltype'" == "normal" | "`kerneltype'" == "gaussian" { local kernelcode = 1 } else if "`kerneltype'" == "biweight" { local kernelcode = 2 } else if "`kerneltype'" == "uniform" { local kernelcode = 3 } else if "`kerneltype'" == "tricube" { local kernelcode = 4 } } * Default estimation method if "`logit'" == "" & "`probit'" == "" { local probit "probit" } * With/without replacement local with_replace = 1 if "`noreplacement'" != "" { local with_replace = 0 } * Ties handling local handle_ties = 0 if "`ties'" != "" { local handle_ties = 1 } * Common support local common_support = 0 if "`common'" != "" { local common_support = 1 } * Descending order local desc_order = 0 if "`descending'" != "" { local desc_order = 1 } * Verbose timing local __do_timing = ("`verbose'" != "") if `__do_timing' { local __ct_elapsed90 = 0 local __ct_elapsed91 = 0 local __ct_elapsed92 = 0 local __ct_elapsed94 = 0 if "`__ct_elapsed90'" == "" local __ct_elapsed90 = 0 quietly _ctools_clock __ct_start90 if "`__ct_elapsed91'" == "" local __ct_elapsed91 = 0 quietly _ctools_clock __ct_start91 } * ========================================================================= * LOAD PLUGIN * ========================================================================= _ctools_load * Stata scopes plugin registrations to the calling ado program. capture program ctools_plugin, plugin using("`__ctools_plugin'") if _rc != 0 & _rc != 110 exit 601 capture confirm number 0 * ========================================================================= * ESTIMATE PROPENSITY SCORE (if not provided) * ========================================================================= * Drop existing output variables if they exist capture drop _weight capture drop _id capture drop _support capture drop _pscore capture drop _treated capture drop _nn * Matching sample as psmatch2 builds it: treatment, covariates and the * outcome nonmissing, restricted to the score model's e(sample), then a * nonmissing score. capture markout `touse' `outcome' if "`pscore'" != "" { * Use provided propensity score quietly gen double _pscore = `pscore' } else if "`treatvar'" != "" { * Estimate propensity score using covariates (show output like psmatch2) if "`logit'" != "" { logit `depvar' `treatvar' if `touse', nolog } else { probit `depvar' `treatvar' if `touse', nolog } quietly replace `touse' = e(sample) quietly predict double _pscore if `touse', pr } else { di as error "cpsmatch: must specify either pscore() or covariates for estimation" exit 198 } markout `touse' _pscore * ========================================================================= * CREATE OUTPUT VARIABLES * ========================================================================= * Create output variables quietly gen double _weight = . quietly gen double _id = . quietly gen double _support = . quietly gen byte _treated = `depvar' if `touse' quietly gen long _nn = . * Pass only the matching inputs and outputs in a fixed, one-based order. local allvars "`depvar' _pscore _weight _id _support `outcome' _nn _treated" local treat_idx = 1 local pscore_idx = 2 local weight_idx = 3 local match_idx = 4 local support_idx = 5 local outcome_idx = cond("`outcome'" == "", 0, 6) * Count observations quietly count if `touse' local nobs = r(N) if `nobs' == 0 { di as error "cpsmatch: no observations" exit 2000 } * Build threads option local threads_code "" if `threads' > 0 { local threads_code "threads(`threads')" } if `__do_timing' { quietly _ctools_clock __ct_now local __ct_elapsed91 = `__ct_elapsed91' + (`__ct_now' - `__ct_start91') if "`__ct_elapsed92'" == "" local __ct_elapsed92 = 0 quietly _ctools_clock __ct_start92 } * ========================================================================= * CALL C PLUGIN * ========================================================================= * Build argument string * Format: treat_idx pscore_idx outcome_idx weight_idx match_idx support_idx * nobs method neighbor caliper common kernel bwidth with_replace ties desc verbose local args "`treat_idx' `pscore_idx' `outcome_idx' `weight_idx' `match_idx' `support_idx'" local args "`args' `nobs' `method' `neighbor' `caliper' `common_support'" local args "`args' `kernelcode' `bwidth' `with_replace' `handle_ties' `desc_order'" * Call plugin with ALL variables (like cencode does). The sample marker * goes last, in place of if `touse': the plugin reads it in parallel, * where Stata answers an if one observation at a time. plugin call ctools_plugin `allvars' `touse', "cpsmatch `threads_code' `args' touse stats" if `__do_timing' { quietly _ctools_clock __ct_now local __ct_elapsed92 = `__ct_elapsed92' + (`__ct_now' - `__ct_start92') } * ========================================================================= * POST-PROCESSING * ========================================================================= * _nn is written by C: actual matches, zero for unmatched treated rows, * missing for controls and observations outside the matching sample. * ========================================================================= * CALCULATE ATT (if outcome specified) * ========================================================================= if `__do_timing' { if "`__ct_elapsed94'" == "" local __ct_elapsed94 = 0 quietly _ctools_clock __ct_start94 } local att = . local att_se = . local att_t = . if "`outcome'" != "" { * C computes the sufficient statistics on the loaded matching sample. * Keep scalar expressions and numeric-local expansion here so the * existing ATT, inference and display rounding remain unchanged. local y1_bar = scalar(_cpsmatch_y1) local n1 = scalar(_cpsmatch_n1) local var1 = scalar(_cpsmatch_var1) local y0_bar = scalar(_cpsmatch_y0) local n0 = scalar(_cpsmatch_n0) if `n1' > 0 & `n0' > 0 { local att = `y1_bar' - `y0_bar' * psmatch2 default ATT variance: unweighted group variances, * with squared match-frequency weights for reused controls. local var0 = scalar(_cpsmatch_var0) local sum_weight_squared = scalar(_cpsmatch_w2) local att_se = sqrt(`var1'/`n1' + `var0'*`sum_weight_squared'/`n1'^2) if `att_se' > 0 { local att_t = `att' / `att_se' } } } * ========================================================================= * DISPLAY RESULTS (psmatch2-compatible format) * ========================================================================= * ATT results table (psmatch2 format) if "`outcome'" != "" & `att' != . { * Calculate unmatched difference local y1_unmatched = scalar(_cpsmatch_y1_u) local y0_unmatched = scalar(_cpsmatch_y0_u) local unmatched_diff = `y1_unmatched' - `y0_unmatched' * Calculate unmatched SE and t-stat local var1_u = scalar(_cpsmatch_var1_u) local n1_u = scalar(_cpsmatch_n1_u) local var0_u = scalar(_cpsmatch_var0_u) local n0_u = scalar(_cpsmatch_n0_u) * psmatch2 displays the OLS SE from regressing outcome on treatment. * Use its pooled residual variance; a singleton group contributes zero SSE. local sse1_u = cond(`n1_u' > 1, (`n1_u'-1)*`var1_u', 0) local sse0_u = cond(`n0_u' > 1, (`n0_u'-1)*`var0_u', 0) local pooled_var = (`sse1_u' + `sse0_u')/(`n1_u' + `n0_u' - 2) local unmatched_se = sqrt(`pooled_var'*(1/`n1_u' + 1/`n0_u')) local unmatched_t = `unmatched_diff' / `unmatched_se' di as text "{hline 78}" di as text " Variable Sample | Treated Controls Difference S.E. T-stat" di as text "{hline 28}+{hline 59}" di as text %16s "`outcome'" " Unmatched |" as result %11.6g `y1_unmatched' %12.6g `y0_unmatched' %12.6g `unmatched_diff' %12.6g `unmatched_se' %9.2f `unmatched_t' di as text " ATT |" as result %11.6g `y1_bar' %12.6g `y0_bar' %12.6g `att' %12.6g `att_se' %9.2f `att_t' di as text "{hline 28}+{hline 59}" di as text "Note: S.E. does not take into account that the propensity score is estimated." } if `__do_timing' { quietly _ctools_clock __ct_now local __ct_elapsed94 = `__ct_elapsed94' + (`__ct_now' - `__ct_start94') } * Treatment assignment table (psmatch2 format) di as text "" local n_untreated_on = scalar(_cpsmatch_n0_on) local n_untreated_off = scalar(_cpsmatch_n0_off) local n_treated_on = scalar(_cpsmatch_n1_on) local n_treated_off = scalar(_cpsmatch_n1_off) local n_untreated_total = `n_untreated_on' + `n_untreated_off' local n_treated_total = `n_treated_on' + `n_treated_off' local n_on_total = `n_untreated_on' + `n_treated_on' local n_off_total = `n_untreated_off' + `n_treated_off' local n_total = `n_on_total' + `n_off_total' di as text " | cpsmatch:" di as text " cpsmatch: | Common" di as text " Treatment | support" if `n_off_total' > 0 { di as text "assignment | On suppor Off suppo | Total" di as text "{hline 11}+{hline 22}+{hline 10}" di as text " Untreated |" as result %10.0f `n_untreated_on' %10.0f `n_untreated_off' as text " |" as result %10.0f `n_untreated_total' di as text " Treated |" as result %10.0f `n_treated_on' %10.0f `n_treated_off' as text " |" as result %10.0f `n_treated_total' di as text "{hline 11}+{hline 22}+{hline 10}" di as text " Total |" as result %10.0f `n_on_total' %10.0f `n_off_total' as text " |" as result %10.0f `n_total' } else { di as text "assignment | On suppor | Total" di as text "{hline 11}+{hline 11}+{hline 10}" di as text " Untreated |" as result %10.0f `n_untreated_on' as text " |" as result %10.0f `n_untreated_total' di as text " Treated |" as result %10.0f `n_treated_on' as text " |" as result %10.0f `n_treated_total' di as text "{hline 11}+{hline 11}+{hline 10}" di as text " Total |" as result %10.0f `n_on_total' as text " |" as result %10.0f `n_total' } di as text "" * ========================================================================= * TIMING OUTPUT (verbose) * ========================================================================= if `__do_timing' { quietly _ctools_clock __ct_now local __ct_elapsed90 = `__ct_elapsed90' + (`__ct_now' - `__ct_start90') * Elapsed seconds are held in caller-local timing state. local __time_total = `__ct_elapsed90' * Elapsed seconds are held in caller-local timing state. local __time_preplugin = `__ct_elapsed91' * Elapsed seconds are held in caller-local timing state. local __time_plugin = `__ct_elapsed92' * Elapsed seconds are held in caller-local timing state. local __time_att = `__ct_elapsed94' di as text "{hline 55}" di as text "cpsmatch timing breakdown:" di as text "{hline 55}" di as text " C plugin internals:" di as text " Load data: " as result %8.4f _cpsmatch_time_load " sec" di as text " Group separation: " as result %8.4f _cpsmatch_time_setup " sec" di as text " Sort/index build: " as result %8.4f _cpsmatch_time_sort " sec" di as text " Matching: " as result %8.4f _cpsmatch_time_match " sec" di as text " Outcome statistics: " as result %8.4f _cpsmatch_time_stats " sec" di as text " Store results: " as result %8.4f _cpsmatch_time_store " sec" di as text " {hline 53}" di as text " C plugin total: " as result %8.4f _cpsmatch_time_total " sec" di as text "" di as text " Stata overhead:" di as text " Pre-plugin setup: " as result %8.4f `__time_preplugin' " sec" di as text " Post-plugin (ATT): " as result %8.4f `__time_att' " sec" di as text " {hline 53}" local __stata_overhead = `__time_preplugin' + `__time_att' di as text " Stata overhead total: " as result %8.4f `__stata_overhead' " sec" di as text "{hline 55}" di as text " Wall clock total: " as result %8.4f `__time_total' " sec" di as text "{hline 55}" * Thread diagnostics capture local __threads_max = _cpsmatch_threads_max if _rc == 0 { capture local __openmp_enabled = _cpsmatch_openmp_enabled if _rc != 0 local __openmp_enabled = 0 di as text "" di as text " Thread diagnostics:" di as text " OpenMP enabled: " as result %8.0f `__openmp_enabled' di as text " Max threads available: " as result %8.0f `__threads_max' di as text "{hline 55}" } } * ========================================================================= * RETURN RESULTS * ========================================================================= return scalar N = `nobs' return scalar n_treated = _cpsmatch_n_treated return scalar n_controls = _cpsmatch_n_controls return scalar n_matched = _cpsmatch_n_matched return scalar n_off_support = _cpsmatch_n_off_support return scalar common_min = _cpsmatch_common_min return scalar common_max = _cpsmatch_common_max * psmatch2 returns the ATT and its standard error, missing when undefined if "`outcome'" != "" { return scalar att = `att' return scalar att_se = `att_se' return scalar seatt = `att_se' return scalar att_t = `att_t' * psmatch2's per-outcome names, where they fit in 32 characters if strlen("att_`outcome'") <= 32 return scalar att_`outcome' = `att' if strlen("seatt_`outcome'") <= 32 return scalar seatt_`outcome' = `att_se' } return local method = cond(`method'==0, "nearest", cond(`method'==1, "radius", "kernel")) return local treatvar "`depvar'" if "`outcome'" != "" { return local outcome "`outcome'" } end