Are `touse' and `varlist' reserved names for locals?

Question

What do touse and varlist mean exactly? Are these locals generated automatically?

program sample, sortpreserve rclass 

syntax varname(numeric) [fweight] [if] [in] ///

if "`summarize'" != "" local summ "summ" 
if "`welfare'" != ""    local w "w" 
local inc "`varlist'"

if "`weight'" == "" gen byte `wi' = 1
else gen `wi' `exp'

marksample touse
if "`bygroup'" != "" markout `touse' `bygroup'

qui count if `touse'
if r(N) == 0 error 2000

Answer 1

The local varlist was created by the syntax command, and contains the name of a single variable (as you specified varname not varlist). You can read more about this here: http://www.stata.com/help.cgi?syntax

The temporary variable touse was created by the command marksample touse. It is a variable that is 1 when varlist and any weight variable is not missing and the if and in conditions are satisfied, and 0 otherwise. You later modify that variable using markout to have value 0 when the variable(s) in bygroup are missing. In essence it is a temporary variable that contains the value 1 (true) when you want to use that observation and 0 (false) when you want to ignore that observation. You can read more about that here: http://www.stata.com/help.cgi?marksample

Answer 2

Neither is a reserved word, but in both cases there are conventional uses.

Using the name touse in conjunction with marksample started as a convention in so far as StataCorp programmers use it as house style and many user-programmers followed suit. (The name runs together "to use".)

What marksample touse does, usually but not necessarily after a syntax statement, is to create a byte indicator variable which is 1 in observations to be used by a command and 0 in observations not to be used.

However, it is a very good convention. Whether you adopt it depends partly on whether you want your Stata programs to be understood by other Stata programmers. Nothing stops you using another name, which you would then need to use later in your programs.

Using the name varlist splits into two. Your example program shows the first, but not the second.

• If a syntax statement specifies varname or varlist indicating that variables may be specified (and often how many and what kind), then once that is executed the name(s) of the variables in question will be held in a local macro varlist, which can be thought of as created by syntax.

• You can always use the macro name varlist for any purpose you like, although it would be considered poor style to do that for anything but a list of variable names. So, you can always go (e.g.)

  local varlist "mpg weight" 
  

Note that if syntax earlier created such a varlist macro, then any such definition will overwrite it, a source of strange bugs if that is not what you want. (The same applies e.g. to local macros if and in.)