\Header{ppr}{Projection Pursuit Regression}
\methalias{ppr.default}{ppr}
\methalias{ppr.formula}{ppr}
\keyword{regression}{ppr}
\begin{Description}\relax
Fit a projection pursuit regression model.
\end{Description}
\begin{Usage}
\begin{verbatim}
ppr(x, ...)

## S3 method for class 'formula':
ppr(formula, data, weights, subset, na.action,
    contrasts = NULL, ..., model = FALSE)

## Default S3 method:
ppr(x, y, weights = rep(1,n),
    ww = rep(1,q), nterms, max.terms = nterms, optlevel = 2,
    sm.method = c("supsmu", "spline", "gcvspline"),
    bass = 0, span = 0, df = 5, gcvpen = 1, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{formula}] a formula specifying one or more numeric response variables and the
explanatory variables.

\item[\code{x}] numeric matrix of explanatory variables.  Rows represent observations, and
columns represent variables.  Missing values are not accepted.

\item[\code{y}] numeric matrix of response variables.  Rows represent observations, and
columns represent variables.  Missing values are not accepted.

\item[\code{nterms}] number of terms to include in the final model.
\item[\code{data}] data frame from which variables specified in \code{formula} are
preferentially to be taken.

\item[\code{weights}] a vector of weights \code{w\_i} for each \emph{case}.
\item[\code{ww}] a vector of weights for each \emph{response}, so the fit criterion is
the sum over case \code{i} and responses \code{j} of
\code{w\_i ww\_j (y\_ij - fit\_ij)\textasciicircum{}2} divided by the sum of \code{w\_i}.

\item[\code{subset}] an index vector specifying the cases to be used in the training
sample.  (NOTE: If given, this argument must be named.)

\item[\code{na.action}] a function to specify the action to be taken if \code{\Link{NA}}s are
found. The default action is given by \code{getOption("na.action")}.
(NOTE: If given, this argument must be named.)

\item[\code{contrasts}] the contrasts to be used when any factor explanatory variables are coded.

\item[\code{max.terms}] maximum number of terms to choose from when building the model.

\item[\code{optlevel}] integer from 0 to 3 which determines the thoroughness of an
optimization routine in the SMART program. See the \bold{Details} section.

\item[\code{sm.method}] the method used for smoothing the ridge functions.  The default is to
use Friedman's super smoother \code{supsmu}.  The alternatives are to use
the smoothing spline code underlying \code{smooth.spline}, either with a
specified (equivalent) degrees of freedom for each ridge functions, or
to allow the smoothness to be chosen by GCV.

\item[\code{bass}] super smoother bass tone control used with automatic span selection
(see \code{supsmu}); the range of values is 0 to 10, with larger values
resulting in increased smoothing.

\item[\code{span}] super smoother span control (see \code{supsmu}).  The default, \code{0},
results in automatic span selection by local cross validation. \code{span}
can also take a value in \code{(0, 1]}.

\item[\code{df}] if \code{sm.method} is \code{"spline"} specifies the smoothness of
each ridge term via the requested equivalent degrees of freedom.

\item[\code{gcvpen}] if \code{sm.method} is \code{"gcvspline"} this is the penalty used
in the GCV selection for each degree of freedom used.

\item[\code{...}] arguments to be passed to or from other methods.
\item[\code{model}] logical.  If true, the model frame is returned.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The basic method is given by Friedman (1984), and is essentially the
same code used by S-PLUS's \code{ppreg}.  This code is extremely
sensitive to the compiler used.

The algorithm first adds up to \code{max.terms} ridge terms one at a
time; it will use less if it is unable to find a term to add that makes
sufficient difference.  It then removes the least
\dQuote{\emph{important}} term at each step until \code{nterm} terms
are left.

The levels of optimization (argument \code{optlevel})
differ in how thoroughly the models are refitted during this process.
At level 0 the existing ridge terms are not refitted.  At level 1
the projection directions are not refitted, but the ridge
functions and the regression coefficients are.
Levels 2 and 3 refit all the terms and are equivalent for one
response; level 3 is more careful to re-balance the contributions
from each regressor at each step and so is a little less likely to
converge to a saddle point of the sum of squares criterion.
\end{Details}
\begin{Value}
A list with the following components, many of which are for use by the
method functions.

\begin{ldescription}
\item[\code{call}] the matched call
\item[\code{p}] the number of explanatory variables (after any coding)
\item[\code{q}] the number of response variables
\item[\code{mu}] the argument \code{nterms}
\item[\code{ml}] the argument \code{max.terms}
\item[\code{gof}] the overall residual (weighted) sum of squares for the
selected model
\item[\code{gofn}] the overall residual (weighted) sum of squares against the
number of terms, up to \code{max.terms}.  Will be invalid (and zero)
for less than \code{nterms}.
\item[\code{df}] the argument \code{df}
\item[\code{edf}] if \code{sm.method} is \code{"spline"} or \code{"gcvspline"}
the equivalent number of degrees of freedom for each ridge term used.
\item[\code{xnames}] the names of the explanatory variables
\item[\code{ynames}] the names of the response variables
\item[\code{alpha}] a matrix of the projection directions, with a column for
each ridge term
\item[\code{beta}] a matrix of the coefficients applied for each response to
the ridge terms: the rows are the responses and the columns the ridge terms
\item[\code{yb}] the weighted means of each response
\item[\code{ys}] the overall scale factor used: internally the responses are
divided by \code{ys} to have unit total weighted sum of squares.
\item[\code{fitted.values}] the fitted values, as a matrix if \code{q > 1}.
\item[\code{residuals}] the residuals, as a matrix if \code{q > 1}.
\item[\code{smod}] internal work array, which includes the ridge functions
evaluated at the training set points.
\item[\code{model}] (only if \code{model=TRUE}) the model frame.
\end{ldescription}
\end{Value}
\begin{References}\relax
Friedman, J. H. and Stuetzle, W. (1981)
Projection pursuit regression.
\emph{Journal of the American Statistical Association},
\bold{76}, 817--823.

Friedman, J. H. (1984)
SMART User's Guide.
Laboratory for Computational Statistics, Stanford University Technical
Report No. 1.

Venables, W. N. \& Ripley, B. D. (2002)
\emph{Modern Applied Statistics with S.}  Springer.
\end{References}
\begin{SeeAlso}\relax
\code{\Link{plot.ppr}}, \code{\Link{supsmu}}, \code{\Link{smooth.spline}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
# Note: your numerical values may differ
data(rock)
attach(rock)
area1 <- area/10000; peri1 <- peri/10000
rock.ppr <- ppr(log(perm) ~ area1 + peri1 + shape,
                data = rock, nterms = 2, max.terms = 5)
rock.ppr
# Call:
# ppr.formula(formula = log(perm) ~ area1 + peri1 + shape, data = rock,
#     nterms = 2, max.terms = 5)
#
# Goodness of fit:
#  2 terms  3 terms  4 terms  5 terms
# 8.737806 5.289517 4.745799 4.490378

summary(rock.ppr)
# .....  (same as above)
# .....
#
# Projection direction vectors:
#       term 1      term 2
# area1  0.34357179  0.37071027
# peri1 -0.93781471 -0.61923542
# shape  0.04961846  0.69218595
#
# Coefficients of ridge terms:
#    term 1    term 2
# 1.6079271 0.5460971

par(mfrow=c(3,2))# maybe: , pty="s")
plot(rock.ppr, main="ppr(log(perm)~ ., nterms=2, max.terms=5)")
plot(update(rock.ppr, bass=5), main = "update(..., bass = 5)")
plot(update(rock.ppr, sm.method="gcv", gcvpen=2),
     main = "update(..., sm.method=\"gcv\", gcvpen=2)")
cbind(perm=rock$perm, prediction=round(exp(predict(rock.ppr)), 1))
detach()
\end{ExampleCode}
\end{Examples}

