.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "AI::Perceptron 3"
.TH AI::Perceptron 3 "2008-01-07" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
AI::Perceptron \- example of a node in a neural network.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use AI::Perceptron;
.Ve
.PP
.Vb 5
\& my $p = AI::Perceptron->new
\&           ->num_inputs( 2 )
\&           ->learning_rate( 0.04 )
\&           ->threshold( 0.02 )
\&           ->weights([ 0.1, 0.2 ]);
.Ve
.PP
.Vb 3
\& my @inputs  = ( 1.3, -0.45 );   # input can be any number
\& my $target  = 1;                # output is always -1 or 1
\& my $current = $p->compute_output( @inputs );
.Ve
.PP
.Vb 1
\& print "current output: $current, target: $target\en";
.Ve
.PP
.Vb 1
\& $p->add_examples( [ $target, @inputs ] );
.Ve
.PP
.Vb 2
\& $p->max_iterations( 10 )->train or
\&   warn "couldn't train in 10 iterations!";
.Ve
.PP
.Vb 2
\& print "training until it gets it right\en";
\& $p->max_iterations( -1 )->train; # watch out for infinite loops
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is meant to show how a single node of a neural network works.
.PP
Training is done by the \fIStochastic Approximation of the Gradient-Descent\fR
model.
.SH "MODEL"
.IX Header "MODEL"
Model of a Perceptron
.PP
.Vb 8
\&              +---------------+
\& X[1] o------ |W[1]      T    |
\& X[2] o------ |W[2] +---------+         +-------------------+
\&  .           | .   |   ___   |_________|    __  Squarewave |_______\e  Output
\&  .           | .   |   \e     |    S    | __|    Generator  |       /
\&  .           | .   |   /__   |         +-------------------+
\& X[n] o------ |W[n] |   Sum   |
\&              +-----+---------+
.Ve
.PP
.Vb 2
\&             S  =  T + Sum( W[i]*X[i] )  as i goes from 1 -> n
\&        Output  =  1 if S > 0; else -1
.Ve
.PP
Where \f(CW\*(C`X[n]\*(C'\fR are the perceptron's \fIinputs\fR, \f(CW\*(C`W[n]\*(C'\fR are the \fIWeights\fR that
get applied to the corresponding input, and \f(CW\*(C`T\*(C'\fR is the \fIThreshold\fR.
.PP
The \fIsquarewave generator\fR just turns the result into a positive or negative
number.
.PP
So in summary, when you feed the perceptron some numeric inputs you get either
a positive or negative output depending on the input's weights and a threshold.
.SH "TRAINING"
.IX Header "TRAINING"
Usually you have to train a perceptron before it will give you the outputs you
expect.  This is done by giving the perceptron a set of examples containing the
output you want for some given inputs:
.PP
.Vb 4
\&    -1 => -1, -1
\&    -1 =>  1, -1
\&    -1 => -1,  1
\&     1 =>  1,  1
.Ve
.PP
If you've ever studied boolean logic, you should recognize that as the truth
table for an \f(CW\*(C`AND\*(C'\fR gate (ok so we're using \-1 instead of the commonly used 0,
same thing really).
.PP
You \fItrain\fR the perceptron by iterating over the examples and adjusting the
\&\fIweights\fR and \fIthreshold\fR by some value until the perceptron's output matches
the expected output of each example:
.PP
.Vb 2
\&    while some examples are incorrectly classified
\&        update weights for each example that fails
.Ve
.PP
The value each weight is adjusted by is calculated as follows:
.PP
.Vb 1
\&    delta[i] = learning_rate * (expected_output - output) * input[i]
.Ve
.PP
Which is know as a negative feedback loop \- it uses the current output as an
input to determine what the next output will be.
.PP
Also, note that this means you can get stuck in an infinite loop.  It's not a
bad idea to set the maximum number of iterations to prevent that.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new( [%args] )" 4
.IX Item "new( [%args] )"
Creates a new perceptron with the following default properties:
.Sp
.Vb 4
\&    num_inputs    = 1
\&    learning_rate = 0.01
\&    threshold     = 0.0
\&    weights       = empty list
.Ve
.Sp
Ideally you should use the accessors to set the properties, but for backwards
compatability you can still use the following arguments:
.Sp
.Vb 3
\&    Inputs => $number_of_inputs  (positive int)
\&    N      => $learning_rate     (float)
\&    W      => [ @weights ]       (floats)
.Ve
.Sp
The number of elements in \fIW\fR must be equal to the number of inputs plus one.
This is because older version of AI::Perceptron combined the threshold and the
weights a single list where W[0] was the threshold and W[1] was the first
weight.  Great idea, eh? :)  That's why it's \fI\s-1DEPRECATED\s0\fR.
.SH "ACCESSORS"
.IX Header "ACCESSORS"
.ie n .IP "num_inputs( [ $int ] )" 4
.el .IP "num_inputs( [ \f(CW$int\fR ] )" 4
.IX Item "num_inputs( [ $int ] )"
Set/get the perceptron's number of inputs.
.ie n .IP "learning_rate( [ $float ] )" 4
.el .IP "learning_rate( [ \f(CW$float\fR ] )" 4
.IX Item "learning_rate( [ $float ] )"
Set/get the perceptron's number of inputs.
.IP "weights( [ \e@weights ] )" 4
.IX Item "weights( [ @weights ] )"
Set/get the perceptron's weights (floats).
.Sp
For backwards compatability, returns a list containing the \fIthreshold\fR as the
first element in list context:
.Sp
.Vb 1
\&  ($threshold, @weights) = $p->weights;
.Ve
.Sp
This usage is \fI\s-1DEPRECATED\s0\fR.
.ie n .IP "threshold( [ $float ] )" 4
.el .IP "threshold( [ \f(CW$float\fR ] )" 4
.IX Item "threshold( [ $float ] )"
Set/get the perceptron's number of inputs.
.IP "training_examples( [ \e@examples ] )" 4
.IX Item "training_examples( [ @examples ] )"
Set/get the perceptron's list of training examples.  This should be a list of
arrayrefs of the form:
.Sp
.Vb 1
\&    [ $expected_result => @inputs ]
.Ve
.ie n .IP "max_iterations( [ $int ] )" 4
.el .IP "max_iterations( [ \f(CW$int\fR ] )" 4
.IX Item "max_iterations( [ $int ] )"
Set/get the perceptron's number of inputs, a negative value implies no maximum.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "compute_output( @inputs )" 4
.el .IP "compute_output( \f(CW@inputs\fR )" 4
.IX Item "compute_output( @inputs )"
Computes and returns the perceptron's output (either \-1 or 1) for the given
inputs.  See the above model for more details.
.ie n .IP "add_examples( @training_examples )" 4
.el .IP "add_examples( \f(CW@training_examples\fR )" 4
.IX Item "add_examples( @training_examples )"
Adds the \f(CW@training_examples\fR to to current list of examples.  See
\&\fItraining_examples()\fR for more details.
.ie n .IP "train( [ @training_examples ] )" 4
.el .IP "train( [ \f(CW@training_examples\fR ] )" 4
.IX Item "train( [ @training_examples ] )"
Uses the \fIStochastic Approximation of the Gradient-Descent\fR model to adjust
the perceptron's weights until all training examples are classified correctly.
.Sp
@training_examples can be passed for convenience.  These are passed to
\&\fIadd_examples()\fR.  If you want to re-train the perceptron with an entirely new
set of examples, reset the \fItraining_examples()\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Steve Purkis <spurkis@epn.nu>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1999\-2003 Steve Purkis.  All rights reserved.
.PP
This package is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
.SH "REFERENCES"
.IX Header "REFERENCES"
\&\fIMachine Learning\fR, by Tom M. Mitchell.
.SH "THANKS"
.IX Header "THANKS"
Himanshu Garg <himanshu@gdit.iiit.net> for his bug-report and feedback.
Many others for their feedback.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Statistics::LTU,
AI::jNeural,
AI::NeuralNet::BackProp,
AI::NeuralNet::Kohonen