## Tuesday, January 29, 2013

### Stata Syntax Command's Syntax

do file

* When programming Stata "programs" (loosely known as functions in R) it is often times very useful to use the "syntax" command to parse arguments.

* This command takes the arguments input into the command and uses them to control the function of the command.

* For example:

cap program drop example1
program define example1, rclass

syntax [anything]
* The [] tell stata that this argument is optional
* The anything tells Stata that this argument can be of any form excluding a comma (,)

di "anything'"

* The local function 1 returns the first argument in the command
di "1'"

* While 2 returns the second
di "2'"

end

example1 hello world
example1 *
example1 2123 123213 hello world

* We can see the display changes as a result of how the arguments are structured

* Programmers can force the user to input only inputs of a particular structure.

* For instance:

cap program drop example2
program define example2, rclass

syntax [varlist]
* The [] tell stata that this argument is optional
* The anything tells Stata that this argument can be of any form excluding a comma (,)

di "varlist'"

* The local function 1 returns the first argument in the command
di "1'"

* While 2 returns the second
di "2'"

* Variables targetted in this manner can be modified:
foreach v of varlist varlist' {
rename v' r_v'_rename
}

end

clear

gen hello = "content of variable hello"
gen world = "content of variable world"

example2 hello world
* Which works because we created the variables hello and world

example2 hello world
* This does not work because the above command already renamed the variables hello and world

* There is a lot of trickiness involved in effectively programming the syntax command and unfortunately it can be very frustrating because the only feedback stata gives is "invalid syntax" when something goes wrong.

* Also, unfortunately stata does not have many actual coding examples in which syntax is displayed.

* However, I think the following example will go a long way to answering many questions.

* This is the start of a command that will simulate data and test different estimators on that data.

* It will also set default parameters if the user does not input parameters into the simulation directly.

* Before executing the command, the command will display to the user the parameter set to be estimated

cap program drop example3
program define example3, rclass

*
syntax [anything] [, NGrp(numlist >0 integer) NInd(numlist >0 integer) ///
Rgrp(numlist integer) Udist(string) NEXogenous NENdogenous]
* The first few letters being capital allows the user to abreviate the option to just those two or three letters.

* Set defaults if the user has not defined any.
if "ngrp'"==""   local ngrp=50
if "nind'"==""   local nind=20
if "rgrp'"==""   local rgrp=0
if "udist'"==""  local udist="rnormal()*5"

* This sets the local parameter exogenous to be equal to 1 by default unless the user specifies ontherwise
local exogenous=1
if "nexogenous'"!="" local exogenous=0

local endogenous=1
if "nendogenous'"!="" local endogenous=0

di as text _newline "Simulation Paramaters"
di "Number of groups: ngrp'"
di "Average number of individuals in each group: nind'"
di "Group size random (0 no, 1 yes): rgrp'"
di "Error distribution: udist'"

di _newline _c "Models estimated: "
if exogenous' == 1 di _c "EXOGENOUS"
if endogenous' == 1 di " ENDOGENOUS"
if  exogenous' == 0 & `endogenous' == 0 di "No model estimated!"

********************

* The actual simulation

********************

* End of the command
end

example3 , ngrp(454)
example3 , ng(454)
* See how the abreviation is possible

example3 , nex  udist(runifrom()*3)
example3 , nex  udist(runifrom()*3) r(1)

example3 , nex nen

* It is very useful to check out the "help syntax" file.