documented utility modules

utils/ks_test.py

@@ -1,4 +1,14 @@
 
+'''
+
+Performs the two-sample KS test, a non-parameteric test on whether two
+distributions are significantly different.  Not used.
+
+TODO: delete
+
+'''
+
+
 from __future__ import division
 
 import numpy as np

utils/l1min.py

@@ -1,5 +1,11 @@
 
-# TODO: delete?
+'''
+
+Defines a function to perform constrained L1-norm minimization.  Unused.
+
+TODO: delete
+
+'''
 
 from __future__ import division
 

utils/linalg.py

@@ -1,5 +1,11 @@
 
-# TODO: delete?
+'''
+
+Functions for performing various, specialized linear algebra optimizations.
+Largely unutilized, except for bilevel_elementwise_pseudoinverse and
+approx_jac.
+
+'''
 
 from __future__ import division
 
@@ -42,6 +48,11 @@ def nullspace_basis(matrix, rcond = _RES):
 	return null
 
 def pinv(matrix, rcond = _RES):
+	'''
+	Finds the Moore-Penrose pseudo-inverse using the singular value
+	decomposition.
+	'''
+
 	u, s, vT = np.linalg.svd(matrix, full_matrices = False)
 
 	retain = (s / s[0] > rcond)
@@ -78,6 +89,13 @@ def bilevel_pseudoinverse(first_matrix, second_matrix, rcond = _RES):
 	return second_nullspace_projector.dot(first_matrix_pseudoinverse)
 
 def bilevel_elementwise_pseudoinverse(first_matrix, second_matrix, rcond = _RES):
+	'''
+
+	Creates the pseudo-inverse matrix that solves a bilevel least-squares
+	optimization problem.
+
+	'''
+
 	n, size = first_matrix.shape
 
 	vectors = [first_matrix[[i], :] for i in xrange(n)]
@@ -102,6 +120,10 @@ def bilevel_elementwise_pseudoinverse(first_matrix, second_matrix, rcond = _RES)
 	return np.concatenate(bilevel_pinvs, 1)
 
 def approx_jac(f, x, d = 1e-3):
+	'''
+	Computes an approximate Jacobian on a function f with respect to parameter
+	values x using centered differences with a size of d.
+	'''
 	f0 = f(x)
 
 	j = np.empty((f0.size, x.size))

utils/liveout.py

@@ -1,4 +1,11 @@
 
+'''
+
+Defines functions and classes for outputing data to a shell in a live, updating
+table.
+
+'''
+
 import sys
 
 from itertools import izip

utils/plotting.py

@@ -1,5 +1,9 @@
 
-# TODO: delete?
+'''
+
+Deifnes a plotting utility function.  Unused but helpful for inspecting matrices.
+
+'''
 
 from __future__ import division
 

utils/rdp.py

@@ -1,4 +1,11 @@
 
+'''
+
+Defines a function for performing the RDP algorithm on data, useful for
+reducing the number of points in a plot.  Not used.
+
+'''
+
 from __future__ import division
 
 import numpy as np

utils/residuals.py

@@ -1,6 +1,6 @@
 
 '''
-Plotting code for drawing the condensed box-plots for figures 5 and 6.
+Plotting code for drawing the condensed box-plots for figures 4 and 6.
 '''
 
 from __future__ import division

utils/svm.py

@@ -1,4 +1,10 @@
 
+'''
+
+Defines a function for performing soft-margin SVM.  Not used.
+
+'''
+
 from __future__ import division
 
 import numpy as np