--- a/pylearn/formulas/costs.py	Fri Oct 01 11:55:04 2010 -0400
+++ b/pylearn/formulas/costs.py	Fri Oct 01 12:19:55 2010 -0400
@@ -1,5 +1,5 @@
 """
-This script defines a few often used cost functions.
+Common training criteria.
 """
 import theano
 import theano.tensor as T
@@ -20,3 +20,5 @@
     return -(target * T.log(output) + (1.0 - target) * T.log(1.0 - output))
 
 
+# This file seems like it has some overlap with theano.tensor.nnet.  Which functions should go
+# in which file?

--- a/pylearn/formulas/noise.py	Fri Oct 01 11:55:04 2010 -0400
+++ b/pylearn/formulas/noise.py	Fri Oct 01 12:19:55 2010 -0400
@@ -1,12 +1,14 @@
 """
+Noise functions used to train Denoising Auto-Associators.
 
-This script define the different symbolic noise functions.
+Functions in this module often include a `noise_lvl` argument that controls the amount of noise
+that the function applies.
 The noise contract is simple: noise_lvl is a symbolic variable going from 0 to 1.
 0: no change.
 1: maximum noise.
 """
 import theano
-from tags import tags
+import tags
 s="""
 * A latex mathematical description of the formulas(for picture representation in generated documentation)
 * Tags(for searching):
@@ -19,20 +21,28 @@
 * Tell the domaine, range of the input/output(range should use the english notation of including or excluding)
 """
 
-@tags('noise','binomial','salt')
-def binomial_noise(theano_rng,inp,noise_lvl):
+@tags.tags('noise','binomial','salt')
+def binomial_noise(theano_rng,input,noise_lvl):
     """
-    This add binomial noise to inp. Only the salt part of pepper and salt.
+    Return `inp` with randomly-chosen elements set to zero.
+
+    TODO: MATH DEFINITION
 
-    :type inp: Theano variable
-    :param inp: The input that we want to add noise
+    :type input: Theano tensor variable
+    :param input: input
     :type noise_lvl: float
-    :param noise_lvl: The %% of noise. Between 0 (no noise) and 1.
+    :param noise_lvl: The probability of setting each element to zero.
     """
-    return theano_rng.binomial( size = inp.shape, n = 1, p =  1 - noise_lvl, dtype=theano.config.floatX) * inp
+    mask = theano_rng.binomial(
+            size = inp.shape,
+            n = 1,
+            p =  1 - noise_lvl,
+            dtype=theano.config.floatX) 
+    # QUESTION: should the dtype not default to the input dtype?
+    return mask * input
 
 
-@tags('noise','binomial NLP','pepper','salt')
+@tags.tags('noise','binomial NLP','pepper','salt')
 def pepper_and_salt_noise(theano_rng,inp,noise_lvl):
     """ This add pepper and salt noise to inp
 
@@ -44,7 +54,7 @@
     return theano_rng.binomial( size = inp.shape, n = 1, p =  1 - noise_lvl[0], dtype=theano.config.floatX) * inp \
                         + (inp==0) * theano_rng.binomial( size = inp.shape, n = 1, p =  noise_lvl[1], dtype=theano.config.floatX)
 
-@tags('noise','gauss','gaussian')
+@tags.tags('noise','gauss','gaussian')
 def gaussian_noise(theano_rng,inp,noise_lvl):
     """ This add gaussian NLP noise to inp