__Title__

**[P] _pred_se** -- Subroutine for programming single-equation extensions to
predict

__Example__

**program define** *estimator***, eclass**
*...*
**ereturn local predict "***estimator_p***"**
*...*
**end**

*...*

**program define** *estimator_p*
**local myopts "***new_predict_options***"**
**_pred_se "`myopts'" `0'**
**if `s(done)' { exit }**
**local vtyp `s(typ)'**
**local varn `s(varn)'**
**local 0 `"`s(rest)'"'**
**syntax [if] [in] [, `myopts' noOFFset]**
*...*
**end**

__Description__

**_pred_se** is a subroutine to assist programmers in implementing additions
to **predict** following a single-equation estimation command or, more
correctly, what appears to the user to be a single-equation estimation
command even if, in the implementation, you used multiple equations to
handle ancillary parameters.

This is necessary only if you want to add features to **predict** following
your estimation command. If all you want are the standard **predict**
features -- see **[R] predict** -- there is nothing you need to do; do not
even define **e(predict)** in your estimation command.

If you do wish to add features, then your estimation command must set the
name of your prediction routine in **e(predict)**. We recommend that if your
estimation command is *X*, you name your prediction routine *X***_p**, truncating
the *X* name if needed to fit within the program naming limit. For
instance, if the estimation command were named **ematreg**, we recommend that
the corresponding prediction routine be named **ematreg_p**. At the
appropriate place in the code for ematreg.ado, include

**ereturn local predict "ematreg_p"**

Above we show the outline for ematreg_p.ado.

**_pred_se** will handle the standard cases. The "*...*" in your prediction
program is responsible for handling the default case when no options are
specified and the special case when one of the new options stored in
**`myopts'** is specified.

Here is how we would fill in the dots if the **predict** options we were
adding were **pr**, **rratio**, **distance**, and **dfbeta(***varname***)** so that, following
estimation, the syntax of **predict** would be

**predict** [*type*] *newvarname* [**if** *exp*] [**in** *range*] [**,** **pr** __r__**ratio** __d__**istance**
__dfb__**eta(***varname***)** __i__**ndex** **xb** **stdp** __nooff__**set** ]

with **pr** the default. Note that **index**, **xb**, and **stdp** are the standard
**predict** options; our program need only be concerned with providing code
to handle the **pr**, **rratio**, **distance**, and **dfbeta()** options.

Our program is

**program define** *...*
**version 15.1**
**local myopts "PR Rratio Distance DFBeta(varname)"**
**_pred_se "`myopts'" `0'**
**if `s(done)' { exit }**
**local vtyp `s(typ)'**
**local varn `s(varn)'**
**local 0 `"`s(rest)'"'**
**syntax [if] [in] [, `myopts' noOFFset]**

/* concatenate switch options together */
**local type "`pr'`rratio'`distanc'"**

/* quickly process default case */
**if ("`type'"=="" | "`type'"=="pr") & "`dfbeta'"=="" {**
**if "`type'"=="" {**
**di in gr "(option pr assumed)"**
**}**
**tempvar t**
**qui _predict double `t' `if' `in', `offset'**
*...*
**gen `vtyp' `varn' =** *...* **`if' `in'**
**label var `varn' "Probability of positive outcome"**
**exit**
**}**

/* mark sample */
**marksample touse**

/* handle options that take argument, if
any; we have one such option */
**if "`dfbeta'" != "" {**
**if "`type'" != "" { error 198 }**
*...*
**exit**
**}**

/* handle switch options */
/* first do the ones that work both */
/* in and out-of-sample. */
**if "`type'"=="rratio" {**
**tempvar t** *...*
**qui _predict double `t' if `touse', stdp `offset'**
*...*
**gen `vtyp' `varn' =** *...* **if `touse'**
**label var `varn' "R-metric ratio"**
**exit**
**}**

/* then handle the options that only */
/* make sense when used with the */
/* estimation subsample */

**qui replace `touse'=0 if ~e(sample)**

**if "`typ'"=="distance" {** /* restricted to e(sample) */
**tempvar r t** *...*
**qui predict double `r' if `touse', rratio `offset'**
**qui _predict double `t' if `touse', stdp `offset'**
*...*
**gen `vtyp' `varn' =** *...* **if `touse'**
**label var `varn' "Distance from centroids"**
**exit**
**}**

**error 198**
**end**

In reviewing this program, please note the following:

1. All intermediate calculations are made using doubles.

2. **_predict** is used to assist in the calculations.

3. We call **predict** itself, and thus recursively call our program, in
implementing option **distance**.

4. Caution is exercised to ensure that the **nooffset** option is
handled correctly (or rather, that offsets, if they exist, are
handled correctly).

5. Caution is exercised to ensure that the user sees the message
"___ missing values generated" if any of the predictions are
missing. This we accomplish by ending each calculation with a
**generate**.

6. The new variable is labeled after creation.