Add doc comments.

Author: darius

probability.py

@@ -288,7 +288,7 @@ def enumerate_all(vars, e, bn):
 #______________________________________________________________________________
 
 def elimination_ask(X, e, bn):
-    """[Fig. 14.11]
+    """Compute bn's P(X|e) by variable elimination. [Fig. 14.11]
     >>> elimination_ask('Burglary', dict(JohnCalls=T, MaryCalls=T), burglary
     ...  ).show_approx()
     'False: 0.716, True: 0.284'"""
@@ -300,9 +300,13 @@ def elimination_ask(X, e, bn):
     return pointwise_product(factors, bn).normalize()
 
 def is_hidden(var, X, e):
+    "Is var a hidden variable when querying P(X|e)?"
     return var != X and var not in e
 
 def make_factor(var, e, bn):
+    """Return the factor for var in bn's joint distribution given e.
+    That is, bn's full joint distribution, projected to accord with e,
+    is the pointwise product of these factors for bn's variables."""
     node = bn.variable_node(var)
     vars = [X for X in [var] + node.parents if X not in e]
     cpt = dict((event_values(e1, vars), node.p(e1[var], e1))
@@ -313,24 +317,28 @@ def pointwise_product(factors, bn):
     return reduce(lambda f, g: f.pointwise_product(g, bn), factors)
 
 def sum_out(var, factors, bn):
+    "Eliminate var from all factors by summing over its values."
     result, var_factors = [], []
     for f in factors:
         (var_factors if var in f.vars else result).append(f)
     result.append(pointwise_product(var_factors, bn).sum_out(var, bn))
     return result
 
 class Factor:
+    "A factor in a joint distribution."
 
     def __init__(self, vars, cpt):
         update(self, vars=vars, cpt=cpt)
 
     def pointwise_product(self, other, bn):
+        "Multiply two factors, combining their variables."
         vars = list(set(self.vars) | set(other.vars))
         cpt = dict((event_values(e, vars), self.p(e) * other.p(e))
                    for e in all_events(vars, bn, {}))
         return Factor(vars, cpt)
 
     def sum_out(self, var, bn):
+        "Make a factor eliminating var by summing over its values."
         vars = [X for X in self.vars if X != var]
         cpt = dict((event_values(e, vars),
                     sum(self.p(extend(e, var, val))
@@ -339,21 +347,24 @@ def sum_out(self, var, bn):
         return Factor(vars, cpt)
 
     def normalize(self):
+        "Return my probabilities; must be down to one variable."
         assert len(self.vars) == 1
         return ProbDist(self.vars[0],
                         dict((k, v) for ((k,), v) in self.cpt.items()))
 
     def p(self, e):
+        "Look up my value tabulated for e."
         return self.cpt[event_values(e, self.vars)]
 
-def all_events(vars, bn, e1):
+def all_events(vars, bn, e):
+    "Yield every way of extending e with values for all vars."
     if not vars:
-        yield e1
+        yield e
     else:
         X, rest = vars[0], vars[1:]
-        for e in all_events(rest, bn, e1):
+        for e1 in all_events(rest, bn, e):
             for x in bn.variable_values(X):
-                yield extend(e, X, x)
+                yield extend(e1, X, x)
 
 #______________________________________________________________________________