UserPreferences

Conx Implementation Details


Conx Implementation Details

(!) The Conx code, like all Pyro code, can be found in the SVN repository, specifically right [WWW]here. Advanced Pyro users are encouraged to examine the code whenever you have questions about how something was implemented. You can also see the source code in your site's file system, usually at /usr/local/pyrobot/. The Conx code can be found at pyrobot/brain/conx.py.

This section will explore the details of the Conx implementation. In many of these examples, a sample instance of a Network is used and called net. You can test many of these commands interactively, like:

$ python
>>> from pyrobot.brain.conx import *
>>> net = Network()
>>> net.addLayers(2, 3, 1)  # will add and connect three layers named, by default, "input", "hidden", "output"
>>> net.display()
>>> net.displayConnections()

Network Class

The Network class contains all of the parameters and methods needed to run a neural network. This class relies heavily on both Layer and Connection classes.

/!\ As a general rule, aside from setting targets and activations manually in complicated networks, the Network class methods should always be used. For example, both Layer and Connection classes have methods called changeSize(). Calling this method at either the Layer or Connection level would be a mistake, however; the Network class method changeSize() should always be called instead.

Building a Network
Network() Initializes a network object.
SRN() Initializes a Simple Recurrent Network (Elman) object.
addLayers(size, size, ...) Adds a series of layers, with standard names (such as "input", "hidden", and "output") and connects them up.
addLayer('layerName', size) Adds a layer to the network. Ex. network.addLayer('hidden',3) will add a layer with name 'hidden' and size 3 to network object.
connect('fromLayer', 'toLayer') Creates a connection between the layer with name 'fromLayer and the layer with name 'toLayer'). This creates an instance of the Connection class automatically. Ex. network.connect('input','output') will connect the layers named 'input' and 'output' respectively.
changeLayerSize(layername, newsize) Changes layer size. Newsize must be greater than zero.

Layers are created and connected in the order of activation flow. To check out the ordering, you could:

>>> from pyrobot.brain.conx import Network
>>> net = Network()
>>> net.addLayers(2, 2, 1)
>>> [layer.name for layer in net.layers]
['input', 'hidden', 'output']
>>> [(connect.fromLayer.name, connect.toLayer.name) for connect in net.connections]
[('input', 'hidden'), ('hidden', 'output')]
Accessing elements
To access a: Use this sytnax: Example
Layer net["layerName"] net["input"].size
Node net["layerName"][pos] net["hidden"][1].activation
Node Bias net["layerName"][pos].weight net["hidden"][1].weight = 0.0
Connection net["fromLayerName", "toLayerName"] net["hidden", "output"].randomize()
Weight net["fromLayerName", "toLayerName"][fromPos][toPos] net["input", "hidden"][0][1] = .4
Weight Matrix net["fromLayerName", "toLayerName"].weight max(max(net["input", "hidden"].weight))
Running a Network
setInputs(inputs) Inputs must have the form [[...],[...],[...],...] or [{}, {}, ...]. Use this method in combination with setTargets before any call to sweep() or train().
setTargets(targets) Targets must have the form [[...],[...],[...],...] or [{}, {}, {}]. Use this method in combination with setInputs before any call to sweep() or train().
sweep() Runs through entire dataset. Must call setInputs(), setTargets(), and associate() methods to initialize all inputs and targets for the entire dataset before calling sweep(). Returns TSS error, total correct, and total count.
train() Trains the network on the dataset till a stopping condition is met. This stopping condition can be a limiting epoch or a percentage correct requirement. Train calls sweep multiple times, and so setInputs and setTargets are still required.
copyActivations(layer, vec, start=0) Copies activations in vec to the specified layer, replacing patterns if necessary. This can be called instead of the Layer class copyActivations.
copyTargets(layer, vec, start=0) Copies targets in vec to specified layer, replacing patterns if necessary. This can be called instead of the Layer class copyTargets. Both copyActivations and copyTargets include more features at the Network class level, including pattern replacement, and ability to chose the starting index of the vector from which to copy the activations or targets.
setActive(layerName, value) Sets a layer to active or inactive. (Affects learning and propagation.)
getActive(layerName) Determine whether a layer is active or not by return value.
associate(inName, outName) inName layer and outName layer will be auto-associating.
predict(inName, outName) outName layer will be predicted (use with loadOrder == 1).
step(layerName=valueList,..., [initContext = 0|1]) Does a single step. Calls propagate(...), backprop(...), and change_weights() if learning is set. Format for parameters: <layer name> = <activation/target list>. If initContext is passed, then this overrides default network.initContext setting.
propagate(layerName=valueList,...) Propagates the network using valueList inputs or targets.
propagateFrom(startLayerName, layerName=valueList,...) Propagates the network starting with "startLayerName", using valueList inputs or targets.
backprop(layerName=valueList,...) Sets the targets for the layerNames, computes error, and changes weights (if net.learning = 1). Format for parameters: <layer name> = <activation/target list>. If initContext is passed, then this overrides default network.initContext setting.
setAutoSaveWeightsFile(filename) When Cross Validation is on, will save weights to filename every time CV TSS drops to a new low.
setAutoCrossValidation(value) If true, the system will create a cross validation set directly from the inputs and targets. This is useful for large datasets.
preSweep() Method called before every sweep()
postSweep() Method called after every sweep()
preProp(layerName=valueList,...) Method called before every propagate(). If you wish to alter inputs/targets return an altered form of {layerName: valueList, ...}
postProp(layerName=valueList,...) Method called after every propagate(). If you wish to alter inputs/targets return an altered form of {layerName: valueList, ...}
preBackprop(layerName=valueList,...) Method called before every backprop(). If you wish to alter inputs/targets return an altered form of {layerName: valueList, ...}
postBackprop(layerName=valueList,...) Method called after every backprop(). If you wish to alter inputs/targets return an altered form of {layerName: valueList, ...}
preStep(layerName=valueList,...) Method called before every step(). If you wish to alter inputs/targets return an altered form of {layerName: valueList, ...}
postStep(layerName=valueList,...) Method called after every step(). If you wish to alter inputs/targets return an altered form of {layerName: valueList, ...}
addLayerNode(layerName, bias, weightDict) Add a new node to a layer and optionally set bias and weights between layers.
deleteLayerNode(layerName, pos) Remove a node from a layer, given a position.

You may call these functions as you wish. The standard method is to just call net.train() which does roughly the following:

net.train(), which calls:
   net.sweep(), which calls:
      net.step(), which calls:
         net.propagate()
         net.compute_error()
         net.backprop()
         net.change_weights()
Network IO
saveWeightsToFile(filename, mode = 'pickle') Saves weights to file in pickle, plain/conx, or tlearn mode.
loadWeightsFromFile(filename, mode = 'pickle') Loads weights from a file in pickle, plain/conx, or tlearn mode.
logLayer(layerName, fileName) Sets the layerName's log feature.
logMsg(layerName, message) Logs a message with layerName log.
arrayify() Returns an array of node bias values and connection weights.
unArrayify(gene) Copies gene bias values and weights to network bias values and weights.
saveNetworkToFile(filename) Saves network to file using pickle.
loadVectorsFromFile(filename, cols = None, everyNrows = 1, delim = ' ', checkEven=1) Load a set of vectors from a file. Takes a filename, list of cols you want (or None for all), get every everyNrows (or 1 for no skipping), and a delimeter. If checkEven is true (the default) then Conx will check to make sure the length of all lines are the same.
loadInputsFromFile(filename, cols = None, everyNrows = 1, delim = ' ', checkEven=1) Loads inputs from file. Patterns are removed. If checkEven is true (the default) then Conx will check to make sure the length of all lines are the same.
saveInputsToFile(filename) Saves inputs to file.
loadTargetsFromFile(filename, cols = None, everyNrows = 1, delim = ' ', checkEven=1) Loads targets from file. If checkEven is true (the default) then Conx will check to make sure the length of all lines are the same.
saveTargetsToFile(filename) Saves targets to file.
saveDataToFile(filename) Saves data (targets/inputs) to file.
loadDataFromFile(filename, ocnt = -1) Loads data (targets/inputs) from file.
display() Displays the network to the screen.
toString() Returns the network layers as a string.
network[layerName].patternReport = N Set N to 0 or 1 after building the network to cause the layer to report details at each epoch or not.
Patterning

Patterning provides a method for associated human readable identifiers with input vectors. For example, a neural network doesn't learn to predict English words, but instead learns to predict orthogonal labels associated with English words. When examining network behavior, however, it is often useful to translate those labels back to human readable form. That is what patterning accomplishes.

replacePatterns(vector) Replaces patterned inputs or targets with activation vectors.
patternVector(vector) Replaces vector with patterns. Used for loading inputs or targets from a file and still preserving patterns.
setPatterns(patterns) Sets patterns to the dictionary argument.
getPattern(word) Returns the pattern with key word.
getWord(pattern) Returns the word associated with pattern.
setPattern(word, vector) Sets a pattern with key word. Better to use addPattern() and delPattern().
addPattern(word, vector) Adds a pattern with key word.
delPattern(word) Delete a pattern with key word.
loadInputPatternsFromFile(checkEven=1) Loads patterns from file. If checkEven is true (the default) then Conx will check to make sure the length of all lines are the same.

You may also want to set network[layerName].patternReport = 1 to see the output layer error/correct report by "pattern" in addition to by "node". This is on by default for output layers that have more than 1 node.

Network Parameters
Parameter Default value Meaning
epsilon 0.1 This is the learning rate for the neural network.
tolerance 0.4 The tolerance determines how close an output must be to a target in order to be considered correct.
batch 0 A network in batch mode with only train between runs of the network through the entire training set on the error accumulated over the training set.
epoch 0 Epochs count the number of times sweep is called when using train.
count 0 This records the number of times propagate is called.
learning 1 Determines whether the network is currently learning (changing weights) or not learning (weights fixed).
momentum 0.9 The momentum parameter indicates how much of the previous change carries over for the next weight change.
orderedInputs 0 This parameter determines whether the order of the training set should be preserved or randomized in a call to sweep() of via train().
stopPercent 1.0 A success parameter for train().
reportRate 25 train() will report on the progress every x number of epochs.
resetEpoch 5000 If the stopping criteria have not been met after x number of epochs, the network will reset and try learning from scratch.
resetCount 1 This is the number of times the network has reset when attempting to train() before giving up.
resetLimit 5 This is the number of times the network can reset when attempting to train() before giving up.
interactive 0 Interactive mode will display the network's state after each propagation.
verbosity 0 Determines how much information to display (higher == more).
patterned 0 Set this to 1 to use patterning features.
Adjusting and Accessing Parameters

In general, network parameters can be set or accessed using a method set<Parameter>() or get<Parameter>(). For example, to set the batch flag to 1, call network.setBatch(1). To determine what the verbosity level is, call network.getVerbosity(). Here is a list of these methods. Descriptions are not included as these methods follow the pattern described above.

/!\ Methods that require layer names require the string(s) that was (were) passed to the Layer class constructor, not a reference to the layer(s), i.e. methods getLayer and getConnections require strings, but return references to the identified object.

self.getLayer(name) Alternate syntax: self[name]
setPatterned(value)
setInteractive(value)
setTolerance(value)
setActive(layerName, value)
getActive(layerName)
setLearning(value)
setMomentum(value)
setResetLimit(value)
setResetEpoch(value) Zero means no limit.
setBatch(value)
setSeed(value)
getConnection(lfrom, lto)
setVerbosity(value)
setStopPercent(value)
setReportRate(value)
setMaxRandom(value)
setEpsilon(value)
getWeights(fromName, toName)
setOrderedInputs(value)
shareWeights(otherNetwork)
Cross Validation

Conx supports the ability to have a second corpus of data that is used just for testing throughout the training process.

Values:

crossValidationCorpus ()
crossValidationReportLayers []
crossValidationSampleRate 0
crossValidationSampleFile "sample.cv"

Methods:

sweepCrossValidation()
saveNetworkForCrossValidation(filename, mode = 'a')
loadCrossValidation(filename)
setUseCrossValidationToStop(value)

One could set the cross validation corpus manually:

        n.crossValidationCorpus = ({"input" : [0.1, 0.1], "output" : [0.0]},
                                   {"input" : [0.2, 0.2], "output" : [0.0]},
                                   {"input" : [0.3, 0.3], "output" : [0.0]},
                                   {"input" : [0.4, 0.4], "output" : [0.0]},
                                   {"input" : [0.5, 0.5], "output" : [0.0]},
                                   {"input" : [0.6, 0.6], "output" : [0.0]},
                                   {"input" : [0.7, 0.7], "output" : [0.0]},
                                   {"input" : [0.8, 0.8], "output" : [0.0]},
                                   {"input" : [0.9, 0.9], "output" : [0.0]},
                                   )
        n.setReportRate(100)
        n.setUseCrossValidationToStop(1)
        n.train()

This would test the 9 patterns to see if they produced the targets. The cross validation corpus is a list of dictionaries, each indicating the activations for each input layer and targets for the output layers (by name). tolerance is used to determine correctness, and crossValidationReportLayers is either empty which means "all output layers" or is a list of layer names with which to report correctness. sweepCrossValidation() will go through all patterns and return total sum squared error, number correct, and total number of outputs. it will do this once every reportRate epochs. You can also call sweepCrossValidation() manually, if your network doesn't call train() (for example if you call backprop() directly yourself).

Note that when you have set setUseCrossValidationToStop(1) that stopPercent will be compare to the performance on the cross validation set, rather than the performance on the training corpus. However, it will only check for this ending criteria every reportRate epochs. To check every epoch, use setReportRate(1).

Also, conx can help you collect the cross validation corpus. You need only set crossValidationSampleRate and crossValidationSampleFile and it will save the associated layers to the file, one sample per line. After training, you could test this by:

        n.learning = 0
        n.crossValidationSampleRate = 1
        #saves in "sample.cv"
        n.sweep()
        n.learning = 1
        n.crossValidationSampleRate = 0
        print "Loading crossvalidation from 'sample.cv'..."
        n.loadCrossValidation("sample.cv")
        print "Corpus:", n.crossValidationCorpus

This class uses the simpliest form of cross validation, called the holdout method. This method divides the data into two sets: the training data, and the testing data. Conx can also use the training set as the testing set. This is actually quite useful in large datasets to get an accurate picture of how training is progressing. To turn this on use net.setAutoCrossValidation(1).

More complex cross validation methods exist (such as k-fold and leave-one-out); however, at present, conx does not implement those.

SRN Class

The SRN class inherits from the network class, so all the methods that are not over-ridden will be the same as described above. You must call net.setSequenceType() with "random-continuous", "ordered-continuous", "random-segmented", or "ordered-segmented". The first part of the sequence type indicates whether the patterns are presented in order, or randomly. The second part idicates whether the sequence is continuous or not.

SRN Parameters
Parameter Default value Meaning
learnDuringSequence 0 The network learns during the sequence, not just on sequence boundaries.
initContext .5 Initialize context to .5 at the beginning of each sequence.
contextCopying 1 Copy the context after each step. Set via setSequenceType.
SRN Methods
predict(inName, outName) Sets prediction between an input and output layer.
setInitContext(value) Clear context layer between sequences.
setContextCopying() Sets flag to indicate whether the hidden layer should be copied to the context layer at each step.
setLearnDuringSequence(value) Set self.learnDuringSequence.
addContextLayer(layerName, size, hiddenLayerName) Adds a context layer. /!\ Use this in place of addLayer() when adding a context layer.
copyHiddenToContext() Call this to copy hidden layer activations to context layers.
setContext(value = .5) Clears the context layer.
setSequenceType() Set to "random-continuous", "ordered-continuous", "random-segmented", or "ordered-segmented"

SigmaNetwork Class

This type of network use Reinforcement Learning and a population encoding. See the source code for more information.

General Functions

These functions are not part of any class, but defined here because they are useful for the Conx classes.

loadNetworkFromFile(filename) Loads a saved network from a file. See net.saveNetworkToFile()
ndim(n[, m]*) Creates a random array of size n by m by ...
randomArray(size, max) Returns an array (Numeric) initialized to random values between -max and max.
displayArray(name, a, width = 0) Prints any sequence of floats to the screen.
toStringArray(name, a, width = 0) Returns any sequence of floats as a string.
writeArray(fp, a) Writes a sequence a of floats to file pointed to by file pointer.

Conx Error Classes

LayerError(AttributeError) Used to indicate that a layer has some improper attribute (size, type, etc.).
NetworkError(AttributeError) Used to indicate that a network has some improper attribute (no layers, no connections, etc.).
SRNError(NetworkError) Used to indicate that SRN specific attributes are improper.

Layer Class

The Layer class represents everything related to a single layer of nodes in a Conx network. Layers can log data, and signal different data to be displayed.

User level methods

These methods represent those that are most commonly used directly by the user. The Layer class has many more methods that are primarily accessed through Network class methods.

Layer(name, size) Constructor for new layer. Specifies the size and layer name.
copyActivations(array) Sets layer activations. Used only for input layers.
copyTargets(arr) Sets layer targets. Used only for output layers.
getActivations(), getActivationsList() Returns the layer's activations as a Numeric array or Python list, respectively.
patternReport = N Trigger epoch level report with N set to 1. You can set this directly.

/!\ Layer class parameters should not be accessed directly, except where noted!

Connection Class

Class which contains references to two layers (from and to) and the weights between them.

/!\ Connection Class parameters and methods should only be accessed through Network class methods.

Tricks and tips

Want to continue training after an initial train? Try this:

...
net.train(500)           # trains for 500 (or until learned), and stops
net.train(500, cont=1)   # continues for 500 more, or until learned

Want to force the network to continue regardless of percent correct? Try this:

...
net.doWhile = lambda count, correct: 1  # network will continue training while doWhile returns true (1)
net.train(500)

Other Network Types

  1. See CascorNetwork in pyrobot/brain/cascor.py

  2. See GovernorNetwork in pyrobot/brain/governor.py


Up: PyroModuleNeuralNetworks

Pyro Modules Table of Contents

Modules

  1. PyroModuleIntroduction

  2. PyroModuleObjectOverview

  3. PyroModulePythonIntro

  4. PyroModuleDirectControl

  5. PyroModuleSequencingControl

  6. PyroModuleBehaviorBasedControl

  7. PyroModuleReinforcementLearning

  8. PyroModuleNeuralNetworks

  9. PyroModuleEvolutionaryAlgorithms

  10. PyroModuleComputerVision

  11. PyroModuleMapping

  12. PyroModuleMultirobot

  13. FurtherReading

Additional Resources

  1. PyroIndex

  2. PyroAdvancedTopics

  3. PyroUserManual

  4. [WWW]Pyro Tutorial Movies

Reference: PyroSiteNotes