Stata 15 help for byprog

[P] byable -- Make programs byable

Syntax

program [define] program_name [, ... byable(recall[, noheader] | onecall) ...]

Description

Most Stata commands allow the use of the by prefix; see [D] by. For example, the syntax diagram for the regress command could be presented as

[by varlist:] regress ...

This entry describes the writing of programs (ado-files) so that they will allow the use of Stata's by varlist: prefix; see [D] by. If you take no special actions and write the program myprog, then by varlist: cannot be used with it:

. by foreign: myprog myprog may not be combined with by r(190);

By reading this entry, you will learn how to modify your program so that by does work with it.

Option

byable(recall[, noheader] | onecall) specifies that the program is to allow the by prefix to be used with it and specifies the style in which the program is coded.

There are two supported styles, known as byable(recall) and byable(onecall). byable(recall) programs are usually -- not always -- easier to write and byable(onecall) programs are usually -- not always -- faster.

byable(recall) programs are executed repeatedly, once per by group. byable(onecall) programs are executed only once and it is the program's responsibility to handle the implications of the by prefix if it is specified.

byable(recall, noheader) programs are distinguished from byable(recall) programs in that by will not display a by-group header before each calling of the program.

byable(onecall) programs are required to handle the by ...: prefix themselves, including displaying the header should they wish that. See Remarks and examples in [P] byable for details.

Remarks

See Remarks and examples in [P] byable for more information.

Example 1:

program myprog1, byable(recall) syntax [varlist] [if] [in] marksample touse summarize `varlist' if `touse' end

In the above program, it would be a mistake to code it

program myprog1, byable(recall) syntax [varlist] [if] [in] summarize `varlist' `if' `in' end

because in that case, the sample would not be restricted to the appropriate by-group when the user specified the by ...: prefix. marksample, however, knows when a program is being by'd and so will set the `touse' variable to reflect whatever restrictions the user specified and the by-group restriction.

syntax, too, knows about by and it will automatically issue an error message when the user specifies by ...: and an in range together even though in range will be allowed when not combined with by.

Example 2:

program myprog2, byable(recall) sortpreserve syntax varname [if] [in] marksample touse sort `touse' `varlist' ... end

This program specifies sortpreserve because it changes the sort order of the data in order to make its calculations.

Example 3:

program myprog3, byable(onecall) sortpreserve syntax newvarname =exp [if] [in] marksample touse, novarlist tempvar rhs quietly { gen double `rhs' `exp' if `touse' sort `touse' `_byvars' `rhs' by `touse' `_byvars': gen `type' `varlist' = /* */ `rhs' - `rhs'[_n-1] if `touse' } end

This program specifies sortpreserve because it changes the sort order of the data.

In addition, this program is byable(onecall) and, were we to change byable(onecall) to byable(recall), we would break the program. This program creates a new variable and a variable can only be generated once; after that we would have to use replace.


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