\HeaderA{nnet}{Fit Neural Networks}{nnet}
\aliasA{add.net}{nnet}{add.net}
\aliasA{coef.nnet}{nnet}{coef.nnet}
\aliasA{eval.nn}{nnet}{eval.nn}
\methaliasA{nnet.default}{nnet}{nnet.default}
\methaliasA{nnet.formula}{nnet}{nnet.formula}
\aliasA{norm.net}{nnet}{norm.net}
\aliasA{print.nnet}{nnet}{print.nnet}
\aliasA{print.summary.nnet}{nnet}{print.summary.nnet}
\aliasA{summary.nnet}{nnet}{summary.nnet}
\keyword{neural}{nnet}
\begin{Description}\relax
Fit single-hidden-layer neural network, possibly with skip-layer connections.
\end{Description}
\begin{Usage}
\begin{verbatim}
nnet(x, ...)

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

## Default S3 method:
nnet(x, y, weights, size, Wts, mask,
     linout = FALSE, entropy = FALSE, softmax = FALSE,
     censored = FALSE, skip = FALSE, rang = 0.7, decay = 0,
     maxit = 100, Hess = FALSE, trace = TRUE, MaxNWts = 1000,
     abstol = 1.0e-4, reltol = 1.0e-8, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{formula}] A formula of the form \code{class \textasciitilde{} x1 + x2 + ...}

\item[\code{x}] matrix or data frame of \code{x} values for examples.

\item[\code{y}] matrix or data frame of target values for examples.

\item[\code{weights}] (case) weights for each example -- if missing defaults to 1.

\item[\code{size}] number of units in the hidden layer. Can be zero if there are skip-layer units.

\item[\code{data}] Data frame from which variables specified in  \code{formula} are
preferentially to be taken.

\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{NA}s are found.
The default action is for the procedure to fail.  An alternative is
na.omit, which leads to rejection of cases with missing values on
any required variable.  (NOTE: If given, this argument must be named.)

\item[\code{contrasts}] a list of contrasts to be used for some or all  of
the  factors  appearing as variables in the model formula.

\item[\code{Wts}] initial parameter vector. If missing chosen at random.

\item[\code{mask}] logical vector indicating which parameters should be optimized (default all).

\item[\code{linout}] switch for linear output units. Default logistic output units.

\item[\code{entropy}] switch for entropy (= maximum conditional likelihood) fitting.
Default by least-squares.

\item[\code{softmax}] switch for softmax (log-linear model) and maximum conditional
likelihood fitting. \code{linout}, \code{entropy}, \code{softmax} and \code{censored} are mutually
exclusive.

\item[\code{censored}] A variant on \code{softmax}, in which non-zero targets mean possible
classes. Thus for \code{softmax} a row of \code{(0, 1, 1)} means one example
each of classes 2 and 3, but for \code{censored} it means one example whose
class is only known to be 2 or 3.

\item[\code{skip}] switch to add skip-layer connections from input to output.

\item[\code{rang}] Initial random weights on [-\code{rang}, \code{rang}].  Value about 0.5 unless the
inputs are large, in which case it should be chosen so that
\code{rang} * max(\code{|x|}) is about 1.

\item[\code{decay}] parameter for weight decay.  Default 0.

\item[\code{maxit}] maximum number of iterations. Default 100.

\item[\code{Hess}] If true, the Hessian of the measure of fit at the best set of weights
found is returned as component \code{Hessian}.

\item[\code{trace}] switch for tracing optimization. Default \code{TRUE}.

\item[\code{MaxNWts}] The maximum allowable number of weights.  There is no intrinsic limit
in the code, but increasing \code{MaxNWts} will probably allow fits that
are very slow and time-consuming (and perhaps uninterruptable).

\item[\code{abstol}] Stop if the fit criterion falls below \code{abstol}, indicating an
essentially perfect fit.

\item[\code{reltol}] Stop if the optimizer is unable to reduce the fit criterion by a
factor of at least \code{1 - reltol}.

\item[\code{...}] arguments passed to or from other methods.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If the response in \code{formula} is a factor, an appropriate classification
network is constructed; this has one output and entropy fit if the
number of levels is two, and a number of outputs equal to the number
of classes and a softmax output stage for more levels.  If the
response is not a factor, it is passed on unchanged to \code{nnet.default}.

Optimization is done via the BFGS method of \code{\LinkA{optim}{optim}}.
\end{Details}
\begin{Value}
object of class \code{"nnet"} or \code{"nnet.formula"}.
Mostly internal structure, but has components

\begin{ldescription}
\item[\code{wts}] the best set of weights found

\item[\code{value}] value of fitting criterion plus weight decay term.

\item[\code{fitted.values}] the fitted values for the training data.

\item[\code{residuals}] the residuals for the training data.

\end{ldescription}
\end{Value}
\begin{References}\relax
Ripley, B. D. (1996)
\emph{Pattern Recognition and Neural Networks.} Cambridge.

Venables, W. N. and Ripley, B. D. (2002)
\emph{Modern Applied Statistics with S.} Fourth edition.  Springer.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{predict.nnet}{predict.nnet}}, \code{\LinkA{nnetHess}{nnetHess}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(iris3)
# use half the iris data
ir <- rbind(iris3[,,1],iris3[,,2],iris3[,,3])
targets <- class.ind( c(rep("s", 50), rep("c", 50), rep("v", 50)) )
samp <- c(sample(1:50,25), sample(51:100,25), sample(101:150,25))
ir1 <- nnet(ir[samp,], targets[samp,], size = 2, rang = 0.1,
            decay = 5e-4, maxit = 200)
test.cl <- function(true, pred){
        true <- max.col(true)
        cres <- max.col(pred)
        table(true, cres)
}
test.cl(targets[-samp,], predict(ir1, ir[-samp,]))

# or
ird <- data.frame(rbind(iris3[,,1], iris3[,,2], iris3[,,3]),
        species = c(rep("s",50), rep("c", 50), rep("v", 50)))
ir.nn2 <- nnet(species ~ ., data = ird, subset = samp, size = 2, rang = 0.1,
               decay = 5e-4, maxit = 200)
table(ird$species[-samp], predict(ir.nn2, ird[-samp,], type = "class"))
\end{ExampleCode}
\end{Examples}