{smcl}
{* 24jan2009}{...}
{hi:help pspline}
{hline}
{title:Title}
{pstd}{hi:pspline} {hline 2} Penalized spline scatterplot smoother based on {cmd:xtmixed}
{title:Syntax}
{p 8 15 2}
{cmd:pspline} {it:{help varname:yvar}} {it:{help varname:xvar}} [{varlist}] {ifin}
[{cmd:,}
{help mesmooth##opt:{it:options}}
]
{synoptset 25 tabbed}{...}
{marker opt}{synopthdr}
{synoptline}
{syntab :Main}
{synopt :{opt d:egree(#)}}degree of spline; default is 1
{p_end}
{synopt :{opt nk:nots(#)}}number of knots; default is min(int(U/4), 35) where U is
the number of distinct values of {it:xvar}
{p_end}
{synopt :{opth k:nots(numlist)}}exact location of knots
{p_end}
{synopt :{opt al:pha(#)}}significance level for pilot goodness-of-fit test
{p_end}
{synopt :{opt force}}force penalized spline estimation
{p_end}
{synopt :{cmd:at(}{varname} {ifin}{cmd:)}}obtain the smooth at the values
of {varname}
{p_end}
{synopt :{opth g:enerate(newvar)}}store smoothed fit in {newvar}
{p_end}
{synopt :{opt r:eplace}}overwrite existing variable
{p_end}
{synopt :{opt nopen:alty}}do not apply a roughness penalty; treat spline
coefficients as fixed effects
{p_end}
{synopt :{opt dis:crete}}treat {it:xvar} as a factor variable
{p_end}
{synopt :{cmdab:estop:ts(}{it:{help xtmixed:options}}{cmd:)}}estimation options as documented
in help {helpb xtmixed}
{p_end}
{synopt :{opt noi:sily}}display estimation output
{p_end}
{synopt :{opt nogr:aph}}suppress graph
{p_end}
{synopt :{opt nosc:atter}}suppress scatterplot only
{p_end}
{synopt :{opt noknot:pos}}suppress ticks indicating knot positions
{p_end}
{syntab :Scatterplot}
{synopt :{it:{help marker_options}}}change look of markers (color, size, etc.)
{p_end}
{synopt :{it:{help marker_label_options}}}add marker labels; change look or position
{p_end}
{syntab :Smoothed line}
{synopt :{opth lineop:ts(cline_options)}}affect rendition of the smoothed line
{p_end}
{syntab :Add plots}
{synopt :{opth "addplot(addplot_option:plot)"}}add other plots to the generated graph
{p_end}
{syntab :Y axis, X axis, Titles, Legend, Overall}
{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:pspline} uses {cmd:xtmixed} to fit a penalized spline regression of
{it:yvar} on {it:xvar} as discussed in Ruppert et al. (2003) and plots the
function. The knots of the spline are positioned at equally spaced
quantiles of the distinct values of {it:xvar}.
{pstd}
{cmd:pspline} is an automatic smoother in that the optimal degree of smoothing
is determined from the data by (restricted) maximum likelihood.
{pstd}
Specify {it:varlist} to adjust for additional covariates and plot partial
residuals.
{pstd}
To circumvent convergence problems in situations where there is only little
deviation in the data from a simple parametric model (e.g. a linear model
if degree=1, a quadratic model if degree=2), {cmd:pspline} performs
a pilot goodness-of-fit (GOF) test for the parametric model. The GOF test
is implemented as a Wald test of the spline terms in a non-penalized
model (see the {cmd:nopenalty} option). A low p-value indicates that there
is a lot of evidence against the parametric model. {cmd:pspline} uses the penalized
spline model only if the p-value is smaller than 0.3 (or as set
by {cmd:alpha()}) and otherwise sticks with the parametric model. Specify
{cmd:force} to skip the test and enforce the penalized spline model.
{title:Options}
{dlgtab:Main}
{phang} {opt degree(#)} specifies the degree of the spline to be used in
the smoothing. The default is {cmd:degree(1)} (linear splines), resulting
in a piecewise linear smooth. Use {cmd:degree(2)} (quadratic splines) for a
continuous smooth (i.e. a smooth with a continuous first
derivative). {cmd:degree(0)} results in a step function.
{phang} {opt nknots(#)} specifies the number of knots of the spline. The
default is min(int(U/4), 35) where U is the number of distinct values of
{it:xvar}. {cmd:nknots(0)} is allowed and causes a parametric model
without splines to be fitted. This is equivalent to fitting a polynomial
model using {helpb regress} (i.e. a linear model if degree=1, a quadratic
model if degree=2, etc.).
{phang}
{opth knots(numlist)} specifies the exact locations of knots of the spline. The
default is to position the knots at equally spaced quantiles of the distinct
values of {it:xvar}. {cmd:nknots()} is not allowed if {cmd:knots()}
is specified.
{phang}
{opt alpha(#)} sets the significance level for the pilot goodness-of-fit test
(see description above). The default is {cmd:alpha(0.3)}.
{phang}
{opt force} skips the pilot goodness-of-fit test and enforces estimation of the
penalized spline model.
{phang}{cmd:at(}{varname} {ifin}{cmd:)} obtains the smoothed fit at the
values of {it:varname}. The default is to obtain the fit at the
values of {it:xvar}. The fit at the values of {it:varname} is computed by
linear interpolation (or extrapolation) from the fit at the values of {it:xvar}.
{phang}
{opth generate(newvar)} stores the smoothed values in
{it:newvar}.
{phang}
{opt replace} permits {cmd:pspline} to overwrite an existing variable.
{phang}
{opt nopenalty} fits a non-penalized spline smooth. This is accomplished by
treating the spline coefficients as fixed instead of random in {helpb xtmixed}
and is equivalent to fitting a spline model using {helpb regress}.
{phang}
{opt discrete} causes {it:xvar} to be treated as a factor variable and fits a model
containing a random effect among the levels of {it:xvar} instead of a
spline. {cmd:nknots()}, {cmd:knots()}, and {cmd:at()} are not allowed if
{cmd:discrete} is specified.
{phang}
{opt estopts(options)} specified options to be passed through to {helpb xtmixed}.
{phang}
{opt noisily} causes output from {helpb xtmixed} to be displayed.
{phang}
{opt nograph} suppresses drawing the graph of the estimated smooth.
{phang}
{opt noscatter} suppresses graphing a scatterplot of the observed data or partial
residuals.
{phang}{opt noknot:pos} suppresses the ticks indicating the knot positions.
{dlgtab:Scatterplot}
{phang}
{it:marker_options} affect the rendition of markers drawn at the plotted points,
including their shape, size, color, and outline; see {manhelpi marker_options G}.
{phang}
{it:marker_label_options} specify if and how the markers are to be labeled; see
{manhelpi marker_label_options G}.
{dlgtab:Smoothed line}
{phang}
{opt lineopts(cline_options)} affects the rendition of the smoothed
line; see {manhelpi cline_options G}.
{dlgtab:Add plots}
{phang}
{opt addplot(plot)} provides a way to add other plots to the generated graph;
see {manhelpi addplot_option G}.
{dlgtab:Y axis, X axis, Titles, Legend, Overall}
{phang}
{it:twoway_options} are any of the options documented in
{manhelpi twoway_options G}, excluding {opt by()}.
These include options for titling the
graph (see {manhelpi title_options G}) and for saving the graph to disk
(see {manhelpi saving_option G}).
{title:Examples}
{pstd}Example using the auto data:
{com}. {stata sysuse auto}
{com}. {stata pspline price mpg} {txt}// piecewise linear
{com}. {stata pspline price mpg, degree(0)} {txt}// step function
{com}. {stata pspline price mpg, degree(2)} {txt}// continuous
{com}. {stata pspline price mpg weight foreign, degree(2)} {txt}// covariate adjustment
{txt}
{pstd}Graph on titlepage of Ruppert et al. (2003):
{com}. {stata "use http://fmwww.bc.edu/repec/bocode/l/lidar.dta"}
{com}. {stata pspline logratio range}
{txt}
{pstd}The motorcycle data:
{com}. {stata webuse motorcycle}
{com}. {stata pspline accel time, d(2)}
{txt}
{title:Saved results}
{pstd}{cmd:pspline} returns the results from {helpb xtmixed} in {cmd:e()} and
saves the following in {cmd:r()}:
{synoptset 15 tabbed}{...}
{p2col 5 15 19 2: Scalars}{p_end}
{synopt:{cmd:r(degree)}}degree of spline
{p_end}
{synopt:{cmd:r(nknots)}}number of knots
{p_end}
{synopt:{cmd:r(alpha)}}significance level for pilot GOF test
{p_end}
{synopt:{cmd:r(gof_chi2)}}chi-squared of pilot GOF test
{p_end}
{synopt:{cmd:r(gof_df)}}degrees of freedom of pilot GOF test
{p_end}
{synopt:{cmd:r(gof_p)}}p-value of pilot GOF test
{p_end}
{synoptset 15 tabbed}{...}
{p2col 5 15 19 2: Macros}{p_end}
{synopt:{cmd:r(model)}}{cmd:penalized}, {cmd:parametric}, or {cmd:non-penalized}
{p_end}
{synopt:{cmd:r(discrete)}}{cmd:discrete} or empty
{p_end}
{synoptset 15 tabbed}{...}
{p2col 5 15 19 2: Matrix}{p_end}
{synopt:{cmd:r(knots)}}knot positions
{p_end}
{title:References}
{phang}
Ruppert, D., M. P. Wand, and R. J. Carroll (2003). Semiparametric Regression.
Cambridge University Press.
{title:Authors}
{pstd}
Ben Jann, ETH Zurich, jannb@ethz.ch
{pstd}
Roberto G. Gutierrez, StataCorp., rgutierrez@stata.com
{pstd}
Thanks for citing this software as follows:
{pmore}
Jann, B., and R. Gutierrez. 2008. pspline: Stata module providing a
penalized spline scatterplot smoother based on linear mixed model
technology. Available from
http://ideas.repec.org/c/boc/bocode/s456972.html.
{title:Also see}
{psee}
Online: help for
{helpb xtmixed},
{helpb lowess},
{helpb lpoly}