_diparm.hlp

是一个经济学管理应用软件 很难找的 但是经济学学生又必须用到

{smcl}
{* 10mar2005}{...}
{cmd:help _diparm}{...}
{right:also see:  {help undocumented}}
{hline}

{title:Title}

{pstd}
{hi:_diparm} {hline 2}
Programmer's utility for displaying ancillary parameters


{title:Syntax}

{pstd}
Syntax for one ancillary parameter:

{p 8 26 2}
{cmd:_diparm} {it:eqname}
	[{cmd:,}
		[
			{cmd:exp} | {cmd:tanh} | {cmd:invlogit} |
			{cmdab:f:unction:(}{it:expr(@)}{cmd:)} 
			{cmdab:d:erivative:(}{it:expr(@)}{cmd:)}
		]
		{cmdab:lab:el:(}{it:string}{cmd:)}
		{cmdab:p:rob}
		{cmd:dof(}{it:#}{cmd:)}
		{cmdab:l:evel:(}{it:#}{cmd:)}
		{opt notab}
	]

{pstd}
where {it:expr(@)} is an expression with {it:@} substituted for the
parameter {cmd:[}{it:eqname}{cmd:]_cons}.


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

{p 8 26 2}
{cmd:_diparm} {it:eqname1} {it:eqname2} [{it:eqname3} ...] {cmd:,}
	{cmdab:f:unction:(}{it:expr(@1,@2,...)}{cmd:)}
	{cmdab:d:erivative:(}{it:expr1(@1,@2,...)} {it:expr2(@1,@2,...)}
		...{cmd:)}
	[
		{cmd:ci(logit} | {cmd:probit} | {cmd:atanh} |
		{cmd:log)} {cmdab:lab:el:(}{it:string}{cmd:)}
		{cmdab:p:rob} {cmd:dof(}{it:#}{cmd:)}
		{cmdab:l:evel:(}{it:#}{cmd:)}
		{opt notab}
	]

{pstd}
where {it:expr(@1,@2,...)} is an expression with {it:@1,@2,...} substituted
for the parameters {cmd:[}{it:eqname1}{cmd:]_cons},
{cmd:[}{it:eqname2}{cmd:]_cons},....


{title:Description}

{pstd}
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 (1) display the transformed parameter with the
"{hi:/}" notation (e.g., {hi:/lnsigma}) and (2) display the parameter in its
natural metric (e.g., sigma).

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

{pstd}
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 {cmd:ci()} option so that the endpoints lie within
certain bounds:

{col 13}(0, 1){col 25}{cmd:ci(logit)}
{col 13}(0, 1){col 25}{cmd:ci(probit)}
{col 13}(-1, 1){col 25}{cmd:ci(atanh)}
{col 13}(0, +inf){col 25}{cmd:ci(log)}

{pstd}
Thus, the CI is

{p 12 12 2}f^-1( f(b) +/- z*se*|f'(b)| )

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


{title:Options}

{phang}
{cmd:label(}{it:string}{cmd:)} specifies how to label the parameter in the
output.  By default the label is {hi:/}{it:eqname}, where {it:eqname} is
shortened to 12 characters if necessary.

{phang}
{cmd:prob} requests that the test statistic and {it: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.

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

{phang}
{cmd:level(}{it:#}{cmd:)} specifies the confidence level for the
confidence intervals; see {help level}.

{phang}
{opt notab} suppresses the table entry from being displayed.

{phang}
{cmd:exp} specifies that {cmd:exp(}estimated parameter{cmd:)} is to be
displayed; that is, the estimated parameter was the log of the natural
parameter.

{phang}
{cmd:tanh} specifies that {cmd:tanh}(estimated parameter{cmd:)} is to be
displayed; that is, the estimated parameter was the arctanh of the natural
parameter.

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

{phang}
{cmd:function(}{it:expr(@)}{cmd:)} 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.

{phang}
{cmd:derivative(}{it:expr(@)}{cmd:)} specifies the derivative of the
function specified in {cmd:function()}.  This must be specified when
{cmd: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, {cmd: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 a single parameter, spaces are allowed within the expression.)
See "Specifying a function of the estimated parameter" below.

{phang}
{cmd:ci(logit} | {cmd:probit} | {cmd:atanh} | {cmd: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.


{title:Specifying a function of a single estimated parameter}

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

{pstd}
For example, suppose that x = lnsigma. We wish to display
sigma = exp(lnsigma).  The option is specified as {cmd:function(exp(@))}.
(Note that in this case, we need not resort to the {cmd:function()} option; we
can merely use the {cmd:exp} option.)

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

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

{pstd}
When specifying {cmd:function()}, the {cmd:derivative()} option must also be
specified.  It is the derivative f'(.) of the function f(.).

{pstd}
For example, if using {cmd:function(exp(-@))}, then you specify
{cmd:derivative(-exp(-@))}.

{pstd}
Note that multiple {cmd:@} are allowed.


{title:Specifying a function of more than one estimated parameter}

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

{pstd}
{cmd:function()} supplies a single expression, but note that
{cmd:derivative()} must supply the derivatives w.r.t. each parameter.  Hence,
{cmd: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 {cmd:function()}, and allowed in {cmd:derivative()} when there is
only a single parameter.)


{title:Saved results}

{pstd}
{cmd:_diparm} saves in {hi:r()}:

{p 8 19 2}{hi:r(est)}{space 2}={space 2}parameter in the metric displayed{p_end}
{p 8 19 2}{hi:r(se)}{space 3}={space 2}standard error of the parameter in the
	metric displayed{p_end}
{p 8 19 2}{hi:r(lb)}{space 3}={space 2}lower bound of confidence interval{p_end}
{p 8 19 2}{hi:r(ub)}{space 3}={space 2}upper bound of confidence interval{p_end}
{p 8 19 2}{hi:r(p)}{space 4}={space 2}{it:p}-value of significance test if displayed


{title:Examples}

{pstd}
Here is how {cmd:_diparm} is used in {cmd:weibull}.  It displays

{phang}(1) ln(p), the parameter in the estimation metric,

{phang}(2) p = exp(ln(p)), the natural parameter,

{phang}(3) 1/p = exp(-ln(p)).

	{cmd:program define weibull}
		{it:...}
		{it:[do estimation]}
		{it:...}

		{cmd:ml mlout, `eform' level(`level') first}

		{cmd:_diparm ln_p, level(`level')}
		{cmd:di in gr _dup(78) "-"}

		{cmd:_diparm ln_p, level(`level') exp label("p")}
		{cmd:_diparm ln_p, level(`level') f(exp(-@)) d(exp(-@)) label("1/p")}
		{cmd:di in gr _dup(78) "-"}
	{cmd:end}

{pstd}
Note that in the last call of {cmd:_diparm}, {cmd:d(exp(-@))} is acceptable,
as is {cmd:d(-exp(-@))}, since {cmd:_diparm} only uses the absolute value of the
derivative.


{pstd}
Here is how {cmd:_diparm} could be used in {helpb heckman} to display
rho, sigma, and lambda:

{phang}{cmd:_diparm athrho, level(`level')}{p_end}
{phang}{cmd:_diparm lnsigma, level(`level')}

{phang}{cmd:di in gr _dup(9) "-" in gr "+" _dup(69) "-"}

{phang}{cmd:_diparm athrho, level(`level') tanh label("rho")}{p_end}
{phang}{cmd:_diparm lnsigma, level(`level') exp label("sigma")}

{phang}{cmd:_diparm athrho lnsigma, /*}{p_end}
{phang}{cmd:*/ func(exp(@2)*(exp(@1)-exp(-@1))/(exp(@1)+exp(-@1)) )/*}{p_end}
{phang}{cmd:*/ der( exp(@2)*(1-((exp(@1)-exp(-@1))/(exp(@1)+exp(-@1)))^2) /*}{p_end}
{phang}{cmd:*/ exp(@2)*(exp(@1)-exp(-@1))/(exp(@1)+exp(-@1)) ) label(lambda)}

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

{phang}{cmd:_diparm sigma_u sigma_e, label(rho) func(@1^2/(@1^2+@2^2)) /*}{p_end}
{phang}{cmd:*/ der( 2*@1*(@2/(@1^2+@2^2))^2 -2*@2*(@1/(@1^2+@2^2))^2 ) ci(probit)}


{title:Also see}

{psee}
Online:  {helpb _get_diparmopts},
{helpb ml}
{p_end}