Writing User-Written Stata Commands

Rosemarie Sandino

Technical Products Coordinator

RST, November 2021

Objectives

• Describe the difference between a coding task and programming a command
• Introduce the basic elements of a program
• Write a user-written command using syntax

Coding Best Practices

• What should we consider when we are writing code?
• Coding as problem solving
• Error control system

​

• Three Overarching Elements of Coding
• Functional
• Reproducible
• Documented

Coding vs. Programming

• Coding task: do file with inputs, outputs, purpose(s), applies to a certain situation
• Cleans data, creates variables, runs other do files, etc.
• Program: completely generalized code with a purpose
• Can apply to any data that fits the format it requires and create output
• Solves a general problem, not a problem with specific dataset

Coding vs. Programming

• Do file: Stata file that contains code
• Ado file: Stata file that contains a program
• Automatic do file
• Stata stores ado files in your adopath
• adopath command
• Store your own commands in personal or plus

​

When to Write a User-Written Command

• You are doing the same task three or more times
• Multiple people/projects have to do the same task over time
• Generalizable
• Easier if your code for this follows the best practices!

​

Designing a User-Written Command

• Map problem first into steps (inputs, outputs) and each step gets its own function
• Your program should not do everything, it should have a single purpose and do it well
• A subprogram can handle each specific task
• Get a simple working version first before adding bells and whistles

Pseudocode

• Turn high-level design into the format of code
• Describe all of the functions the computer will need to do, but don’t code it out directly
• Example for a t-test command:

// receive 2 variables from user

// confirm that variables 1 & 2 are numeric

// t-test variables

// display the p-value

Writing a User-Written Command

• Stata has commands that structure the inputs you want to allow in a program
• Two commands create the basic elements of a program
• Program
• Syntax

Program

• Program defines a command for Stata
• Program [define]
• End
• Program drop

​

• Allows for multiple commands in the same file

Structure of A Command

• How do we enter a command in Stata?
• name of command
• specifications
• variables, type of variables, if, filename, replace, force, etc.
• When we use the program command, we are telling Stata the name of the command
• We need to tell Stata: 1) what else the program needs to run, 2) what it should expect, and 3) how we will reference it

Syntax

• Stata already parses any code written after your command name
• `0’: everything written after the command name
• `1’, `2’, `3’, …, `n’: each space-separated word after the command name
• syntax command parses code into specific macros
• Specify how you want Stata to read the inputs

Syntax: Command

• syntax defines how the program parses command inputs
• varlist/varname: create `varlist’
• if: creates `if’
• in: creates `in’
• using: creates `using’
• =exp: creates `exp’
• weight: creates `weight’

Pop Quiz!

Syntax: Options

• Can create own name for each option
• After a “,”
• optionname: creates`optionname’
• For options, capitalize what is the minimum Stata will recognize as an option
• syntax DETail: creates `detail’ as long as “det” is typed
• Two types of options
• Takes a value
• Ex. generate(varname)
• A word
• Ex. replace

Syntax: Defaults and Constraints

• Varlist can have constraints
• Ex: varlist(numeric max=2)
• Only allows 1 or 2 variable in varlist
• Options can have constraints too
• Ex: syntax, input
• Option input creates `input’
• `input’ = “” if Stata doesn’t find the word input
• Ex: syntax, input(integer 1)
• `input’ = 1 if Stata doesn’t find the word input

Syntax: Other Considerations

• Anything can be optional by using brackets
• [varlist] makes it optional to include variables
• Macros will include “if”, “in”, “=“ unless you include a slash
• syntax if : `if’ = “if foreign == 1”
• syntax if/ : `if’ = “foreign == 1”

Syntax Practice

• Write a command called “practice”
• Extra credit: Allow up to 2 variables
• Create an optional option “detail”
• Extra credit: Make the option such that the user only has to type “d” to use the option
• Your command should summarize the variables (use the summarize command) and use detail option if the user specifies
• Hint: “summarize, “ is the same as “summarize”

Syntax Practice

Creating Your Own Errors & Checks

• You have now:
• Defined a command
• Told Stata how to parse the inputs
• Next step is to create your own errors and checks to ensure that the inputs to your program are the inputs that you want
• dis as error “Your own error message”

exit [errorcode]

• if `filename’ == “” local `filename’ = “output”

Try for yourself!

• Create the “radsummit” command
• Allow up to three numeric variables
• Display:
• Your name
• The variables
• Anything else you want!
• Include optional option “red” that will show outputs in red (use help display)
• Hint: as red

General Programming Best Practices

Best Practices

• Include a comment that contains the version number, date modified, and author

​

• Use sensible names for temporary variables and macros
• Adopt Stata conventions when possible
• Stata has ownership of commands that are in the English dictionary

Best Practices

• Incorporate coding best practices
• Tab lines consistently
• Write within 80 columns
• Organize code logically with code blocks and line breaks
• Avoid # delim ;
• Other people may want to troubleshoot or adjust your command
• Every scenario should be covered by an error

Best Practices

• Use quietly and capture
• Every error should have a clear explanation
• capture confirm will help show you the error so you can address it or show the user the error
• Don’t change data in memory or add/drop variables unless the command explicitly states it will
• Use temporary variables, sortpreserve, or preserve/restore
• Always have user specify new names

References

• Cox, Nick. 2005. “Suggestions on Stata Programming Style.” The Stata Journal 5, no. 4: 560-566. doi.org/10.1177/1536867X0500500406

​

• StataCorp LP. NetCourse 251: Writing your Own Stata Commands.