

   FFiitt NNeeuurraall NNeettwwoorrkkss

        nnet.formula(formula, data=NULL, ...,
                     subset, na.action=na.fail, contrasts=NULL)
        nnet.default(x, y, weights, size, Wts,
                     linout=F, entropy=F, softmax=F,
                     skip=F, rang=0.7, decay=0, maxit=100,
                     Hess=F, trace=T)
        nnet(...)

   AArrgguummeennttss::

    formula: A formula of the form `class ~ x1 + x2 + ...{}'

          x: matrix or data frame of `x' values for examples.

          y: matrix or data frame of target values for exam-
             ples.

    weights: (case) weights for each example -- if missing
             defaults to 1.

       size: number of units in the hidden layer. Can be zero
             if there are skip-layer units.

       data: Data frame from which variables specified in
             `formula' are preferentially to be taken.

     subset: An index vector specifying the cases to be used in
             the training sample.  (NOTE: If given, this argu-
             ment must be named.)

   na.action: A function to specify the action to be taken if
             `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.)

   contrasts: a list of `contrasts' to be used for some or all
             of the factors appearing as variables in the model
             formula.

        Wts: initial parameter vector. If missing chosen at
             random.

     linout: switch for linear output units. Default logistic
             output units.

    entropy: switch for entropy (= maximum conditional likeli-
             hood) fitting.  Default by least-squares.

    softmax: switch for softmax (log-linear model) and maximum
             conditional likelihood fitting. `linout',
             `entropy' and `softmax' are mutually exclusive.

       skip: switch to add skip-layer connections from input to
             output.

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

      decay: parameter for weight decay.  Default 0.

      maxit: maximum number of iterations. Default 100.

       Hess: If true, the Hessian of the measure of fit at the
             best set of weights found is returned as component
             `Hessian'.

      trace: switch for tracing optimization. Default `True''.

   DDeessccrriippttiioonn::

        If the response in `formula' is a factor, an appropri-
        ate classfication 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
        `nnet.default'.

        A quasi-Newton optimizer is used, written in `C'.

   VVaalluuee::

        object of class `nnet' or `nnet.formula'.  Mostly
        internal structure, having components

        wts: the best set of weights found

      value: value of fitting criterion plus weight decay term.

   fitted.values: the fitted values for the training data.

   SSeeee AAllssoo::

        The methods `predict.nnet', `nnet.Hess'.

   EExxaammpplleess::

        data(iris3)# use half the iris data for training
        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){
             ## Compute (Mis)classification table
                true <- max.col(true)
                cres <- max.col(pred)
                table(true, cres)
        }
        # Out of sample classification:
        # Have from 0 to 6 misclassified, out of 75, depending on training (!)
        test.cl(targets[-samp,], predict(ir1, ir[-samp,]))
        cat("Misclassified plant `id's:\n")
        for(n in 1:10) {
          samp <- c(sample(1:50,25), sample(51:100,25), sample(101:150,25))
          print(which(max.col(targets[-samp,]) !=
                   max.col(predict(nnet(ir[samp,], targets[samp,], size=2, rang=0.1,
                               decay=5e-4, maxit=200, trace = FALSE),
                             ir[-samp,]))))
        }

        # or -- using formula / model notation :
        ird <- data.frame(rbind(iris3[,,1], iris3[,,2], iris3[,,3]),
                       species=c(rep("s",50), rep("c", 50), rep("v", 50)))
        ##- still fails in 0.60.1 -- fitted values are NOT  75 x 3 matrix (but should)
        ir.nn2 <- nnet(species ~ ., data=ird, subset=samp, size=2, rang=0.1,
                       decay= 5e-4, maxit= 200)
        predict.nnet(ir.nn2, x= model.matrix(delete.response(ir.nn2$terms),ird[-samp,]),type="class")

        # fails: predict(.) returns NULL
        table(ird$species[-samp], predict(ir.nn2, ird[-samp,], type="class"))

