/stata

name: stata
description: >
  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.

Stata Skill

You have access to comprehensive Stata reference files. **Do not load all files.** Read only the 1-3 files relevant to the user's current task using the routing table below.

---

Critical Gotchas

These are Stata-specific pitfalls that lead to silent bugs. Internalize these before writing any code.

Missing Values Sort to +Infinity

Stata's `.` (and `.a`-`.z`) are **greater than all numbers**.

* WRONG — includes observations where income is missing!
gen high_income = (income > 50000)

* RIGHT
gen high_income = (income > 50000) if !missing(income)

* WRONG — missing ages appear in this list
list if age > 60

* RIGHT
list if age > 60 & !missing(age)

`=` vs `==`

`=` is assignment; `==` is comparison. Mixing them up is a syntax error or silent bug.

* WRONG — syntax error
gen employed = 1 if status = 1

* RIGHT
gen employed = 1 if status == 1

Local Macro Syntax

Locals use `` `name' `` (backtick + single-quote). Globals use `$name` or `${name}`. Forgetting the closing quote is the #1 macro bug.

local controls "age education income"
regress wage `controls'        // correct
regress wage `controls         // WRONG — missing closing quote
regress wage 'controls'        // WRONG — wrong quote characters

`by` Requires Prior Sort (Use `bysort`)

* WRONG — error if data not sorted by id
by id: gen first = (_n == 1)

* RIGHT — bysort sorts automatically
bysort id: gen first = (_n == 1)

* Also RIGHT — explicit sort
sort id
by id: gen first = (_n == 1)

Factor Variable Notation (`i.` and `c.`)

Use `i.` for categorical, `c.` for continuous. Omitting `i.` treats categories as continuous.

* WRONG — treats race as continuous (e.g., race=3 has 3x effect of race=1)
regress wage race education

* RIGHT — creates dummies automatically
regress wage i.race education

* Interactions
regress wage i.race##c.education    // full interaction
regress wage i.race#c.education     // interaction only (no main effects)

`generate` vs `replace`

`generate` creates new variables; `replace` modifies existing ones. Using `generate` on an existing variable name is an error.

gen x = 1
gen x = 2          // ERROR: x already defined
replace x = 2      // correct

String Comparison Is Case-Sensitive

* May miss "Male", "MALE", etc.
keep if gender == "male"

* Safer
keep if lower(gender) == "male"

`merge` Always Check `_merge`

Never skip `tab _merge` — it costs nothing and is the only diagnostic you get when `assert` fails.

merge 1:1 id using other.dta
tab _merge                      // ALWAYS tab before assert
assert _merge == 3              // fails silently without tab output
drop _merge

`preserve` / `restore` + `tempfile` for Collapse-Merge-Back

The standard pattern for computing group stats and merging them onto the original data:

tempfile stats
preserve
collapse (mean) avg_x=x, by(group)
save `stats'
restore
merge m:1 group using `stats'
tab _merge
assert _merge == 3
drop _merge

For simple group means, `bysort group: egen avg_x = mean(x)` avoids the round-trip entirely.

Weights Are Not Interchangeable

• `fweight` — frequency weights (replication)
• `aweight` — analytic/regression weights (inverse variance)
• `pweight` — probability/sampling weights (survey data, implies robust SE)
• `iweight` — importance weights (rarely used)

`capture` Swallows Errors

capture some_command
if _rc != 0 {
    di as error "Failed with code: " _rc
    exit _rc
}

Line Continuation Uses `///`

regress y x1 x2 x3 ///
    x4 x5 x6, ///
    vce(robust)

Stored Results: `r()` vs `e()` vs `s()`

• `r()` — r-class commands (summarize, tabulate, etc.)
• `e()` — e-class commands (estimation: regress, logit, etc.)
• `s()` — s-class commands (parsing)

A new estimation command **overwrites** previous `e()` results. Store them first:

regress y x1 x2
estimates store model1

---

Running Stata from the Command Line

Claude can execute Stata code by running `.do` files in batch mode from the terminal. This is how to run Stata non-interactively.

Finding the Stata Binary

Stata on macOS is a `.app` bundle. The actual binary is inside it. Common locations:

# Stata 18 / StataNow (most common)
/Applications/Stata/StataMP.app/Contents/MacOS/stata-mp
/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp

# Other editions (SE, BE)
/Applications/Stata/StataSE.app/Contents/MacOS/stata-se
/Applications/Stata/StataBE.app/Contents/MacOS/stata-be

If Stata isn't on `$PATH`, find it with: `mdfind -name "stata-mp" | grep MacOS`

Batch Mode (`-b`)

# Run a .do file in batch mode — output goes to <filename>.log
/Applications/Stata/StataMP.app/Contents/MacOS/stata-mp -b do analysis.do

# If stata-mp is on PATH (e.g., via symlink or alias):
stata-mp -b do analysis.do

• `-b` = batch mode (non-interactive, no GUI)
• Output (everything Stata would display) is written to `analysis.log` in the working directory
• Exit code is 0 on success, non-zero on error
• The log file contains all output, including error messages — check it after execution

Running Inline Stata Code

To run a quick Stata snippet without creating a `.do` file:

# Write a temp .do file and run it
cat > /tmp/stata_run.do << 'EOF'
sysuse auto, clear
summarize price mpg
EOF
stata-mp -b do /tmp/stata_run.do
cat /tmp/stata_run.log

Checking Results

# Check if it succeeded
stata-mp -b do tests/run_tests.do && echo "SUCCESS" || echo "FAILED"

# Search