Workflow
2026-02-2811 min read

Stata Macros: local, global, and Extended Functions Explained

Macros are Stata's variable system for code. local vs global, backtick-apostrophe syntax, extended functions, and the patterns that make do-files readable.

Sytra Team
Research Engineering Team, Sytra AI

Your do-file works in one section and fails in another because macros silently change scope.

You will control macro scope deliberately and stop losing hours to invisible expansion bugs.

All examples tested in Stata 18 SE. Compatible with Stata 15+.

Quick Answer

  1. Use local macros as default; reserve globals for explicit cross-script constants.
  2. Always print key macros during debugging.
  3. Use extended functions for robust varlist parsing.
  4. Avoid reusing macro names in nested scopes.

Use Macro Scope as a Reliability Tool

Define local macros for safe reusable templates

Locals reduce side effects by limiting visibility to the current do-file block or program. This makes scripts easier to reason about and review.

Pair locals with loops for concise, high-signal code.

If you are extending this pipeline, also review Export Regression Tables in Stata and Clustered Standard Errors in Stata.

macros-local.do
stata
1clear all
2set obs 1000
3gen wage = 20 + rnormal(0,3)
4gen education = 8 + floor(runiform()*10)
5gen experience = 18 + floor(runiform()*20)
6
7local controls "education experience"
8local depvar "wage"
9
10display "Running model: regress `depvar' `controls'"
11regress `depvar' `controls'
. display "Running model macro expansion"
Running model: regress wage education experience
๐Ÿ’กName locals semantically
Macro names like controls, depvar, and fe_spec are easier to maintain than one-letter macro names.

Use extended macro functions for dynamic varlists

Extended macro functions help build robust automation where variable sets change by sample or wave.

They are especially useful in large panel projects with evolving schemas.

macros-extended.do
stata
1clear all
2set obs 1000
3gen wage = 20 + rnormal(0,3)
4gen education = 8 + floor(runiform()*10)
5gen experience = 18 + floor(runiform()*20)
6
7local controls "education experience"
8local depvar "wage"
9
10display "Running model: regress `depvar' `controls'"
11regress `depvar' `controls'
12
13* ---- Section-specific continuation ----
14ds wage education experience
15local rawvars `r(varlist)'
16local nvars : word count `rawvars'
17display "Number of selected variables: `nvars'"
18
19* Build interaction-ready list
20local rhs ""
21foreach v of local rawvars {
22    local rhs "`rhs' c.`v'"
23}
24display "RHS spec: `rhs'"
. display "RHS spec macro expansion"
RHS spec:  c.wage c.education c.experience
โš ๏ธGlobal macros can leak across scripts
If a global macro from another script remains in memory, your current script may run with unintended settings.

Common Errors and Fixes

"invalid syntax"

Macro delimiters are malformed or expansion produced an empty fragment.

Display macro contents and verify backtick-apostrophe usage around macro names.

. display "'controls'"
invalid syntax
r(198);
This causes the error
wrong-way.do
stata
display "'controls'"
This is the fix
right-way.do
stata
display "`controls'"
error-fix.do
stata
1macro list
2local controls "education experience"
3display "`controls'"
. macro list
locals:
controls: education experience

Command Reference

local / global macro

Stata docs โ†’

Stores reusable text fragments for parameterized Stata commands.

local name "text" | global NAME "text"
localScope-limited macro definition
globalSession-wide macro definition
macro listDisplays defined macros
: word countExtended macro function example

How Sytra Handles This

Sytra can scaffold macro-safe do-files with local scoping defaults and explicit debugging printouts.

A direct natural-language prompt for this exact workflow:

sytra-prompt.txt
bash
Refactor my do-file to use local macros for dependent variable, controls, and fixed-effects spec, then print macro expansions and run regressions with safe scope.

Sytra catches these errors before you run.

Sytra can scaffold macro-safe do-files with local scoping defaults and explicit debugging printouts.

Join the Waitlist โ†’

FAQ

When should I use local instead of global macros?

Use local macros by default because they are scoped and safer. Use globals only for intentionally shared project-wide settings.

Why does my macro expand to empty text?

Likely scope mismatch or quoting error. Check backtick-apostrophe delimiters and whether macro exists in current scope.

Are extended macro functions worth using?

Yes for robust string manipulation of varlists and filenames, especially in reusable programs.

Related Guides

Written by Sytra Team
Research Engineering Team, Sytra AI

We build practical, reproducible workflows for Stata and R teams working on real empirical research pipelines.

#Stata#Macros#Programming#Workflow

Enjoyed this article?

Related Guides

Data Management14 min read

Stata Loops: foreach and forvalues Tutorial with 20 Practical Examples

Stop writing the same command 50 times. Here are 20 real-world loop patterns โ€” from basic iteration to nested loops and automated tables.

Workflow10 min read

Stata Factor Variables: i., c., ibn., and # Notation Explained

Factor variable notation is powerful but confusing. Here's when to use i., c., ibn., ##, and # โ€” with interaction examples and common mistakes.

Workflow8 min read

Stata preserve/restore and tempvar: Safe Data Manipulation Patterns

preserve and restore let you make destructive changes safely. tempvar and tempfile prevent namespace pollution. Here are the patterns every do-file needs.

Workflow8 min read

Publication-Ready Tables in Stata: esttab, outreg2, and collect

Stop manually formatting regression tables. Here's how to produce camera-ready LaTeX and Word tables from Stata using esttab, outreg2, and the new collect framework.

Workflow7 min read

How to Structure a Stata Project: Directory Layout, Naming, and Automation

A clean Stata project structure saves you hours. Here's the directory layout, naming conventions, and master .do file template used by top economics departments.

View all articles