Added docs for utils; link to readthedocs on README

README.md

@@ -1,12 +1,14 @@
 # conx
 
-Neural Network Library for Cognitive Scientists
+## Deep Learning for Simple Folk
 
-Built in Python on Keras
+Built in Python on Keras.
 
 [![CircleCI](https://circleci.com/gh/Calysto/conx/tree/master.svg?style=svg)](https://circleci.com/gh/Calysto/conx/tree/master) [![codecov](https://codecov.io/gh/Calysto/conx/branch/master/graph/badge.svg)](https://codecov.io/gh/Calysto/conx)
 
-Networks implement neural network algorithms. Networks can have as many hidden layers as you desire.
+Read the documentation at [conx.readthedocs.io](http://conx.readthedocs.io/)
+
+Implements Deep Learning neural network algorithms using a simple interface. Built on top of Keras, which can use either TensorFlow or Theano.
 
 The network is specified to the constructor by providing sizes. For example, Network("XOR", 2, 5, 1) specifies a network named "XOR" with a 2-node input layer, 5-unit hidden layer, and a 1-unit output layer.
 
@@ -22,7 +24,7 @@ dataset = [[[0, 0], [0]],
           [[1, 0], [1]],
           [[1, 1], [0]]]
 
-net = Network("XOR", 2, 2, 1, activation="sigmoid")
+net = Network("XOR", 2, 5, 1, activation="sigmoid")
 net.set_dataset(dataset)
 net.compile(loss='mean_squared_error',
             optimizer=SGD(lr=0.3, momentum=0.9))

conx/utils.py

@@ -24,9 +24,16 @@
 # utility functions
 
 def one_hot(vector, categories):
+    """
+    Given a vector of integers (i.e. labels), return a numpy array of one-hot vectors.
+    """
     return to_categorical(vector, categories)[0].tolist()
 
 def topological_sort(net, layers):
+    """
+    Given a conx network and list of layers, produce a topological
+    sorted list, from input(s) to output(s).
+    """
     ## Initilize all:
     for layer in net.layers:
         layer.visited = False
@@ -39,13 +46,20 @@ def topological_sort(net, layers):
     return stack
 
 def visit(layer, stack):
+    """
+    Utility function for topological_sort.
+    """
     layer.visited = True
     for outgoing_layer in layer.outgoing_connections:
         if not outgoing_layer.visited:
             visit(outgoing_layer, stack)
     stack.append(layer)
 
 def autoname(index, sizes):
+    """
+    Given an index and list of sizes, return a
+    name for the layer.
+    """
     if index == 0:
         n = "input"
     elif index == sizes - 1:
@@ -57,14 +71,24 @@ def autoname(index, sizes):
     return n
 
 def valid_shape(x):
+    """
+    Is this a valid shape for Keras layers?
+    """
     return isinstance(x, numbers.Integral) and x > 0 \
         or isinstance(x, (tuple, list)) and len(x) > 1 and all([isinstance(n, numbers.Integral) and n > 0 for n in x])
 
 def valid_vshape(x):
+    """
+    Is this a valid shape (i.e., size) to display vectors using PIL?
+    """
     # vshape must be a single int or a 2-dimensional tuple
     return valid_shape(x) and (isinstance(x, numbers.Integral) or len(x) == 2)
 
 def rescale_numpy_array(a, old_range, new_range, new_dtype):
+    """
+    Given a vector, old min/max, a new min/max and a numpy type,
+    create a new vector scaling the old values.
+    """
     assert isinstance(old_range, (tuple, list)) and isinstance(new_range, (tuple, list))
     old_min, old_max = old_range
     if a.min() < old_min or a.max() > old_max: