Skip to content

brycewang-stanford/Auto-Empirical-Research-Skills / skills/32-dylantmoore-stata-skill/plugins/stata/skills/stata

Comprehensive Stata reference for writing correct .do files, data management, econometrics, causal inference, graphics, Mata programming, and 20 community packages (reghdfe, estout, did, rdrobust, etc.). Covers syntax, options, gotchas, and idiomatic patterns. Use this skill whenever the user asks you to write, debug, or explain Stata code.

FileKindSize
SKILL.mdskill md16.4 KB
packages/asdoc.mdmarkdown8.5 KB
packages/binsreg.mdmarkdown10.1 KB
packages/coefplot.mdmarkdown10.1 KB
packages/data-manipulation.mdmarkdown10.1 KB
packages/diagnostics.mdmarkdown15.3 KB
packages/did.mdmarkdown16.0 KB
packages/estout.mdmarkdown17.7 KB
packages/event-study.mdmarkdown29.8 KB
packages/graph-schemes.mdmarkdown14.1 KB
packages/ivreg2.mdmarkdown11.1 KB
packages/nprobust.mdmarkdown12.4 KB
packages/outreg2.mdmarkdown11.2 KB
packages/package-management.mdmarkdown10.2 KB
packages/psmatch2.mdmarkdown18.6 KB
packages/rdrobust.mdmarkdown13.4 KB
packages/reghdfe.mdmarkdown10.4 KB
packages/synth.mdmarkdown23.0 KB
packages/tabout.mdmarkdown12.1 KB
packages/winsor.mdmarkdown6.7 KB
packages/xtabond2.mdmarkdown14.9 KB
references/advanced-programming.mdmarkdown10.1 KB
references/basics-getting-started.mdmarkdown5.8 KB
references/bootstrap-simulation.mdmarkdown8.4 KB
references/data-import-export.mdmarkdown7.4 KB
references/data-management.mdmarkdown11.0 KB
references/date-time-functions.mdmarkdown6.8 KB
references/descriptive-statistics.mdmarkdown6.4 KB
references/difference-in-differences.mdmarkdown20.9 KB
references/external-tools-integration.mdmarkdown20.1 KB
references/filing-issues.mdmarkdown4.7 KB
references/gmm-estimation.mdmarkdown8.8 KB
references/graphics.mdmarkdown8.6 KB
references/limited-dependent-variables.mdmarkdown8.2 KB
references/linear-regression.mdmarkdown12.4 KB
references/machine-learning.mdmarkdown12.4 KB
references/mata-data-access.mdmarkdown8.2 KB
references/mata-introduction.mdmarkdown6.4 KB
references/mata-matrix-operations.mdmarkdown6.3 KB
references/mata-programming.mdmarkdown8.4 KB
references/matching-methods.mdmarkdown19.2 KB
references/mathematical-functions.mdmarkdown7.4 KB
references/maximum-likelihood.mdmarkdown16.6 KB
references/missing-data-handling.mdmarkdown18.5 KB
references/nonparametric-methods.mdmarkdown11.7 KB
references/panel-data.mdmarkdown8.7 KB
references/programming-basics.mdmarkdown8.1 KB
references/regression-discontinuity.mdmarkdown13.4 KB
references/sample-selection.mdmarkdown17.7 KB
references/sem-factor-analysis.mdmarkdown15.2 KB
references/spatial-analysis.mdmarkdown19.4 KB
references/string-functions.mdmarkdown8.7 KB
references/survey-data-analysis.mdmarkdown13.7 KB
references/survival-analysis.mdmarkdown12.3 KB
references/tables-reporting.mdmarkdown24.2 KB
references/time-series.mdmarkdown9.9 KB
references/treatment-effects.mdmarkdown23.1 KB
references/variables-operators.mdmarkdown4.9 KB
references/workflow-best-practices.mdmarkdown25.8 KB

packages/binsreg.md

View on GitHub
# BINSREG: Binscatter Estimation and Inference

## Overview

The `binsreg` package (Cattaneo, Crump, Farrell, Feng) implements modern binscatter methods with rigorous statistical foundations: data-driven bin selection, pointwise and uniform inference, hypothesis testing, and support for OLS, logit, probit, and quantile regression.

**Key advantage over traditional `binscatter` (Stepner):** Proper covariate adjustment (no residualization), formal inference (CI/CB), optimal bin selection, and hypothesis testing.

### Package Commands

| Command | Purpose |
|---------|---------|
| `binsreg` | Binscatter for continuous outcomes (OLS) |
| `binslogit` | Binscatter for binary outcomes (logit) |
| `binsprobit` | Binscatter for binary outcomes (probit) |
| `binsqreg` | Binscatter for quantile regression |
| `binstest` | Hypothesis testing (linearity, monotonicity, shape) |
| `binspwc` | Pairwise group comparison |
| `binsregselect` | Optimal bin count selection |

---

## Installation

```stata
net install binsreg, from(https://raw.githubusercontent.com/nppackages/binsreg/master/stata) replace
which binsreg
help binsreg
```

Also available in R (`install.packages('binsreg')`) and Python (`pip install binsreg`).

---

## Core Syntax and Options

### binsreg (Main Command)

```stata
binsreg depvar xvar [controls] [if] [in] [weight] [, options]
```

**Binning Options:**
- `nbins(#)` - Number of bins (default: data-driven)
- `binspos(es|qs)` - Evenly-spaced or quantile-spaced bins
- `binsmethod(dpi|rot)` - Bin selection method (direct plug-in or rule-of-thumb)

**Polynomial Options (all take `(p v)` = polynomial degree, derivative order):**
- `dots(p v)` - Dots (use `dots(0,0)` for canonical binscatter)
- `line(p v)` - Smooth line connecting bins
- `ci(p v)` - Pointwise confidence intervals
- `cb(p v)` - Uniform confidence bands
- `polyreg(#)` - Global polynomial overlay of specified degree
- `deriv(#)` - Plot derivative of specified order

**Inference Options:**
- `level(#)` - Confidence level (default: 95)
- `vce(robust)` - Heteroskedasticity-robust
- `vce(cluster clustervar)` - Cluster-robust
- `vce(bootstrap, reps(#))` - Bootstrap (recommended for quantile regression)

**Covariate Options:**
- `at(mean|median|#)` - Evaluation point for control variables
- `absorb(varlist)` - Fixed effects to absorb

**Grouping Options:**
- `by(groupvar)` - Separate binscatter by group
- `bycolors(colorlist)` - Colors per group
- `bysymbols(symbollist)` - Symbols per group

**Output Options:**
- `saveplot(filename)` - Save graph (.png, .pdf, .gph)
- `savedata(filename)` - Save bin data for custom plotting
- `name(graphname, replace)` - Named graph for `graph combine`

Standard Stata graph options (`title()`, `xtitle()`, `ytitle()`, `legend()`, `scheme()`, etc.) all work.

---

## Covariate Adjustment (Critical Difference)

**WRONG -- traditional residualization approach (biased):**
```stata
* DON'T DO THIS
reg wage controls
predict wage_resid, resid
reg education controls
predict educ_resid, resid
binscatter wage_resid educ_resid
```

**CORRECT -- binsreg handles adjustment internally:**
```stata
* DO THIS -- estimates E[wage | education=x, controls=w0]
binsreg wage education controls
```

---

## Binary Outcomes: binslogit / binsprobit

```stata
binslogit depvar xvar [controls] [, nolink options]
binsprobit depvar xvar [controls] [, nolink options]
```

- `nolink` - Plot fitted probabilities instead of logit/probit index
- All other options same as `binsreg`

```stata
* Employment probability by age
binslogit employed age education, nolink ci(3,3)
binsprobit employed age education, nolink cb(3,3)
```

---

## Quantile Regression: binsqreg

```stata
binsqreg depvar xvar [controls] [, quantile(#) options]
```

- `quantile(#)` - Quantile to estimate (default: 0.5)
- Bootstrap recommended for inference: `vce(bootstrap, reps(100))`

```stata
binsqreg wage education, quantile(0.5) ci(3,3)
binsqreg wage education experience, quantile(0.75) ci(3,3) vce(bootstrap, reps(100))
```

---

## Hypothesis Testing: binstest

```stata
binstest depvar xvar [controls] [, test_options]
```

**Test Options:**
- `testmodelpoly(#)` - Test polynomial specification (1=linear, 2=quadratic, ...)
- `testshaper(#)` - Shape restriction: 0 for >= (increasing), 1 for <= (decreasing)
- `testshapel(#)` - Lower bound on derivative
- `deriv(#)` - Derivative order to test
- `lp(#|inf)` - Test metric (inf=supremum default, 2=L2, 1=L1)
- `estmethod(reg|logit|probit|qreg #)` - Estimation method

```stata
* Test linearity
binstest wage education, testmodelpoly(1)

* Test quadratic
binstest wage education, testmodelpoly(2)

* Test monotonicity (increasing)
binstest wage education, testshaper(0) deriv(1)

* Test concavity (decreasing returns)
binstest wage education, testshaper(1) deriv(2)

* Test with logit model
binstest employed age, estmethod(logit) testshaper(0) deriv(1)

* Test at specific quantile
binstest wage education, estmethod(qreg 0.5) testmodelpoly(1)
```

---

## Pairwise Comparison: binspwc

```stata
binspwc depvar xvar [controls], by(groupvar) [options]
```

- `by(groupvar)` - Required grouping variable
- `estmethod(method)` - Estimation method
- `pwc(#)` - Comparison type

```stata
binspwc wage education, by(gender)
binspwc wage education experience, by(union_status) vce(robust)
binspwc wage education, by(gender) estmethod(qreg 0.4)
```

---

## Bin Selection: binsregselect

```stata
binsregselect depvar xvar [controls] [, options]
```

- `binsmethod(dpi|rot)` - Selection method
- `binspos(es|qs)` - Bin positioning
- `pselect(# #)` - Range of polynomial degrees to search
- `sselect(# #)` - Range of smoothness degrees

```stata
binsregselect wage education
binsregselect wage education, binspos(es) pselect(1/4)
```

---

## Practical Examples

### Wage-Education Relationship

```stata
sysuse nlsw88, clear
rename grade education
rename ttl_exp experience

* Basic binscatter
binsreg wage education

* With controls, CI, and polynomial overlay
binsreg wage education experience age, ///
    dots(0,0) line(3,3) ci(3,3) polyreg(2) ///
    title("Wage-Education Relationship") ///
    xtitle("Years of Education") ytitle("Hourly Wage ($)")

* Test linearity
binstest wage education experience age, testmodelpoly(1)

* Test monotonicity
binstest wage education experience age, testshaper(0) deriv(1)
```

### Group Comparison

```stata
* Visual comparison by union status
binsreg wage education experience, ///
    by(union) dots(0,0) line(3,3) ci(3,3) ///
    legend(order(1 "Non-Union" 2 "Union"))

* Formal pairwise test
binspwc wage education experience, by(union) vce(robust)
```

### Binary Outcome

```stata
* Logit binscatter (probability scale)
binslogit employed age education, nolink ci(3,3) ///
    title("Employment Probability by Age") ytitle("Pr(Employed)")

* Test monotonicity
binstest employed age education, estmethod(logit) testshaper(1) deriv(1)
```

### Quantile Comparison

```stata
binsqreg wage education experience, quantile(0.25) name(q25, replace)
binsqreg wage education experience, quantile(0.75) name(q75, replace)
graph combine q25 q75, title("Wage Distribution by Education")

* Test linearity at multiple quantiles
foreach q in 0.25 0.5 0.75 {
    display "Testing linearity at quantile `q'"
    binstest wage education experience, estmethod(qreg `q') testmodelpoly(1)
}
```

### Specification Testing Workflow

```stata
* Step 1: Visualize with linear overlay
binsreg wage education experience age, ///
    line(3,3) cb(3,3) polyreg(1)

* Step 2: Test linearity
binstest wage education experience age, testmodelpoly(1)
local pval_linear = r(p_val)

* Step 3: If rejected, test quadratic
if `pval_linear' < 0.05 {
    binstest wage education experience age, testmodelpoly(2)
}

* Step 4: Test economic shape restrictions
binstest wage education experience age, testshaper(0) deriv(1)  // Increasing
binstest wage education experience age, testshaper(1) deriv(2)  // Concave
```

### Derivative Plot

```stata
* Marginal return to education
binsreg wage education, deriv(1) line(2,2) cb(2,2) ///
    title("Marginal Return to Education")
```

### Saved Data for Custom Plotting

```stata
binsreg wage education, savedata(bindata) replace
use bindata, clear
* Variables: dots_x, dots_fit (bin-mean dots), poly_x, poly_fit (polynomial),
*            CI_l, CI_r (pointwise CI), CB_l, CB_r (uniform CB)
* With by(): each group gets suffix: dots_x_1, dots_x_2, etc.
twoway (scatter dots_fit dots_x) ///
       (rcap CI_l CI_r dots_x), ///
       title("Custom Binscatter")
```

### Publication-Ready Plot

```stata
binsreg wage education experience age, ///
    nbins(20) dots(0,0) line(3,3) ///
    ci(3,3) cb(3,3) polyreg(2) ///
    title("Returns to Education", size(medium)) ///
    xtitle("Years of Education", size(small)) ///
    ytitle("Hourly Wage ($)", size(small)) ///
    note("95% CI and CB shown. Quadratic overlay.", size(vsmall)) ///
    graphregion(color(white)) scheme(s1color) ///
    saveplot("figure1_wage_education.pdf") replace
```

---

## Migration from Traditional binscatter

```stata
* OLD (binscatter):
binscatter wage education, nquantiles(20) ///
    controls(experience age) absorb(state)

* NEW (binsreg) -- with proper covariate adjustment and inference:
binsreg wage education experience age, ///
    nbins(20) binspos(qs) absorb(state) ci(3,3) cb(3,3)

* Or with automatic bin selection:
binsreg wage education experience age, absorb(state) ci(3,3)
```

| Feature | binscatter | binsreg |
|---------|------------|---------|
| Bin selection | Manual (`nquantiles`) | Automatic or manual (`nbins`) |
| Covariates | Residualization (`controls`) | Direct adjustment (listed after xvar) |
| Inference | None | CI/CB |
| Testing | Visual only | Formal tests (`binstest`) |
| Estimators | OLS only | OLS, logit, probit, quantile |

---

## References

**Cattaneo, M. D., Crump, R. K., Farrell, M. H., and Feng, Y. (2024).** "On Binscatter." *American Economic Review*, 114(5): 1488-1514.

**Cattaneo, M. D., Crump, R. K., Farrell, M. H., and Feng, Y. (2025).** "Binscatter Regressions." *The Stata Journal* (forthcoming). arXiv:2407.15276.

- Website: [https://nppackages.github.io/binsreg/](https://nppackages.github.io/binsreg/)
- GitHub: [https://github.com/nppackages/binsreg](https://github.com/nppackages/binsreg)
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 323kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 323kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 323kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall