Stata

---
name: stata
description: >-
  Use this skill whenever the user asks to run Stata commands, estimate econometric models,
  work with .dta files, run a .do file, generate Stata output, or do any statistical analysis
  where Stata is involved. Also trigger when the user mentions Stata variables, Stata syntax,
  or econometric tasks where Stata is the natural tool, including regressions, IV estimation,
  diff-in-diff, RDD, panel data, clustering, summary statistics, and margins. Stata runs
  through pystata on StataNow 19.5 BE; configure once with stata_setup, then drive everything
  with stata.run() and exchange data directly with pandas. Prefer this skill over subprocess
  calls or .do-file shelling for Stata work, including cases where the user does not say
  pystata.
---

# Stata Skill — pystata on StataNow 19.5 BE

Run Stata entirely through **pystata**, the official Python integration that
ships with Stata. Configure the session once, then issue every command — and
run every `.do` file — with `stata.run()`. Data crosses between Python and
Stata in memory through pandas, so there is no need to write intermediate
`.dta` files or read `.log` files unless the user wants them.

## The one rule that matters most

**Always execute Stata through pystata.** Both individual commands and entire
`.do` files go through `stata.run(...)`. Never launch `StataBE-64.exe` as a
subprocess and never run a do-file in batch mode — pystata keeps a single live
Stata session in the Python process, gives direct access to data and stored
results, and raises real Python exceptions on errors. Running a do-file is just
`stata.run('do "path/to/file.do"')`.

## Setup

This machine has **StataNow 19.5 BE** at `C:\Program Files\StataNow19`, and it
is already on PATH. `pystata` and `stata_setup` are installed for the system
Python (3.14). Basic Edition (BE) is the only licensed edition; `"se"` and
`"mp"` cannot be initialized.

Configure once per Python process:

```python
import stata_setup
stata_setup.config(r"C:\Program Files\StataNow19", "be")
from pystata import stata
```

For clean output without the StataCorp splash banner, drive `pystata.config`
directly instead:

```python
import sys
sys.path.insert(0, r"C:\Program Files\StataNow19\utilities")
import pystata
pystata.config.init("be", splash=False)
from pystata import stata
```

`config.init` can run only once per process; to start over, launch a fresh
Python process.

## Bundled helper (optional)

`scripts/stata_runner.py` removes the boilerplate: it bakes in the path and
edition, configures pystata lazily on first use, and wraps command-running,
output capture, and data exchange. Reach for it when a script makes several
Stata calls.

```python
import os
import sys
sys.path.insert(0, os.path.expanduser("~/.claude/skills/stata/scripts"))
import stata_runner as sr

sr.run("sysuse auto, clear")
log = sr.run("regress price mpg weight, robust", capture=True)
print(log)
print("R-squared:", sr.ereturn()["e(r2)"])
```

The plain three-line pattern above works just as well; the helper is a
convenience, not a requirement.

## Running commands

```python
stata.run("""
    sysuse auto, clear
    summarize price mpg weight
    regress price mpg weight i.foreign, robust
""")
```

`stata.run(cmd, quietly=False, echo=False)` accepts one command or several
newline-separated commands. `quietly=True` suppresses output while still
storing results; `echo=True` echoes each command line.

## Capturing output

Output prints to stdout by default. To capture it as a string, redirect stdout:

```python
import io, contextlib
buf = io.StringIO()
with contextlib.redirect_stdout(buf):
    stata.run("regress price mpg weight, robust")
log = buf.getvalue()
```

For a persistent `.log` on disk, tee through `set_output_file` — see
`references/pystata-api.md`.

## Error handling

A failing command **raises `SystemError`**, with a message ending in the Stata
return code such as `r(111);`. Catch it directly; there is no log to parse.

```python
try:
    stata.run("regress price nonexistent_var")
except SystemError as e:
    print("Stata error:", e)   # ".. variable nonexistent_var not found  r(111);"
```

Common codes: `r(111)` variable not found, `r(198)` syntax error, `r(601)`
file not found, `r(2000)` no observations.

## Data exchange with pandas

Move data in memory — no `.dta` files needed.

```python
import pandas as pd

# pandas -> Stata (replaces the dataset in memory)
stata.pdataframe_to_data(df, force=True)

# Stata -> pandas
df = stata.pdataframe_from_data()                 # whole dataset
prices = stata.pdataframe_from_data(var=["price", "mpg"])
labeled = stata.pdataframe_from_data(valuelabel=True)   # labels, not codes
```

Named **frames** let several datasets coexist:
`stata.pdataframe_to_frame(df, "aux")` and `stata.pdataframe_from_frame("aux")`.
`numpy` arrays have the parallel `nparray_*` calls. Full options are in
`references/pystata-api.md`.

If the user explicitly wants a `.dta` artifact, write one from Stata
(`save "out.dta", replace`) or from pandas (`df.to_stata("out.dta")`).

## Reading stored results

After any command the stored results are plain Python dicts:

```python
stata.run("summarize price", quietly=True)
r = stata.get_return()        # {'r(mean)': 6165.26, 'r(N)': 74.0, ...}

stata.run("regress price mpg weight", quietly=True)
e = stata.get_ereturn()       # {'e(N)': 74.0, 'e(r2)': 0.4996, 'e(b)': <ndarray>, ...}
```

Scalars are floats, macros are strings, and matrices (`e(b)`, `e(V)`) come back
as numpy arrays. For single values inside `python:` blocks, the bundled `sfi`
module exposes `Scalar`, `Macro`, `Matrix`, and `Data` — see the reference.

## Running an existing .do file

```python
stata.run('do "C:/path/to/analysis.do"')
```

Capture its output with the same `redirect_stdout` pattern if the user wants
the log. The do-file shares the live session, so any data or results it leaves
behind are immediately reachable from Python.

## BE edition constraints

StataNow 19.5 BE differs from SE/MP:

- **Variable ceiling of 2048** (`c(maxvar)`); SE allows 32,767 and MP up to
  120,000. Trim wide datasets with `keep`/`drop` before loading, or the load
  fails.
- **Single computational core** for estimation — BE has no MP parallelism, so
  very large models run slower.
- **`set matsize` is irrelevant** — it was removed in Stata 16; matrix size is
  managed automatically. Do not reintroduce it.
- Most commands run unchanged in BE; the practical limits are dataset width and
  speed, not command availability.

## Stata 19 capabilities (absent in the old Stata 16 setup)

Because this is Stata 19, several things the previous version could not do are
now available:

- **`didregress` / `xtdidregress`** for difference-in-differences (introduced in
  Stata 17). For the user's applied-micro work, still prefer `reghdfe` for
  high-dimensional or staggered-adoption designs; reach for modern estimators
  (`csdid`, `did_multiplegt`) when treatment timing varies.
- **`python:` blocks** inside do-files, with `sfi` for reading and writing Stata
  objects from Python.
- **Frames** with full Python integration, as shown above.

## Econometric workflow conventions

These reflect the user's applied-microeconomics practice. Follow them unless the
user says otherwise.

**Standard errors.** Default to robust (`, robust`) for cross-sectional
regressions. For panel data, cluster at the unit level (`, vce(cluster panelid)`).
Honor any clustering variable the user specifies. When the clustering level is
genuinely ambiguous, ask, because it is a consequential choice.

**Estimation.** For IV use `ivregress` and always report the first-stage
F-statistic (`estat firststage` after `ivregress 2sls`). For high-dimensional
fixed effects prefer `reghdfe` (`reghdfe y x, absorb(id year) cluster(id)`); for
simpler panels `xtreg` or `areg` are fine, and always `xtset` before `xtreg`.

**Output.** For side-by-side specifications use `esttab` from the `estout`
package; do not use `outreg2`. Display N and R-squared prominently.

**Data inspection.** On an unfamiliar dataset run `describe`, `summarize`, and
`codebook, compact` first, and flag missing values, string-encoded numerics, and
duplicate ID values.

User-written commands (`reghdfe`, `ftools`, `estout`, `csdid`) install with
`ssc install <pkg>` from inside a `stata.run(...)` call. Check availability with
`which <cmd>` before assuming a package is present.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `FileNotFoundError: ... shared library` on `init("se"/"mp")` | Only BE is installed/licensed | Initialize with `"be"` |
| `init` raises "already initialized" | `config.init` called twice in one process | Guard with `pystata.config.is_stata_initialized()`, or use a fresh process |
| `SystemError: ... r(111);` | Stata command error (here, variable not found) | Read the code in the message; fix the command |
| Output is empty when captured | Command run with `quietly=True` | Drop `quietly`, or read results via `get_return()`/`get_ereturn()` |
| Load fails on a wide dataset | Exceeds BE's 2048-variable ceiling | `keep`/`drop` columns before `pdataframe_to_data` |
| `unrecognized command` for a user package | Not installed | `stata.run("ssc install <pkg>")`, then retry |

## What this skill does not do

- It does not launch a Stata GUI window.
- It does not call `StataBE-64.exe` as a subprocess or run do-files in batch
  mode — everything goes through pystata's live session.
- It does not leave permanent `.do` files for the user to run by hand unless
  they ask for one.