Stata 15 help for _prefix

Title

[P] _prefix -- Overview of subroutines for parsing prefix commands

Description

Stata has a suite of prefix commands. This entry describes some of the subroutines that are used by the following prefix commands.

bootstrap, jackknife, permute, nestreg, rolling, simulate, statsby, stepwise, svy

Remarks

Remarks are presented under the following headings:

Splitting text on the colon character Clearing e() and r() Parsing a user supplied command Parsing a list of expressions Expanding and evaluating expression lists

Splitting text on the colon character

See _on_colon_parse.

Clearing e() and r()

Use _prefix_clear to clear the contents of e(), r() or both.

_prefix_clear [, eclass rclass]

eclass clears the e() stored results.

rclass clears the r() stored results.

If neither option is specified, the stored results in e() and r() remain.

Parsing a user supplied command

Use _prefix_command to parse the contents of command, which should follow standard Stata syntax. caller should be the name of the routine calling _prefix_command and will be used in error messages.

_prefix_command caller [if] [in] [weight] [, svy norest checkcluster checkvce cluster(varlist) level(#) COEF eform_option ] : command

command can contain calls to version, capture, noisily, and quietly; although capture, noisily, and quietly are removed with a note. command cannot have calls to by or xi. command is assumed to have some of or all the following syntax elements:

cmd_name [anything] [cmd_if] [cmd_in] [cmd_weight] [, cmd_options] [: rest]

_prefix_parse checks for conflicts between if, in, and weight when they are also specified in command.

svy specifies that weights are not allowed.

norest specifies that "[: rest]" is not allowed in command.

checkcluster specifies that the varlist from the cluster() option must be returned in s(cluster) even if cluster() is not specified as an option of _prefix_command but is specified in cmd_options.

level(#) is the standard Stata level() option. _prefix_command checks for conflicts when the level() option is also specified in cmd_options.

coef is the anti-eform_option of logistic. _prefix_command checks for conflicts with eform_option, and also checks if the corresponding options are specified in cmd_options.

eform_option is one of the options documented in [R] eform_option. _prefix_command checks for conflicts when eform_option is also specified in cmd_options.

_prefix_command stores the following in s():

Macros:

s(version) version prefix for use with command s(cmdname) cmd_name s(anything) anything s(wtype) type of weight, if weights specified s(wexp) weight expression, if weights specified s(wgt) [weight], if weights specified s(if) [if] restriction s(in) [in] restriction s(rest) : rest, if rest specified s(efopt) eform_option s(eform) eform() equivalent of eform_option s(level) # from level(#) option s(cluster) varlist from cluster() option s(options) cmd_options s(vce) vcetype from vce(vcetype) option if checkvce specified s(command) command, possibly with some options removed

Parsing a list of expressions

Use _prefix_explist as the first step in the two-step process of parsing an exp_list. exp_list identifies the grammar for lists of expressions that are specifically used by prefix commands that allow them.

_prefix_explist [exp_list] , stub(name) [ geqname(name) default edefaultonly ]

stub(name) specifies the stub used to generate default names used to identify the individual expressions in exp_list. If stub(myexp) is specified, then myexp# identifies the #th unnamed expression in exp_list.

geqname(name) specifies the equation name that will be attached to expressions in exp_list that are not already part of a named group. The default is geqname(_eq).

default specifies that _prefix_explist generate the default expression list if exp_list is not specified. If exp_list is not specified, the default depends the results in e() and r(). If e(b) exists, then the default exp_list is _b. If e(b) does not exist, then the default is all the scalars posted to r(). It is an error not to specify an expression in exp_list otherwise.

edefault specifies that _prefix_explist generate the default expression list if exp_list is not specified. If exp_list is not specified and e(b) exists, then the default exp_list is _b. It is an error not to specify an expression in exp_list otherwise.

_prefix_explist stores the following in s():

Macros:

s(k_exp) the number of exp expressions in exp_list s(idlist) list of names for each exp expression s(eqlist) list of equation names for each exp expression s(k_eexp) the number of eexp expressions in exp_list s(eexplist) the list of eexp expressions

Expanding and evaluating expression lists

After using _prefix_explist to perform a preliminary parse of an exp_list and running the user supplied command (command from _prefix_command above), use _prefix_expand to produce the expanded list of expressions and collect their observed values in matname.

_prefix_expand matname [exp1 exp2 ...] , stub(name) [ eqstub(name) eexp(eexp) colnames(names) coleq(names) ]

stub(name) specifies the stub used to generate default names used to identify the individual expressions. If stub(myexp) is specified, then myexp# identifies the # unnamed expression.

eqstub(name) specifies the stub used to generate default equation names used to identify the equations or group of expressions. If eqstub(gp) is specified, then gp# identifies the # unnamed group of expressions. The default is eqstub(_eq).

eexp(eexp) specifies the eexp elements as defined in exp_list. Individual expressions are derived by expanding each eexp.

In the grammar for exp_list, an eexp is basically _b or _se (with the possibility to restrict to a specified equation); see _variables. _prefix_expand assigns default names to each individual expressions derived from _b and _se. These default names are based on the equation names and column names. For example, suppose eexp(_b) was specified and e(b) contains the following:

[xb]_b[mpg] [xb]_b[turn] [xb]_b[trunk] [xb]_b[_con] [lnsigma]_b[_con]

_prefix_expand will generate default names for these derived expressions as follows:

expression name ------------------------------------------------------ [xb]_b[mpg] xb_b_mpg [xb]_b[turn] xb_b_turn [xb]_b[trunk] xb_b_trunk [xb]_b[_con] xb_b_cons [lnsigma]_b[_con] lnsigma_b_cons ------------------------------------------------------

colnames(names) specifies the list of names corresponding to each exp#.

coleq(names) specifies the list of equation names corresponding to each exp#.

_prefix_expand stores the following in s():

Macros:

s(exp#) the #th expression s(k_eexp) number of expressions expanded from eexp s(ecoleq) equation names from eexp s(ecolna) expression names from eexp s(k_exp) number of expression from the exp# s(coleq) equation names for the exp# s(colna) expression names for the exp# s(k_eq) total number of number of equations s(k_extra) number of unique names from coleq() s(enames) names for expressions from eexp s(eexplist) paren delimited list of the expanded expressions from eexp s(names) names for expressions from the exp# s(explist) paren delimited list of the expressions from the exp#


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index