neuronet 6.0.0 → 6.0.1

data/lib/neuronet.rb

@@ -1,8 +1,20 @@
 # Neuronet module
 module Neuronet
-  VERSION = '6.0.0'
-
-  # The squash function for Neuronet is the sigmoid function.
+  VERSION = '6.0.1'
+
+  # An artificial neural network uses a squash function
+  # to determine the activation value of a neuron.
+  # The squash function for Neuronet is the
+  # [Sigmoid function](http://en.wikipedia.org/wiki/Sigmoid_function)
+  # which sets the neuron's activation value between 1.0 and 0.0.
+  # This activation value is often thought of on/off or true/false.
+  # For classification problems, activation values near one are considered true
+  # while activation values near 0.0 are considered false.
+  # In Neuronet I make a distinction between the neuron's activation value and
+  # it's representation to the problem.
+  # This attribute, activation, need never appear in an implementation of Neuronet, but
+  # it is mapped back to it's unsquashed value every time
+  # the implementation asks for the neuron's value.
   # One should scale the problem with most data points between -1 and 1,
   # extremes under 2s, and no outbounds above 3s.
   # Standard deviations from the mean is probably a good way to figure the scale of the problem.
@@ -14,13 +26,23 @@ module Neuronet
     Math.log(squashed / (1.0 - squashed))
   end
 
-  # By default, Neuronet builds a zeroed network.
-  # Noise adds random fluctuations to create a search for minima.
+  # Although the implementation is free to set all parameters for each neuron,
+  # Neuronet by default creates zeroed neurons.
+  # Association between inputs and outputs are trained, and
+  # neurons differentiate from each other randomly.
+  # Differentiation among neurons is achieved by noise in the back-propagation of errors.
+  # This noise is provided by Neuronet.noise.
+  # I chose rand + rand to give the noise an average value of one and a bell shape distribution.
   def self.noise
     rand + rand
   end
 
-  # A Node, used for the input layer.
+  # In Neuronet, there are two main types of objects: Nodes and Connections.
+  # A Node has a value which the implementation can set.
+  # A plain Node instance is used primarily as input neurons, and
+  # its value is not changed by training.
+  # It is a terminal for backpropagation of errors.
+  # Nodes are used for the input layer.
   class Node
     attr_reader :activation
     # A Node is constant (Input)
@@ -47,7 +69,9 @@ module Neuronet
     end
   end
 
-  # A weighted connection to a neuron (or node).
+  # Connections between neurons (and nodes) are there own separate objects.
+  # In Neuronet, a neuron contains it's bias, and a list of it's connections.
+  # Each connection contains it's weight (strength) and connected node.
   class Connection
     attr_accessor :node, :weight
     def initialize(node, weight=0.0)
@@ -59,21 +83,32 @@ module Neuronet
       @node.activation * @weight
     end
 
-    # Updates and returns the value of the connection.
-    # Updates the connected node.
+    # Connection#update returns the updated value of a connection,
+    # which is the weighted updated activation of
+    # the node it's connected to ( weight * node.update ).
+    # This method is the one to use
+    # whenever the value of the inputs are changed (right after training).
+    # Otherwise, both update and value should give the same result.
+    # Use Connection#value when back calculations are not needed instead.
     def update
       @node.update * @weight
     end
 
-    # Adjusts the connection weight according to error and
-    # backpropagates the error to the connected node.
+    # Connectoin#backpropagate modifies the connection's weight
+    # in proportion to the error given and passes that error
+    # to its connected node via the node's backpropagate method.
     def backpropagate(error)
       @weight += @node.activation * error * Neuronet.noise
       @node.backpropagate(error)
     end
   end
 
-  # A Neuron with bias and connections
+  # A Neuron is a Node with some extra features.
+  # It adds two attributes: connections, and bias.
+  # The connections attribute is a list of
+  # the neuron's connections to other neurons (or nodes).
+  # A neuron's bias is it's kicker (or deduction) to it's activation value,
+  # a sum of its connections values.
   class Neuron < Node
     attr_reader :connections
     attr_accessor :bias
@@ -84,33 +119,54 @@ module Neuronet
     end
 
     # Updates the activation with the current value of bias and updated values of connections.
+    # If you're not familiar with ruby's Array::inject method,
+    # it is a Ruby way of doing summations. Checkout:
+    # [Jay Field's Thoughts on Ruby: inject](http://blog.jayfields.com/2008/03/ruby-inject.html)
+    # [Induction ( for_all )](http://carlosjhr64.blogspot.com/2011/02/induction.html)
     def update
       self.value = @bias + @connections.inject(0.0){|sum,connection| sum + connection.update}
     end
 
-    # Updates the activation with the current values of bias and connections
-    # For when connections are already updated.
+    # For when connections are already updated,
+    # Neuron#partial updates the activation with the current values of bias and connections.
+    # It is not always necessary to burrow all the way down to the terminal input node
+    # to update the current neuron if it's connected neurons have all been updated.
+    # The implementation should set it's algorithm to use partial
+    # instead of update as update will most likely needlessly update previously updated neurons.
     def partial
       self.value = @bias + @connections.inject(0.0){|sum,connection| sum + connection.value}
     end
 
-    # Adjusts bias according to error and
-    # backpropagates the error to the connections.
+    # The backpropagate method modifies
+    # the neuron's bias in proportion to the given error and
+    # passes on this error to each of its connection's backpropagate method.
+    # While updates flows from input to output,
+    # back-propagation of errors flows from output to input.
     def backpropagate(error)
+      # Adjusts bias according to error and...
       @bias += error * Neuronet.noise
+      # backpropagates the error to the connections.
       @connections.each{|connection| connection.backpropagate(error)}
     end
 
     # Connects the neuron to another node.
     # Updates the activation with the new connection.
-    # The default weight=0 means there is no initial association
+    # The default weight=0 means there is no initial association.
+    # The connect method is how the implementation adds a connection,
+    # the way to connect the neuron to another.
+    # To connect neuron out to neuron in, for example, it is:
+    #	in = Neuronet::Neuron.new
+    #	out = Neuronet::Neuron.new
+    #	out.connect(in)
+    # Think output connects to input.
     def connect(node, weight=0.0)
       @connections.push(Connection.new(node,weight))
       update
     end
   end
 
-  # This is the Input Layer
+  # Neuronet::InputLayer is an Array of Neuronet::Node's.
+  # It can be used for the input layer of a feed forward network.
   class InputLayer < Array
     def initialize(length) # number of nodes
       super(length)
@@ -123,7 +179,8 @@ module Neuronet
     end
   end
 
-  # Just a regular Layer
+  # Just a regular Layer.
+  # InputLayer is to Layer what Node is to Neuron.
   class Layer < Array
     def initialize(length)
       super(length)
@@ -161,6 +218,16 @@ module Neuronet
   # A Feed Forward Network
   class FeedForward < Array
     # Whatchamacallits?
+    # The learning constant is given different names...
+    # often some greek letter.
+    # It's a small number less than one.
+    # Ideally, it divides the errors evenly among all contributors.
+    # Contributors are the neurons' biases and the connections' weights.
+    # Thus if one counts all the contributors as N,
+    # the learning constant should be at most 1/N.
+    # But there are other considerations, such as how noisy the data is.
+    # In any case, I'm calling this N value FeedForward#mu.
+    # 1/mu is used for the initial default value for the learning constant.
     def mu
       sum = 1.0
       1.upto(self.length-1) do |i|
@@ -169,16 +236,33 @@ module Neuronet
       end
       return sum
     end
+    # Given that the learning constant is initially set to 1/mu as defined above,
+    # muk gives a way to modify the learning constant by some factor, k.
+    # In theory, when there is no noice in the target data, k can be set to 1.0.
+    # If the data is noisy, k is set to some value less than 1.0.
     def muk(k=1.0)
       @learning = k/mu
     end
+    # Given that the learning constant can be modified by some factor k with #muk,
+    # #num gives an alternate way to express
+    # the k factor in terms of some number n greater than 1, setting k to 1/sqrt(n).
+    # I believe that the optimal value for the learning constant
+    # for a training set of size n is somewhere between #muk(1) and #num(n).
+    # Whereas the learning constant can be too high,
+    # a low learning value just increases the training time.
     def num(n)
-      @learning = 1.0/(Math.sqrt(1.0+n) * mu)
+      muk(1.0/(Math.sqrt(n)))
     end
 
     attr_reader :in, :out
     attr_reader :yin, :yang
     attr_accessor :learning
+
+    # I find very useful to name certain layers:
+    #	[0]	@in	Input Layer
+    #	[1]	@yin	Tipically the first middle layer
+    #	[-2]	@yang	Tipically the last middle layer
+    #	[-1]	@out	Output Layer
     def initialize(layers)
       super(length = layers.length)
       @in = self[0] = Neuronet::InputLayer.new(layers[0])
@@ -222,11 +306,23 @@ module Neuronet
     end
   end
 
-  # Scales the problem
+  # Neuronet::Scale is a class to
+  # help scale problems to fit within a network's "field of view".
+  # Given a list of values, it finds the minimum and maximum values and
+  # establishes a mapping to a scaled set of numbers between minus one and one (-1,1).
   class Scale
     attr_accessor :spread, :center
     attr_writer :init
 
+    # If the value of center is provided, then
+    # that value will be used instead of
+    # calculating it from the values passed to method set.
+    # Likewise, if spread is provided, that value of spread will be used.
+    # The attribute @init flags if
+    # there is a initiation phase to the calculation of @spread and @center.
+    # For Scale, @init is true and the initiation phase calculates
+    # the intermediate values @min and @max (the minimum and maximum values in the data set).
+    # It's possible for subclasses of Scale, such as Gaussian, to not have this initiation phase.
     def initialize(factor=1.0,center=nil,spread=nil)
       @factor,@center,@spread = factor,center,spread
       @centered, @spreaded = center.nil?, spread.nil?
@@ -272,7 +368,10 @@ module Neuronet
     alias unmapped_output unmapped
   end
 
-  # Normal Distribution
+  # "Normal Distribution"
+  # Gaussian subclasses Scale and is used exactly the same way.
+  # The only changes are that it calculates the arithmetic mean (average) for center and
+  # the standard deviation for spread.
   class Gaussian < Scale
     def initialize(factor=1.0,center=nil,spread=nil)
       super(factor, center, spread)
@@ -290,7 +389,8 @@ module Neuronet
     end
   end
 
-  # Log-Normal Distribution
+  # "Log-Normal Distribution"
+  # LogNormal subclasses Gaussian to transform the values to a logarithmic scale. 
   class LogNormal < Gaussian
     def initialize(factor=1.0,center=nil,spread=nil)
       super(factor, center, spread)
@@ -313,7 +413,11 @@ module Neuronet
     alias unmapped_output unmapped
   end
 
-  # Series Network for similar input/output values
+  # ScaledNetwork is a subclass of FeedForwardNetwork.
+  # It automatically scales the problem given to it
+  # by using a Scale type instance set in @distribution.
+  # The attribute, @distribution, is set to Neuronet::Gausian.new by default,
+  # but one can change this to Scale, LogNormal, or one's own custom mapper.
   class ScaledNetwork < FeedForward
     attr_accessor :distribution
 
@@ -331,6 +435,12 @@ module Neuronet
       super(@distribution.mapped_input(inputs))
     end
 
+    # ScaledNetwork#reset works just like FeedForwardNetwork's set method,
+    # but calls distribution.set( values ) first.
+    # Sometimes you'll want to set the distribution
+    # with the entire data set and the use set,
+    # and then there will be times you'll want to
+    # set the distribution with each input and use reset.
     def reset(inputs)
       @distribution.set(inputs)
       set(inputs)
@@ -345,13 +455,17 @@ module Neuronet
     end
   end
 
-  # A Perceptron Hybrid
+  # A Perceptron Hybrid,
+  # Tao directly connects the output layer to the input layer.
   module Tao
+    # Tao's extra connections adds to mu.
     def mu
       sum = super
       sum += self.first.length * self.last.length
       return sum
     end
+    # Tao.bless connects the network's output layer to the input layer,
+    # extends it with Tao, and modifies the learning constant if needed.
     def self.bless(myself)
       # @out directly connects to @in
       myself.out.connect(myself.in)
@@ -364,8 +478,13 @@ module Neuronet
     end
   end
 
-  # sets @yin to initially mirror @in
+  # Yin is a network wich has its @yin layer initially mirroring @in.
   module Yin
+    # Yin.bless sets the bias of each @yin[i] to 0.5, and
+    # the weight of pairing (@yin[i], @in[i]) connections to one.
+    # This makes @yin initially mirror @in.
+    # The pairing is done starting with (@yin[0], @in[0]).
+    # That is, starting with (@yin.first, @in.first).
     def self.bless(myself)
       yin = myself.yin
       if yin.length < (in_length = myself.in.length)
@@ -381,11 +500,18 @@ module Neuronet
     end
   end
 
-  # sets @out to initially mirror @yang
+  # Yang is a network wich has its @out layer initially mirroring @yang.
   module Yang
+    # Yang.bless sets the bias of each @yang[i] to 0.5, and
+    # the weight of pairing (@out[i], @yang[i]) connections to one.
+    # This makes @out initially mirror @yang.
+    # The pairing is done starting with (@out[-1], @yang[-1]).
+    # That is, starting with (@out.last, @yang.last).
     def self.bless(myself)
       offset = myself.yang.length - (out_length = (out = myself.out).length)
       raise "Last hidden layer, yang, needs to have at least the same length as output" if offset < 0
+      # Although the algorithm here is not as described,
+      # the net effect to is pair @out.last with @yang.last, and so on down.
       0.upto(out_length-1) do |index|
         node = out[index]
         node.connections[offset+index].weight = 1.0
@@ -395,9 +521,7 @@ module Neuronet
     end
   end
 
-  # And convenient composites...
-
-  # Yin-Yang-ed  :))
+  # A Yin Yang composite provided for convenience.
   module YinYang
     def self.bless(myself)
       Yin.bless(myself)
@@ -406,6 +530,7 @@ module Neuronet
     end
   end
 
+  # A Tao Yin Yang composite provided for convenience.
   module TaoYinYang
     def self.bless(myself)
       Tao.bless(myself)
@@ -415,6 +540,7 @@ module Neuronet
     end
   end
 
+  # A Tao Yin composite provided for convenience.
   module TaoYin
     def self.bless(myself)
       Tao.bless(myself)
@@ -423,6 +549,7 @@ module Neuronet
     end
   end
 
+  # A Tao Yang composite provided for convenience.
   module TaoYang
     def self.bless(myself)
       Tao.bless(myself)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: neuronet
 version: !ruby/object:Gem::Version
-  version: 6.0.0
+  version: 6.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-16 00:00:00.000000000 Z
+date: 2013-06-18 00:00:00.000000000 Z
 dependencies: []
 description: Build custom neural networks. 100% 1.9 Ruby.
 email: carlosjhr64@gmail.com