An Introduction to Macros in Stata

A macro in Stata is a really important tool for automation. If you are at all familiar with programming, a macro in Stata is what might be referred to as an argument or a variable or a parameter in another programming language.

If you aren't familiar with programming, I'm going to break this down into its core concept using a simple example.

A Macro Example

The current GDP for Australia is approximately 1,300,000,000,000. If I wanted to use that number in some calculations or analysis in Stata I would have to carefully count out all the zeros every time I input the number. That would become tedious very quickly. However, I can simplify this problem by creating a special word that I save Australia's GDP to. In this example let's say my special word is ausgdp. Now every time I want to use Australia's GDP in a calculation, all I have to do is input the word ausgdp instead of the full number. Stata will then automatically insert Australia's GDP whenever the word ausgdp is used.

Referencing a Macro

It is important that Stata is able to determine when a word is a macro. In order to indicate to Stata that we are using a macro we use special grammar. There are two types of macros in Stata, and they have different grammar associated with them.

To indicate a local macro we start with a ` (this is a grave, located on the ~ key, left of the 1 key on your keyboard). We then insert our special word, and end with a ' (an apostrophe, located on the double-quotes key, left of the Enter key on your keyboard). For example:

`ausgdp'

NOTE: It is important to remember that to begin a local macro you use the grave and not the apostrophe.

To indicate a global macro, we start with a $ (dollar symbol, located on the 4 key on your keyboard). We then insert our special word. For example:

$ausgdp

Defining a Macro

In order for Stata to insert the correct information when a macro is given, you first need to define your macro - i.e. tell Stata what information the macro should contain. Continuing with our GDP example, to define ausgdp as a local macro:

local ausgdp = 1300000000000

And to define ausgdp as a global macro:

global ausgdp = 1300000000000

You can also save a string of text to a macro instead of a number. This means that the text you saved will be inserted when you reference the macro in Stata. For example:

local ausgdp = "Australia's Gross Domestic Product"

OR

global ausgdp = "Australia's Gross Domestic Product"

When saving a string of text to a Stata macro, you need to use double-quotes, as shown in the above examples. By default only the text will be inserted when the macro is referenced, the double-quotes are ignored. It is possible to have special characters like double-quotes inserted, but this requires some explicit grammar that we will not cover in this introduction.

Local vs Global Macros

The only difference between a local and a global macro is how the macro persists within Stata. If a local macro is created within a do-file or program, it will be dropped by Stata when the do-file or program completes. This means once the do-file or program is finished, the information contained in any local macros can no longer be referenced. If a global macro is created within a do-file or program, it can still be referenced once that do-file or program completes. Both local and global macros that are defined interactively while using Stata will persist until you close Stata.

It is important to note that neither local nor global macros persist between Stata sessions. If you close and then re-open Stata, any macros defined in your previous session can no longer be referenced. However, it is possible to add the creation of global macros to your profile.do. By doing this, you can create a global macro that persists across Stata sessions as it is re-defined every time Stata is opened. For more information on what a profile.do is and how to use it, check out this article.

Finally, you should be aware that because local and global macros are referenced differently, it is possible to assign two different bits of information to the same special word. I strongly advise you not to do this, however it is important to understand the two are not interchangeable. If you define your macro as a local then it cannot be referenced using the global $ dollar-sign grammar, and vice-versa.

An Interactive Example of Macros in Stata

I am going to perform a quick calculation in Stata using the display command to demonstrate the use of macros. In the command pane:

local ausgdp = 1300000000000
global auspop = 26068792
display `ausgdp'/$auspop

This displays the number 49868.057, which I can round up to $49,868.06 and is Australia's current GDP per capita (approximately).

---

In order to perform more advanced automation in Stata it is important to understand how macros work. They are used in loops such as forvalues{} or foreach{} which can greatly speed up repetitive analysis or reporting. They can also be used as positional arguments with Stata do-files. This allows you to create more flexible do-files that can be applied across multiple datasets and shared more widely with colleagues and others.

If you are interested in learning more I highly recommend the Stata Press book An Introduction to Stata Programming, 2nd Edition. It is a comprehensive text-book that introduces do-file automation before progressing to more advanced programming with ado files.