13 Using the Do-file Editor—automating Stata

13 Using the Do-ﬁle Editor—automating Stata

The Do-ﬁle Editor

Stata comes with an integrated text editor called the Do-ﬁle Editor, which can be used for many

tasks. It gets its name from the term do-ﬁle, which is a ﬁle containing a list of commands for Stata

to run (called a batch ﬁle or a script in other settings). See [U] 16 Do-ﬁles for more information.

Although the Do-ﬁle Editor has advanced features that can help in writing such ﬁles, it can also be

used to build up a series of commands that can then be submitted to Stata all at once. This feature

can be handy when writing a loop to process multiple variables in a similar fashion or when doing

complex, repetitive tasks interactively.

To get the most from this chapter, you should work through it at your computer. Start by opening

the Do-ﬁle Editor, either by clicking on the Do-ﬁle Editor button, , or by typing doedit in the

Command window and pressing Return.

The Do-ﬁle Editor toolbar

The Do-ﬁle Editor has seven buttons. Many of the buttons share a similar purpose with their

look-alikes in the main Stata toolbar.

If you ever forget what a button does, hover the mouse pointer over a button, and a tooltip will

appear.

Open: Open a do-ﬁle from disk in a new tab in the Do-ﬁle Editor.

Save: Save the current ﬁle to disk.

Print: Print the contents of the Do-ﬁle Editor.

Find: Open the Find bar for ﬁnding text.

Show: Toggle display of invisible characters.

Zoom: Change the display size of the text.

Execute (do): Run the commands in the do-ﬁle, showing all commands and their

output. If text is highlighted, the button becomes the Execute selection (do) button

and will run only the selected lines, showing all output. We will refer to this as the

Do button. If you click on the arrow next to the Do button, you will see further

choices for what gets done.

2 [ GSM ] 13 Using the Do-ﬁle Editor—automating Stata

Using the Do-ﬁle Editor

Suppose that we would like to analyze fuel usage for 1978 automobiles in a manner similar to

what we did in [GSM] 1 Introducing Stata—sample session. We know that we will be issuing many

commands to Stata during our analysis and that we want to be able to reproduce our work later

without having to type each command again.

We can do this easily in Stata: simply save a text ﬁle containing the commands. When that is

done, we can tell Stata to run the ﬁle and execute each command in sequence. Such a ﬁle is known

as a Stata do-ﬁle; see [U] 16 Do-ﬁles.

To analyze fuel usage of 1978 automobiles, we would like to create a new variable containing

gallons per mile. We would like to see how that variable changes in relation to vehicle weight for

both domestic and imported cars. Performing a regression with our new variable would be a good

ﬁrst step.

To get started, click on the Do-ﬁle Editor button to open the Do-ﬁle Editor. After the Do-ﬁle

Editor opens, type the commands below into the Do-ﬁle Editor. Purposely misspell the name of the

foreign variable on the ﬁfth line. (We are intentionally making some common mistakes and then

pointing you to the solutions. This will save you time later.)

* an example do-file

sysuse auto

generate gp100m = 100/mpg

label var gp100m "Gallons per 100 miles"

regress gp100m weight foreing

Here is what your Do-ﬁle Editor should look like now:

You will notice that the color of the text changes as you type. The different colors are examples

of the Do-ﬁle Editor’s syntax highlighting. The colors and text properties of the syntax elements can

be changed by right-clicking in the Do-ﬁle Editor, selecting Preferences... and then clicking on the

Syntax highlighting tab in the resulting window. You can also deﬁne your own list of keywords for

syntax highlighting.

Syntax highlighting extends beyond highlighting Stata commands. You can switch the syntax

highlighting from Stata by clicking on the dropdown menu in the lower-right corner of the Do-ﬁle

Editor and choosing the language you would like. This dropdown menu includes a selection for

Markdown because Stata can process Markdown to create dynamic documents. See [RPT] dyndoc

for more information. This menu also contains selections for Python and Java because Stata has both

Python integration and Java integration. See [P] PyStata integration and [P] Java integration for

more information. Stata will default to the proper language based on the extension of the ﬁle you

are editing, but if the ﬁle has not been saved yet, you will need to tell it what language to choose.

Also note that if you pause brieﬂy as you type, the Do-ﬁle Editor will allow autocompletion of

words that are already in the do-ﬁle and, in StataNow, autocompletion of variable names. Once the

suggestions appear, more typing will narrow down the possibilities. You can navigate the suggestions

[ GSM ] 13 Using the Do-ﬁle Editor—automating Stata 3

using the up- and down-arrow keys or keep typing to narrow them to a single word. Once you have

the word you like, pressing Return will place the word in your do-ﬁle.

Click on the Do button, , to execute the commands. Stata executes the commands in sequence,

and the results appear in the Results window:

 

(1978 automobile data)

variable not found

r(111);

end of do-file

 

The do "/tmp/. . . " command is how Stata executes the commands in the Do-ﬁle Editor. Stata

saves the commands from a do-ﬁle with unsaved changes to a temporary ﬁle and issues the do

command to execute them. Everything worked as planned until Stata saw the misspelled variable. The

ﬁrst three commands were executed, but an error was produced on the fourth. Stata does not know

of a variable named foreing. We need to go back to the Do-ﬁle Editor and change the misspelled

variable name to foreign in the last line:

Click on the Do button again. Alas, Stata now fails on the ﬁrst line—it will not overwrite the

dataset in memory that we changed.

 

no; dataset in memory has changed since last saved

r(4);

end of do-file

 

We now have a choice for what we should do:

• We can put a clear command in our do-ﬁle as the very ﬁrst command. This automatically

clears out Stata’s memory before the do-ﬁle tries to load auto.dta. This is convenient but

dangerous because it defeats Stata’s protection against throwing away changes without warning.

• We can type a clear command in the Command window to manually clear the dataset and

then process the do-ﬁle again. This process can be aggravating when building a complicated

do-ﬁle.

4 [ GSM ] 13 Using the Do-ﬁle Editor—automating Stata

Here is some advice: Automatically clear Stata’s memory while debugging the do-ﬁle. Once the

do-ﬁle is in its ﬁnal form, decide the context in which it will be used. If it will be used in a highly

automated environment (such as when certifying), the do-ﬁle should still automatically clear Stata’s

memory. If it will be used rarely, do not clear Stata’s memory. This decision will save much heartache.

We will add a clear option to the sysuse command to automatically clear the dataset in Stata’s

memory before the do-ﬁle runs:

The do-ﬁle now runs well, as clicking on the Do button shows:

 

(1978 automobile data)

Source SS df MS Number of obs =

F( 2, 71) =

Model Prob > F =

Residual R-squared =

Adj R-squared =

Total Root MSE =

p100m Coefficient Std. err. t P>|t| [95% conf. interval]

weight

foreign

_cons

end of do-file

 

You might want to select File > Save as... to save this do-ﬁle while the Do-ﬁle Editor is in front.

Later, you could select File > Open... to open it and then add more commands as you move forward

with your analysis. By saving the commands of your analysis in a do-ﬁle as you go, you do not have

to worry about retyping them with each new Stata session. Think hard about removing the clear

option from the ﬁrst command.

After you have saved your do-ﬁle, you can execute the commands it contains by typing do ﬁlename,

where the ﬁlename is the name of your do-ﬁle.

[ GSM ] 13 Using the Do-ﬁle Editor—automating Stata 5

The File menu

When the Do-ﬁle Editor is in front, the File menu’s items apply to do-ﬁles. You may choose any

of these menu items: create a New > Do-ﬁle, Open... an existing ﬁle, Save the current ﬁle, save the

current ﬁle under a new name with Save as..., or Print the current ﬁle. There are also buttons on the

Do-ﬁle Editor’s toolbar that correspond to these features.

Finally, you can create a New > Project... to keep track of collections of ﬁles used in a project.

These can be do-ﬁles, data ﬁles, graph ﬁles, or any other ﬁles you like. For more information on the

Project Manager, see [P] Project Manager.

The Edit menu

The Edit menu of the Do-ﬁle Editor includes the standard Undo, Redo, Cut, Copy, Paste, and

Find capabilities. There are several other Edit menu features that you might ﬁnd useful:

• You can select Insert ﬁle... to insert the contents of another ﬁle at the current cursor position

in the Do-ﬁle Editor.

• You can select the current line with Select line.

• You can delete the current line with Delete line.

• Find > Go to line... will allow you to jump to a speciﬁc line number. The line numbers are

displayed at the left and the lower-left of the Do-ﬁle Editor window.

• Advanced leads to a submenu with some programmer’s friends:

– Shift right indents the selection by one tab.

– Shift left unindents the selection by one tab.

– Re-indent indents the selection according to its nesting within blocks and programs.

– Toggle comment toggles //-style comments at the start of the selected lines.

– Add block comment puts a /* before and a */ after the selected region, commenting it

out.

– Remove block comment undoes the above.

– Make selection uppercase converts the selection to all capital letters.

– Make selection lowercase converts the selection to all lowercase letters.

– Complete word attempts to complete the current word based on words that are already

in the do-ﬁle. If there are multiple possibilities, all will be shown. You can either pick

the completion you would like or keep typing to narrow the choices.

– Convert to UTF-8... converts the current ﬁle to UTF-8 encoding.

– Convert line endings to macOS/Unix format (\n) converts the line endings for the current

ﬁle to macOS/Unix format.

– Convert line endings to Windows format (\r\n) converts the line endings for the current

ﬁle to Windows format.

– Convert tabs to spaces replaces any tab characters with spaces, leaving the spacing as

it currently appears.

– Convert leading spaces to tabs converts any spaces at the start of lines to tab characters.

The number of spaces per tab is determined by a preference setting.

– Convert all spaces to tabs converts spaces to tab characters wherever possible. The

number of spaces per tab is determined by a preference setting.

– Convert Unicode spaces and curly quotes to ASCII converts spaces and curly quotes

in Unicode to ASCII encoding.

6 [ GSM ] 13 Using the Do-ﬁle Editor—automating Stata

Matching and balancing of parentheses ( ), braces { }, and brackets [ ] are also available from

the Edit menu. When you select Edit > Find > Match brace, the Do-ﬁle Editor looks at the character

immediately to the left and right of the cursor. If either is one of the characters that the editor can

match, the editor will ﬁnd the matching character and place the cursor immediately in front of it. If

there is no match, the menu item will be inactive.

When you select Edit > Find > Balance braces, the Do-ﬁle Editor looks to the left and right

of the current cursor position or selection and creates a selection that includes the narrowest level

of matching characters. If you select Balance braces again, the editor will expand the selection to

include the next level of matching characters. If there is no match, the cursor will not move. Balancing

braces is useful for working with complicated expressions or blocks of code deﬁned by loops or if

commands. See [P] foreach, [P] forvalues, [P] while, and [P] if for more information.

Balance braces is easier to explain with an example. Type (now (is the) time) in the Do-ﬁle

Editor. Place the cursor between the words is and the. Select Edit > Find > Balance braces. The

Do-ﬁle Editor will select (is the). If you select Balance braces again, the Do-ﬁle Editor will select

(now (is the) time).

Text in Stata strings can include Unicode characters and is encoded as UTF-8 (see [U] 12.4.2 Handling

Unicode strings). However, you may have do-ﬁles, ado-ﬁles, or other text ﬁles that you used with

Stata 13 or earlier, and those ﬁles contain characters other than plain ASCII such as accented characters,

Chinese, Japanese, or Korean (CJK) characters, Cyrillic characters, and the like. If you open a ﬁle

that is not encoded in UTF-8, Stata prompts you to specify the encoding for the ﬁle so that it can

convert the ﬁle to UTF-8. If you cancel the conversion or choose the wrong encoding, you can try the

conversion again later using Convert to UTF-8. The conversion to UTF-8 can be undone by using

Edit > Undo and is not permanent until you save the do-ﬁle. For Stata datasets with characters

not encoded in UTF-8 or for bulk conversion of multiple Stata ﬁles, you should use the unicode

translate command.

Editing tip: You can split the Do-ﬁle Editor window vertically by clicking on the Split window

button in the status bar . This is useful for looking at two widely separated places in a ﬁle at the

same time. To go back to a single pane view, click on the close button in either of the split panes.

The View > Do-ﬁle Editor menu

You have already learned about the Do button. Selecting View > Do-ﬁle Editor > Execute (do)

is equivalent to clicking on the Execute (do) button.

Selecting View > Do-ﬁle Editor > Execute (do) from top will send all the commands from the

ﬁrst line to the current line to the Command window. This method is a quick way to run a part of a

do-ﬁle.

Selecting View > Do-ﬁle Editor > Execute (do) to bottom will send all the commands from the

current line through the end of the contents of the Do-ﬁle Editor to the Command window. This

method is a quick way to run a part of a do-ﬁle.

Selecting View > Do-ﬁle Editor > Execute quietly (run) is equivalent to View > Do-ﬁle Editor

> Execute (do), but the commands will be executed quietly; that is, no output will be displayed

in the Command window.

Selecting View > Do-ﬁle Editor > Execute (do) line will send all the commands from the current

line to the Command window. The cursor will then automatically advance to the next executable line,

bypassing empty lines and comments. This method is an easy way to run a do-ﬁle line by line.

[ GSM ] 13 Using the Do-ﬁle Editor—automating Stata 7

Selecting View > Do-ﬁle Editor > Execute (include) is similar to clicking on the Execute (do)

button with one major difference: local macros deﬁned in the current session can be expanded in the

commands being executed.

Do is equivalent to Stata’s do command, whereas Execute (include) is equivalent to Stata’s

include command. See [U] 16 Do-ﬁles for a complete discussion.

You can also preview ﬁles in the Viewer by selecting View > Do-ﬁle Editor > Show ﬁle in Viewer.

This feature is useful when working with ﬁles that use Stata’s SMCL tags, such as when writing help

ﬁles or editing log ﬁles.

Saving interactive commands from Stata as a do-ﬁle

While working interactively with Stata, you might decide that you would like to rerun the last

several commands that you typed interactively. From the History window, you can send highlighted

commands or even the entire contents to the Do-ﬁle Editor. You can also save commands as a do-ﬁle

and open that ﬁle in the Do-ﬁle Editor. You can copy a command from a dialog (rather than submit

it) and paste it into the Do-ﬁle Editor. See [GSM] 6 Using the Data Editor for details. Also see

[R] log for information on the cmdlog command, which allows you to log all commands that you

type in Stata to a do-ﬁle.

Navigating your do-ﬁle

When you work with long ﬁles, bookmarks allow you to easily navigate through your do-ﬁle. By

placing a bookmark before important sections in your do-ﬁle, you can return to those sections more

easily later. You can add a bookmark line by using Edit > Find > Toggle bookmark or by manually

typing a line beginning with a special comment, **#. All other text on the rest of the line is treated

as the title of the bookmark. You cannot have ado code on the same line as the bookmark comment,

or the bookmark comment will be ignored. You can also add a bookmark with the special comment

//#. This bookmark comment may be preferable to use over **# because it’s also valid for both

Mata and Java.

You can move between bookmarks using the options in the Edit menu or the Navigation Control.

The Navigation Control of the Do-ﬁle Editor allows you to move between bookmarks as well as

programs and Java and Python code blocks that you have deﬁned in your do-ﬁle. When you select a

program or a bookmark from the Navigation Control, you will jump directly to the position of that

program or bookmark in your do-ﬁle.

8 [ GSM ] 13 Using the Do-ﬁle Editor—automating Stata

You can increase the level of indentation for a bookmark’s label in the Navigation Control by

adding # to the bookmark comment. For example, bookmark comment **## Bookmark 2 will be

indented one level more than bookmark comment **# Bookmark 1.

Bookmarks can also be removed with the Toggle bookmark option in the Edit menu as well

as simply deleting the line. You can also add and remove bookmarks by clicking in the bookmark

margin next to the line you want to add the bookmark before. When you add a bookmark line, the

bookmark icon will be added in the bookmark margin to make it more visibly obvious for you while

scrolling.

Projects

For advanced users managing many ﬁles as part of a project, Stata has a Project Manager that

uses the Do-ﬁle Editor. For more information on the Project Manager, see [P] Project Manager.

Auto backup

The Do-ﬁle Editor now creates a backup ﬁle whenever it opens a document or creates a new one.

When an existing document is opened, Stata creates a backup ﬁle of a document that is saved to disk

in the same directory using the existing document’s ﬁlename preﬁxed with

and with the extension

.stswp. When you edit a new and unsaved document, it saves the backup ﬁle to the temp directory.

When a document is closed, the backup ﬁle is deleted. However, if Stata does not exit cleanly because

of a power outage or a computer crash, the backup ﬁle is left behind.

By default, Stata periodically backs up the document every 4 seconds if an edit has been made

or after an addition or a deletion of 200 characters or more. The time interval can be changed in the

Do-ﬁle Editor’s advanced settings, and the backup feature can also be turned off.

[ GSM ] 13 Using the Do-ﬁle Editor—automating Stata 9

When you attempt to open a document in the Do-ﬁle Editor, it ﬁrst checks for the existence of a

backup ﬁle. If a backup ﬁle is found, the Do-ﬁle Editor prompts you that a backup ﬁle exists and asks

if you want to recover the backup ﬁle, open the original document, or cancel. We will discuss the

options in reverse order. Choosing to cancel will cancel opening the document and leave the backup

ﬁle on disk. If you choose to open the original document, the original document is opened in the

Do-ﬁle Editor, and the backup ﬁle is deleted from disk. If you choose to recover the backup ﬁle, the

backup ﬁle is opened as a new and unsaved document in the Do-ﬁle Editor with its default ﬁlename

set to the original ﬁlename and the string Recovered appended to the ﬁlename. The backup ﬁle is

deleted from disk. You can keep the recovered document by saving it to disk either as a new ﬁle

or by overwriting the original document, or you can disregard the changes by closing the document

without saving it.

Adding user-deﬁned keywords for syntax highlighting

You can create a text ﬁle containing keywords that Stata will use for syntax highlighting. The text

ﬁle must be named stata-userkeywords.txt and contain a list of keywords that can be separated by any

combination of spaces or tabs and can be placed on separate lines. Keywords must follow Stata’s rules

for valid command names. Comments are not supported. Any keywords that are invalid command

names are ignored. There are no limits on the number of keywords you can deﬁne. However, you

must be mindful of the fact that Stata has to search across all keywords when syntax-highlighting a

document, so a very large dictionary of keywords can affect performance in the Do-ﬁle Editor. Stata

maintains a dictionary of unique keywords, so repeated instances of a keyword are ignored.

Stata searches for both a global keywords ﬁle and a local keywords ﬁle; if both ﬁles exist, then their

dictionaries of keywords are merged. The global keywords ﬁle must be saved in the Stata directory.

This allows the global keywords ﬁle to be shared with multiple users without requiring each user to

have a copy. You can also create your own local keywords ﬁle, which must be saved to your home

directory. Stata for Mac users can also save their local keywords ﬁle to the Stata folder located within

their Documents folder.

Stata reads the keywords ﬁles when it launches. Changes to the keywords ﬁles while Stata is

running require Stata to be restarted to take effect.

10 [ GSM ] 13 Using the Do-ﬁle Editor—automating Stata

Stata, Stata Press, and Mata are registered trademarks of StataCorp LLC. Stata and

Stata Press are registered trademarks with the World Intellectual Property Organization

of the United Nations. StataNow and NetCourseNow are trademarks of StataCorp

LLC. Other brand and product names are registered trademarks or trademarks of their

respective companies. Copyright

 1985–2023 StataCorp LLC, College Station, TX,

For suggested citations, see the FAQ on citing Stata documentation.