Stata 15 help for _diparm

Title

[P] _diparm -- Programmer's utility for displaying ancillary parameters

Syntax

Syntax for one ancillary parameter:

_diparm eqname [, [ exp | tanh | invlogit | function(expr(@)) derivative(expr(@)) ] label(string) prob dof(#) level(#) notab ]

where expr(@) is an expression with @ substituted for the parameter [eqname]_cons.

Syntax for a parameter that is a function of 2-9 ancillary parameters:

_diparm eqname1 eqname2 [eqname3 ...] , function(expr(@1,@2,...)) derivative(expr1(@1,@2,...) expr2(@1,@2,...) ...) [ ci(logit | probit | atanh | log) label(string) prob dof(#) level(#) notab ]

where expr(@1,@2,...) is an expression with @1,@2,... substituted for the parameters [eqname1]_cons, [eqname2]_cons,....

Syntax for drawing a separator line:

_diparm __sep__

Syntax for drawing the bottom line:

_diparm __bot__

Syntax for adding a labeled row:

_diparm __lab__, label(string) [ eqlabel value(#) comment(string) ]

Description

Ancillary parameters are often estimated in a transformed metric; for example, rather than estimating sigma, we estimate ln(sigma). In an estimation output table, we would like to display the transformed parameter with the "/" notation (for example, /lnsigma) and display the parameter in its natural metric (for example, sigma).

This command displays the ancillary parameter, its standard error, confidence interval, and, optionally, the z or t statistic and p-value. The confidence interval for one parameter in any metric other than the estimation metric is obtained by taking the confidence interval in the estimation metric and transforming the endpoints.

For a parameter that is a function of more than one estimated parameter, the second syntax applies. Here, confidence intervals can be optionally transformed using the ci() option so that the endpoints lie within certain bounds:

(0, 1) ci(logit) (0, 1) ci(probit) (-1, 1) ci(atanh) (0, +inf) ci(log)

Thus, the CI is

f^-1( f(b) +/- z*se*|f'(b)| )

where f() is either the logit, probit, atanh, or log transform.

Options

label(string) specifies how to label the parameter in the output. By default, the label is /eqname, where eqname is shortened to 12 characters if necessary.

The following options are allowed in addition to the required label() option when _diparm __lab__ is specified.

eqlabel indicates that the label() option contains the label for an equation. This changes the default alignment and color of the label to that of an equation.

value(#) specifies a value to be placed in the coefficient column.

comment(string) specifies a comment to be placed in the standard error column.

prob requests that the test statistic and p-value be displayed. If the parameter is being displayed in the estimation metric, then, by default, these are displayed. If the parameter is being displayed in another metric, then, by default, these are not displayed.

dof(#) specifies the degrees of freedom for a t statistic. If not specified, a z statistic is used for the confidence interval, test statistic, and p-value.

level(#) specifies the confidence level for the confidence intervals; see [R] level.

notab suppresses the table entry from being displayed.

exp specifies that exp(estimated parameter) is to be displayed; that is, the estimated parameter was the log of the natural parameter.

tanh specifies that tanh(estimated parameter) is to be displayed; that is, the estimated parameter was the arctanh of the natural parameter.

invlogit specifies that invlogit(estimated parameter) is to be displayed; that is, the estimated parameter was the logit of the natural parameter. Note that this option has ilogit as a synonym.

function(expr(@)) specifies that expr(estimated parameter) is to be displayed. It is not optional when the parameter is a function of more than one estimated parameter (second syntax). See Remarks below.

derivative(expr(@)) specifies the derivative of the function specified in function(). This must be specified when function() is specified. It is not optional when the parameter is a function of more than one estimated parameter (second syntax). For functions of more than one estimated parameter, derivative() must contain the derivative w.r.t. each parameter; each derivative must be separated with a space; no spaces are allowed within each derivative expression. (For functions of one parameter, spaces are allowed within the expression.) See Remarks below.

ci(logit | probit | atanh | log) specifies an optional transformation so that the endpoints of the CI are bounded. It is ONLY allowed for functions of more than one estimated parameter. See "Description" above.

Remarks

Remarks are presented under the following headings:

Specifying a function of one estimated parameter Specifying a function of more than one estimated parameter

Specifying a function of one estimated parameter

Let x be the estimated parameter. Suppose that we wish to display y = f(x). The function f(.) is specified in the function() option as f(@). That is, the option is specified as function(f(@)).

For example, suppose that x = lnsigma. We wish to display sigma = exp(lnsigma). The option is specified as function(exp(@)). (Note that here we need not resort to the function() option; we can merely use the exp option.)

Note that the function specified in function() is typically the inverse of the transform used to create the estimated parameter, but it can be any function.

Suppose that we wish to display 1/sigma = 1/exp(lnsigma). The option is specified as function(1/exp(@)) or function(exp(-@)).

When specifying function(), the derivative() option must also be specified. It is the derivative f'(.) of the function f(.).

For example, if using function(exp(-@)), then you specify derivative(-exp(-@)).

Note that multiple @ are allowed.

Specifying a function of more than one estimated parameter

The same logic applies here. The only difference is that the function must be written as an expression using @1, @2, ... (a maximum of 9 parameters are allowed). @1 is substituted for the first parameter in the argument list, @2 for the second, etc.

function() supplies one expression, but note that derivative() must supply the derivatives w.r.t. each parameter. Hence, derivative() contains multiple expressions; the first is the derivative w.r.t. the first parameter in the argument list; the second is the derivative w.r.t. the second parameter, etc. These expressions must be separated by a space. No spaces are allowed within the expression. (Note: Spaces are always allowed in function(), and allowed in derivative() when there is only one parameter.)

Examples

Here is how _diparm could be used in weibull. It displays

(1) ln(p), the parameter in the estimation metric,

(2) p = exp(ln(p)), the natural parameter,

(3) 1/p = exp(-ln(p)).

program define weibull ... [do estimation] ...

ml mlout, `eform' level(`level') first

_diparm ln_p, level(`level') _diparm __sep__"

_diparm ln_p, level(`level') exp label("p") _diparm ln_p, level(`level') f(exp(-@)) d(exp(-@)) label("1/p") _diparm __bot__ end

Note that in the last call of _diparm, d(exp(-@)) is acceptable, as is d(-exp(-@)), because _diparm only uses the absolute value of the derivative.

Here is how _diparm could be used in heckman to display rho, sigma, and lambda:

_diparm athrho, level(`level') _diparm lnsigma, level(`level')

_diparm __sep__

_diparm athrho, level(`level') tanh label("rho") _diparm lnsigma, level(`level') exp label("sigma")

_diparm athrho lnsigma, /* */ func(exp(@2)*(exp(@1)-exp(-@1))/(exp(@1)+exp(-@1)) )/* */ der( exp(@2)*(1-((exp(@1)-exp(-@1))/(exp(@1)+exp(-@1)))^2) /* */ exp(@2)*(exp(@1)-exp(-@1))/(exp(@1)+exp(-@1)) ) label(lambda)

Here is how _diparm could be used in xtreg, mle to display rho using a probit transform to ensure that the endpoints lie between 0 and 1:

_diparm sigma_u sigma_e, label(rho) func(@1^2/(@1^2+@2^2)) /* */ der( 2*@1*(@2/(@1^2+@2^2))^2 -2*@2*(@1/(@1^2+@2^2))^2 ) ci(probit)

Stored results

_diparm stores the following in r():

r(est) = parameter in the metric displayed r(se) = standard error of the parameter in the metric displayed r(lb) = lower bound of confidence interval r(ub) = upper bound of confidence interval r(p) = p-value for significance test if displayed


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