help program properties
-------------------------------------------------------------------------------
Title
[P] program properties -- Properties of user-defined programs
Description
User-defined programs can have properties associated with them. Some of
Stata's prefix commands -- such as svy and stepwise -- use these
properties for command validation. You can associate program properties
with programs by using the properties() option of program.
program [define] command [, properties(namelist) ...]
// body of the program
end
You can retrieve program properties of command by using the properties
extended macro function.
global mname : properties command
local lclname : properties command
Option
properties(namelist) states that command has the specified properties.
namelist may contain up to 80 characters, including separating
spaces.
Remarks
Remarks are presented under the following headings:
Writing programs for use with nestreg and stepwise
Writing programs for use with svy
Writing programs for use with mi
Properties for survival-analysis commands
Properties for exponentiating coefficients
Checking for program properties
Writing programs for use with nestreg and stepwise
Some of Stata's estimation commands can be used with the nestreg and
stepwise prefix commands; see [R] nestreg and [R] stepwise. For example,
the syntax diagram for the regress command could be presented as
[nestreg, ...:] regress ...
or
[stepwise, ...:] regress ...
In general, the syntax for these prefix commands is
prefix_command [, prefix_options] : command depvar (varlist)
[(varlist) ...] [if] [in] [, options]
where prefix_command is either nestreg or stepwise.
You must follow some additional programming requirements to write
programs (ado-files) that can be used with the nestreg and stepwise
prefix commands. Some theoretical requirements must be satisfied to
justify using nestreg or stepwise with a given command.
o command must be eclass and accept the standard estimation syntax; see
[P] program, [P] syntax, and [P] mark.
command varlist [if] [in] [weight] [, options]
o command must save the model coefficients and ancillary parameters in
e(b) and the estimation sample size in e(N), and it must identify the
estimation subsample in e(sample); see [P] ereturn.
o For the likelihood-ratio test, command must have property swml. For
example, the program definition for poisson appears as
program poisson, ... properties(... swml ...)
command must also save the log-likelihood value in e(ll) and the
model degrees of freedom in e(df_m).
o For the Wald test, command must have property sw if it does not already
have property swml. For example, the program definition for qreg
appears as
program qreg, ...properties(... sw ...)
command must also save the variance estimates for the coefficients
and ancillary parameters in e(V); see [R] test.
Writing programs for use with svy
Some of Stata's estimation commands can be used with the svy prefix; see
[SVY] svy. For example, the syntax diagram for the regress command could
be presented as
[svy:] regress ...
In general, the syntax for the svy prefix is
svy [, svy_options] : command varlist [if] [in] [, options]
You must follow some additional programming requirements to write
programs (ado-files) that can be used with the svy prefix. The extra
requirements imposed by the svy prefix command are from the three
variance-estimation methods that it uses: vce(brr), vce(jackknife), and
vce(linearized). Each of these variance-estimation methods has
theoretical requirements that must be satisfied to justify using them
with a given command.
o command must be eclass and allow iweights and accept the standard
estimation syntax; see [P] program, syntax, and mark.
command varlist [if] [in] [weight] [, options]
o command must save the model coefficients and ancillary parameters in
e(b) and the estimation sample size in e(N), and it must identify the
estimation subsample in e(sample); see [P] ereturn.
o svy's vce(brr) requires that command have svyb as a property. For
example, the program definition for regress appears as
program regress, ... properties(... svyb ...)
o vce(jackknife) requires that command have svyj as a property.
o vce(linearized) has the following requirements:
a. command must have svyr as a property.
b. predict after command must be able to generate scores with the
following syntax:
predict [type] stub* [if] [in], scores
This syntax implies that estimation results with k equations will
cause predict to generate k new equation-level score variables.
These new equation-level score variables are stub_1 for the first
equation, stub_2 for the second equation, ..., and stub_k for the
last equation. Actually svy does not strictly require that these
new variables be named this way, but this is a good convention to
follow.
The equation-level score variables generated by predict must be
of the form that can be used to estimate the variance using
Taylor linearization (otherwise known as the delta method); see
[SVY] variance estimation
c. command must save the model-based variance estimator for the
coefficients and ancillary parameters in e(V); see [SVY] variance
estimation.
Writing programs for use with mi
Stata's mi suite of commands provides multiple imputation to provide
better estimates of parameters and their standard errors in the presence
of missing values; see [MI] intro. Estimation commands intended for use
with the mi estimate prefix must have property mi, indicating that the
command meets the following requirements:
o The command is eclass.
o The command saves its name in e(cmd).
o The command saves the model coefficients and ancillary parameters in
e(b), saves the corresponding variance matrix in e(V), saves the
estimation sample size in e(N), and identifies the estimation
subsample in e(sample).
o If the command employs a small-sample adjustment for tests of
coefficients and reports of confidence intervals, the command saves
the numerator (residual) degrees of freedom in e(df_r).
o Because mi estimate uses its own routines to display the output, to
ensure that results display well the command also saves its title in
e(title). mi estimate also uses macros e(vcetype) or e(vce) to label
the within-imputation variance, but those macros are usually set
automatically by other Stata routines.
Properties for survival-analysis commands
Stata's st suite of commands have the st program property, indicating
that they have the following characteristics:
o The command should only be run on data that have been previously stset.
o No dependent variable is specified when calling that command. All
variables in varlist are regressors. The "dependent" variable is
time or failure, handled by stset.
o Weights are not specified with the command but instead obtained from
stset.
o If robust or replication-based standard errors are requested, the
default level of clustering is according to the ID variable that was
stset, if any.
Properties for exponentiating coefficients
Stata has several prefix commands -- such as bootstrap, jackknife, and
svy -- that use alternative variance-estimation techniques for existing
commands. These prefix commands behave like conventional Stata
estimation commands when reporting and saving estimation results. Given
the appropriate properties, these prefix commands can even report
exponentiated coefficients. In fact, the property names for the various
shortcuts for the eform() option are the same as the option names:
option/property description
---------------------------------------------------------------------
hr hazard ratio
nohr coefficient instead of hazard ratio
shr subhazard ratio
noshr coefficient instead of subhazard ratio
irr incidence-rate ratio
or odds ratio
rrr relative-risk ratio
---------------------------------------------------------------------
For example, the program definition for logit looks something like the
following:
program logit, ... properties(... or ...)
Checking for program properties
You can use the properties extended macro function to check the
properties associated with a program; see [P] macro. For example, the
following retrieves and displays the program properties for logit.
. local logitprops : properties logit
. di "`logitprops'"
or svyb svyj svyr swml
Also see
Manual: [P] program properties
Help: [R] nestreg, [R] stepwise, [SVY] svy, [P] program
