\Header{nnet}{Fit Neural Networks}
\alias{add.net}{nnet}
\alias{coef.nnet}{nnet}
\alias{eval.nn}{nnet}
\methalias{nnet.default}{nnet}
\methalias{nnet.formula}{nnet}
\alias{norm.net}{nnet}
\alias{print.nnet}{nnet}
\alias{print.summary.nnet}{nnet}
\alias{residuals.nnet}{nnet}
\alias{summary.nnet}{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.formula(formula, data=NULL, weights, ...,
             subset, na.action=na.fail, contrasts=NULL)
nnet.default(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 under
Windows).

\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}.

\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}.


A quasi-Newton optimizer is used, written in \code{C}.\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{SeeAlso}\relax
\code{\Link{predict.nnet}}, \code{\Link{nnet.Hess}}\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}

