{smcl}
{* 15oct2008}{...}
{hi:help nlcheck}
{hline}
{title:Title}
{pstd}{hi:nlcheck} {hline 2} Check linearity assumption after model estimation
{title:Syntax}
{p 8 15 2}
{cmd:nlcheck} {varname} [{varlist}]
[{cmd:,}
{help nlcheck##opt:{it:options}}
]
{synoptset 22 tabbed}{...}
{marker opt}{synopthdr:options}
{synoptline}
{syntab :Main}
{synopt :{opt b:ins(#)}}number of bins for the adaptive fit; default is
{cmd:bins(10)}
{p_end}
{synopt :{opt s:pline}}use linear spline instead of bins
{p_end}
{synopt :{opt k:nots(#)}}number of knots for the spline fit; default is
{cmd:knots(9)}
{p_end}
{synopt :{opt eq:freq}}use equal frequency bins
{p_end}
{synopt :{opt d:iscrete}}treat {it:varname} as a discrete variable
{p_end}
{synopt :{opt noi:sily}}display adaptive model estimation results
{p_end}
{syntab :Graph}
{synopt :{opt g:raph}}display graph containing linear predictions
{p_end}
{synopt :{opt l:evel(#)}}set confidence level; default is {cmd:level(95)}
{p_end}
{synopt :{opt step}}use model without linear term to plot the adaptive fit
{p_end}
{synopt :{opt eq:uation(eqno)}}plot predictions for {it:eqno} equation in a multiple-equation system
{p_end}
{synopt :{it:{help cline_options}}}affect rendition of the plotted
predictions
{p_end}
{synopt :{opth ciopt:s(area_options)}}affect rendition of the plotted confidence interval
{p_end}
{synopt :{it:{help twoway_options}}}any options other than {cmd:by()}
documented in {bind:{bf:[G] {it:twoway_options}}}
{p_end}
{synoptline}
{title:Description}
{pstd}
{cmd:nlcheck} is a simple diagnostic tool that can be used after
fitting a model to quickly check the linearity assumption for predictor
{varname}. {cmd:nlcheck} categorizes the predictor into bins, refits
the model including dummy variables for the bins, and then performs a
joint Wald test for the added parameters. A significant test result
indicates that the linearity assumption is violated. Alternatively, if
the {cmd:spline} option is specified, {cmd:nlcheck} uses linear splines
for the adaptive model. Furthermore, support for discrete
variables is provided (see the {cmd:discrete} option).
{pstd}
Optionally, {cmd:nlcheck} also displays a graph of the adjusted linear
predictions from the original model and the adaptive model (setting all
other variables to the mean). Pointwise confidence intervals are
plotted for the adaptive fit. Such a linear prediction plot can be
useful to evaluate the functional form of a relationship.
{pstd}
If a predictor enters the model repeatedly via different
transformations (e.g. polynomials), then these additional terms should
be taken into account when computing the adjusted linear predictions for
the graph. Use {varlist} to specify such additional variables.
{pstd}
{cmd:nlcheck} can be used with any estimation command as long as it
supports {helpb test} (and, if {cmd:graph} is specified, {helpb adjust}), follows the standard syntax
{it:command} {it:varlist} [{it:if}] [{it:in}] [{it:weight}] [{cmd:,} {it:options} ]
{pstd}
and stores the command as typed in {cmd:e(cmdline)}. Stata 10 is required.
{title:Options}
{dlgtab:Main}
{phang}
{opt bins(#)} sets the number of bins used for the adaptive fit (resulting in
#-1 additional parameters). The default is
{cmd:bins(10)} or {cmd:knots()}+1 if {cmd:knots()} is specified.
{phang}
{opt s:pline} causes linear splines to be used for the adaptive fit
instead of bins.
{phang}
{opt knots(#)} sets the number of knots for the spline fit. The default is
{cmd:knots(9)} or {cmd:bins()}-1 if {cmd:bins()} is specified.
{phang}
{opt eqfreq} causes the bin boundaries to be chosen according to
quantiles of the empirical distribution of the predictor (i.e. so that
each bin contains approximately the same number of observations). The
default is to determine the cut points based on quantiles of the
distinct values of the predictor (i.e. so that each bin contains
approximately the same number of distinct values). With {cmd:spline},
the knots are positioned at equally spaced quantiles (of the distinct
values or of the empirical distribution, depending on the {cmd:eqfreq}
option) with half a step before the first knot and after last.
{phang}
{opt discrete} causes {varname} to be treated as a discrete
variable and includes one parameter for each distinct value of the
predictor in the adaptive model. The {cmd:bins()}, {cmd:knots()}, and
{cmd:spline} options are not allowed with {cmd:discrete}.
{phang}
{opt noisily} causes the estimation results from the adaptive model to
be displayed.
{dlgtab:Graph}
{phang}
{cmd:graph} plots the linear predictions from the base model and the
adaptive fit against the predictor with all other variables set to
their mean and including pointwise confidence intervals for the
adaptive fit.
{phang}
{opt level(#)} specifies the confidence level, as a percentage,
for the plotted confidence intervals. The default is {cmd:level(95)} or
as set by {helpb set level}.
{phang}
{opt equation(eqno)}, where {it:eqno} is {cmd:#}{it:#} or {it:name}
specifies the equation in a multiple-equation system for which the
predictions be plotted. This option is allowed only after
multiple-equation commands.
{phang}
{opt step} causes the plotted adaptive fit to be based on a
model from which the original predictor is excluded. The adjusted
predictions from such model appear as a step-function and may be easier
to read. {cmd:step} has no effect with {cmd:spline} or
{cmd:discrete}. {cmd:step} also has no effect on the performed
nonlinearity test.
{phang}
{it:cline_options} affect the rendition of the plotted predictions. See
help {it:{help cline_options}}.
{phang}
{opt ciopts(area_options)} specifies details about the rendition of the
plotted confidence interval. See help {it:{help area_options}}.
{phang}
{it:twoway_options} are any of the options documented in help
{it:{help twoway_options}}, excluding {cmd:by()}.
{title:Examples}
{pstd}
Basic usage:
{com}. {stata "use http://www.stata-press.com/data/r10/nlswork4.dta"}
. {stata "regress ln_wage ttl_exp msp"}
. {stata "nlcheck ttl_exp"}
. {stata "nlcheck ttl_exp, graph step"}
. {stata "nlcheck ttl_exp, spline graph"}{txt}
{pstd}
Nonlinear effect:
{com}. {stata "generate ttl_exp2 = ttl_exp^2"}
. {stata "regress ln_wage ttl_exp ttl_exp2 msp"}
. {stata "nlcheck ttl_exp ttl_exp2, graph step bin(20)"}{txt}
{pstd}
Discrete predictor:
{com}. {stata "regress ln_wage ttl_exp msp year"}
. {stata "nlcheck year, discrete graph"}{txt}
{pstd}
Logit model:
{com}. {stata "sysuse auto"}
. {stata "logit foreign price mpg"}
. {stata "nlcheck price, spline knots(3) graph"}{txt}
{pstd}
Multinomial logit:
{com}. {stata "mlogit rep78 mpg if rep78>=3"}
. {stata "nlcheck mpg, bin(4) graph equation(5)"}{txt}
{title:Returned results}
{pstd}Scalars{p_end}
{synoptset 17 tabbed}{...}
{synopt:{cmd:r(p)}}two-sided p-value{p_end}
{synopt:{cmd:r(F)} or {cmd:r(chi2)}}F statistic or chi-squared {p_end}
{synopt:{cmd:r(df)}}degrees of freedom{p_end}
{synopt:{cmd:r(df_r)}}residual degrees of freedom (some models){p_end}
{synopt:{cmd:r(cut}{it:#}{cmd:)}}value of the {it:#}th cut point or spline knot{p_end}
{synopt:{cmd:r(levels)}}list of distinct values of discrete predictor{p_end}
{title:Author}
{pstd}
Ben Jann, ETH Zurich, jannb@ethz.ch
{pstd}
Thanks for citing this software as follows:
{pmore}
Jann, B. (2008). nlcheck: Stata module to check linearity assumption
after model estimation. Available from http://ideas.repec.org/.
{title:Also see}
{psee}
Online: help {help estcom}, {helpb test}, {helpb adjust}