From 2d20b5883e85e145c0c8b560cb2da3db3ff46405 Mon Sep 17 00:00:00 2001
From: John Mason <jmason42@stanford.edu>
Date: Mon, 11 Jun 2018 16:14:37 -0700
Subject: [PATCH] documented utility modules

---
 utils/ks_test.py   | 10 ++++++++++
 utils/l1min.py     |  8 +++++++-
 utils/linalg.py    | 24 +++++++++++++++++++++++-
 utils/liveout.py   |  7 +++++++
 utils/plotting.py  |  6 +++++-
 utils/rdp.py       |  7 +++++++
 utils/residuals.py |  2 +-
 utils/svm.py       |  6 ++++++
 8 files changed, 66 insertions(+), 4 deletions(-)

diff --git a/utils/ks_test.py b/utils/ks_test.py
index 8a5c582..2f1f98f 100644
--- a/utils/ks_test.py
+++ b/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
diff --git a/utils/l1min.py b/utils/l1min.py
index 90ed804..2ce5e4e 100644
--- a/utils/l1min.py
+++ b/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
 
diff --git a/utils/linalg.py b/utils/linalg.py
index 71ad10d..f237ea9 100644
--- a/utils/linalg.py
+++ b/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))
diff --git a/utils/liveout.py b/utils/liveout.py
index 9f1d9c9..f223c0e 100644
--- a/utils/liveout.py
+++ b/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
diff --git a/utils/plotting.py b/utils/plotting.py
index 7683c56..8db4e37 100644
--- a/utils/plotting.py
+++ b/utils/plotting.py
@@ -1,5 +1,9 @@
 
-# TODO: delete?
+'''
+
+Deifnes a plotting utility function.  Unused but helpful for inspecting matrices.
+
+'''
 
 from __future__ import division
 
diff --git a/utils/rdp.py b/utils/rdp.py
index 93aea04..f48a71c 100644
--- a/utils/rdp.py
+++ b/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
diff --git a/utils/residuals.py b/utils/residuals.py
index 70e47c2..8839948 100644
--- a/utils/residuals.py
+++ b/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
diff --git a/utils/svm.py b/utils/svm.py
index 8708c40..664be9c 100644
--- a/utils/svm.py
+++ b/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