Stata 15 help for program_properties

[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 Putting it all together 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 store 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 store 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 store 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 various variance-estimation methods that it uses: vce(bootstrap), vce(brr), vce(jackknife), vce(sdr), 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 store 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(bootstrap), vce(brr), and vce(sdr) require 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 store 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 (see [MI] mi estimate) must have property mi, indicating that the command meets the following requirements:

o The command is eclass.

o The command stores its name in e(cmd).

o The command stores the model coefficients and ancillary parameters in e(b), stores the corresponding variance matrix in e(V), stores the estimation sample size in e(N), and identifies the estimation subsample in e(sample).

o The command stores the number of ancillary parameters in e(k_aux). This information is used for the model F test, which is reported by mi estimate when the command stores model degrees of freedom in e(df_m).

o If the command employs a small-sample adjustment for tests of coefficients and reports of confidence intervals, the command stores 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 stores 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; see [ST] stset.

o No dependent variable is specified when calling that command. All variables in varlist are regressors. The "dependent" variable is time of 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 ...)

Putting it all together

logit can report odds ratios, works with svy, and works with stepwise. The program definition for logit reads

program logit, ... properties(or svyb svyj svyr swml mi) ...

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 mi


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