# HG changeset patch
# User James Bergstra <bergstrj@iro.umontreal.ca>
# Date 1299089120 18000
# Node ID a19c371a8d3af208b49e9c759721bff5a98b1bd0
# Parent  c584d8f8f280c7131e19031ab6277d7b399fad4d
pca - added pca_whiten2 with better interface than pca_whiten

diff -r c584d8f8f280 -r a19c371a8d3a pylearn/preprocessing/pca.py
--- a/pylearn/preprocessing/pca.py	Fri Feb 25 16:38:33 2011 -0500
+++ b/pylearn/preprocessing/pca.py	Wed Mar 02 13:05:20 2011 -0500
@@ -118,6 +118,32 @@
     """
     return numpy.dot(whitened_X * (numpy.sqrt(eigvals+eps)), eigvecs.T)
 
+def pca_whiten2(pca_from_examples_rval, eps=1e-14):
+    """
+    Return the projection of X onto it's principle components.  
+    
+    The return value has the same number of rows as X, but the number of columns is the number
+    of principle components.  Columns of the return value have mean 0, variance 1, and are
+    uncorrelated.
+
+    .. code-block:: python
+
+        X = data
+        (evals, evecs), whitened_X = pca_whiten(
+                pca_from_examples(X, max_components=10),
+                eps=1e-3)
+
+    :param pca_from_examples_rval: the ((eigvals, eigvecs), centered_X)
+            pair returned by e.g. pca_from_examples(X).
+
+    :returns: ((eigvals, eigvecs), whitened_X)
+
+    """
+    ((eigvals, eigvecs), centered_X) = pca_from_examples_rval
+    pca_of_X = numpy.dot(centered_X, eigvecs)
+    pca_of_X /= numpy.sqrt(eigvals+eps)
+    return ((eigvals, eigvecs), pca_of_X)
+
 def zca_whiten((eigvals, eigvecs), centered_X):
     """Return the PCA of X but rotated back into the original vector space.