help _diparm undocumented
-------------------------------------------------------------------------------
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; e.g.,
rather than estimating sigma, we estimate ln(sigma). In an estimation
output table, we would like to display the transformed parameter with the
"/" notation (e.g., /lnsigma) and display the parameter in its natural
metric (e.g., 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 "Specifying a
function of the estimated parameter" 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
"Specifying a function of the estimated parameter" 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.
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.)
Saved results
_diparm saves 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 of significance test if displayed
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)
Also see
Manual: undocumented
Help: [P] _get_diparmopts, [R] ml
