[MRG+1] Made PCA expose the singular values

sklearn/decomposition/incremental_pca.py

@@ -71,7 +71,12 @@ class IncrementalPCA(_BasePCA):
     explained_variance_ratio_ : array, shape (n_components,)
         Percentage of variance explained by each of the selected components.
         If all components are stored, the sum of explained variances is equal
-        to 1.0
+        to 1.0.
+
+    singular_values_ : array, shape (n_components,)
+        The singular values corresponding to each of the selected components.
+        The singular values are equal to the 2-norms of the ``n_components``
+        variables in the lower-dimensional space.
 
     mean_ : array, shape (n_features,)
         Per-feature empirical mean, aggregate over calls to ``partial_fit``.
@@ -166,6 +171,7 @@ def fit(self, X, y=None):
         self.singular_values_ = None
         self.explained_variance_ = None
         self.explained_variance_ratio_ = None
+        self.singular_values_ = None
         self.noise_variance_ = None
 
         X = check_array(X, copy=self.copy, dtype=[np.float64, np.float32])

sklearn/decomposition/pca.py

@@ -186,23 +186,28 @@ class PCA(_BasePCA):
 
     Attributes
     ----------
-    components_ : array, [n_components, n_features]
+    components_ : array, shape (n_components, n_features)
         Principal axes in feature space, representing the directions of
         maximum variance in the data. The components are sorted by
         ``explained_variance_``.
 
-    explained_variance_ : array, [n_components]
+    explained_variance_ : array, shape (n_components,)
         The amount of variance explained by each of the selected components.
 
         .. versionadded:: 0.18
 
-    explained_variance_ratio_ : array, [n_components]
+    explained_variance_ratio_ : array, shape (n_components,)
         Percentage of variance explained by each of the selected components.
 
         If ``n_components`` is not set then all components are stored and the
         sum of explained variances is equal to 1.0.
 
-    mean_ : array, [n_features]
+    singular_values_ : array, shape (n_components,)
+        The singular values corresponding to each of the selected components.
+        The singular values are equal to the 2-norms of the ``n_components``
+        variables in the lower-dimensional space.
+
+    mean_ : array, shape (n_features,)
         Per-feature empirical mean, estimated from the training set.
 
         Equal to `X.mean(axis=1)`.
@@ -250,22 +255,28 @@ class PCA(_BasePCA):
     >>> pca.fit(X)
     PCA(copy=True, iterated_power='auto', n_components=2, random_state=None,
       svd_solver='auto', tol=0.0, whiten=False)
-    >>> print(pca.explained_variance_ratio_) # doctest: +ELLIPSIS
+    >>> print(pca.explained_variance_ratio_)  # doctest: +ELLIPSIS
     [ 0.99244...  0.00755...]
+    >>> print(pca.singular_values_)  # doctest: +ELLIPSIS
+    [ 6.30061...  0.54980...]
 
     >>> pca = PCA(n_components=2, svd_solver='full')
     >>> pca.fit(X)                 # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
     PCA(copy=True, iterated_power='auto', n_components=2, random_state=None,
       svd_solver='full', tol=0.0, whiten=False)
-    >>> print(pca.explained_variance_ratio_) # doctest: +ELLIPSIS
+    >>> print(pca.explained_variance_ratio_)  # doctest: +ELLIPSIS
     [ 0.99244...  0.00755...]
+    >>> print(pca.singular_values_)  # doctest: +ELLIPSIS
+    [ 6.30061...  0.54980...]
 
     >>> pca = PCA(n_components=1, svd_solver='arpack')
     >>> pca.fit(X)
     PCA(copy=True, iterated_power='auto', n_components=1, random_state=None,
       svd_solver='arpack', tol=0.0, whiten=False)
-    >>> print(pca.explained_variance_ratio_) # doctest: +ELLIPSIS
+    >>> print(pca.explained_variance_ratio_)  # doctest: +ELLIPSIS
     [ 0.99244...]
+    >>> print(pca.singular_values_)  # doctest: +ELLIPSIS
+    [ 6.30061...]
 
     See also
     --------
@@ -385,6 +396,7 @@ def _fit_full(self, X, n_components):
         explained_variance_ = (S ** 2) / n_samples
         total_var = explained_variance_.sum()
         explained_variance_ratio_ = explained_variance_ / total_var
+        singular_values_ = S.copy()  # Store the singular values.
 
         # Postprocess the number of components required
         if n_components == 'mle':
@@ -409,6 +421,7 @@ def _fit_full(self, X, n_components):
         self.explained_variance_ = explained_variance_[:n_components]
         self.explained_variance_ratio_ = \
             explained_variance_ratio_[:n_components]
+        self.singular_values_ = singular_values_[:n_components]
 
         return U, S, V
 
@@ -463,6 +476,7 @@ def _fit_truncated(self, X, n_components, svd_solver):
         total_var = np.var(X, axis=0)
         self.explained_variance_ratio_ = \
             self.explained_variance_ / total_var.sum()
+        self.singular_values_ = S.copy()  # Store the singular values.
         if self.n_components_ < n_features:
             self.noise_variance_ = (total_var.sum() -
                                     self.explained_variance_.sum())
@@ -520,9 +534,11 @@ def score(self, X, y=None):
         return np.mean(self.score_samples(X))
 
 
-@deprecated("RandomizedPCA was deprecated in 0.18 and will be removed in 0.20. "
+@deprecated("RandomizedPCA was deprecated in 0.18 and will be removed in "
+            "0.20. "
             "Use PCA(svd_solver='randomized') instead. The new implementation "
-            "DOES NOT store whiten ``components_``. Apply transform to get them.")
+            "DOES NOT store whiten ``components_``. Apply transform to get "
+            "them.")
 class RandomizedPCA(BaseEstimator, TransformerMixin):
     """Principal component analysis (PCA) using randomized SVD
 
@@ -549,8 +565,8 @@ class RandomizedPCA(BaseEstimator, TransformerMixin):
         .. versionchanged:: 0.18
 
     whiten : bool, optional
-        When True (False by default) the `components_` vectors are multiplied by
-        the square root of (n_samples) and divided by the singular values to
+        When True (False by default) the `components_` vectors are multiplied
+        by the square root of (n_samples) and divided by the singular values to
         ensure uncorrelated outputs with unit component-wise variances.
 
         Whitening will remove some information from the transformed signal
@@ -564,15 +580,20 @@ class RandomizedPCA(BaseEstimator, TransformerMixin):
 
     Attributes
     ----------
-    components_ : array, [n_components, n_features]
+    components_ : array, shape (n_components, n_features)
         Components with maximum variance.
 
-    explained_variance_ratio_ : array, [n_components]
+    explained_variance_ratio_ : array, shape (n_components,)
         Percentage of variance explained by each of the selected components.
-        k is not set then all components are stored and the sum of explained
-        variances is equal to 1.0
+        If k is not set then all components are stored and the sum of explained
+        variances is equal to 1.0.
+
+    singular_values_ : array, shape (n_components,)
+        The singular values corresponding to each of the selected components.
+        The singular values are equal to the 2-norms of the ``n_components``
+        variables in the lower-dimensional space.
 
-    mean_ : array, [n_features]
+    mean_ : array, shape (n_features,)
         Per-feature empirical mean, estimated from the training set.
 
     Examples
@@ -584,8 +605,10 @@ class RandomizedPCA(BaseEstimator, TransformerMixin):
     >>> pca.fit(X)                 # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
     RandomizedPCA(copy=True, iterated_power=2, n_components=2,
            random_state=None, whiten=False)
-    >>> print(pca.explained_variance_ratio_) # doctest: +ELLIPSIS
+    >>> print(pca.explained_variance_ratio_)  # doctest: +ELLIPSIS
     [ 0.99244...  0.00755...]
+    >>> print(pca.singular_values_)  # doctest: +ELLIPSIS
+    [ 6.30061...  0.54980...]
 
     See also
     --------
@@ -663,6 +686,7 @@ def _fit(self, X):
         self.explained_variance_ = exp_var = (S ** 2) / n_samples
         full_var = np.var(X, axis=0).sum()
         self.explained_variance_ratio_ = exp_var / full_var
+        self.singular_values_ = S  # Store the singular values.
 
         if self.whiten:
             self.components_ = V / S[:, np.newaxis] * sqrt(n_samples)

sklearn/decomposition/truncated_svd.py

@@ -71,26 +71,33 @@ class TruncatedSVD(BaseEstimator, TransformerMixin):
     ----------
     components_ : array, shape (n_components, n_features)
 
-    explained_variance_ratio_ : array, [n_components]
-        Percentage of variance explained by each of the selected components.
-
-    explained_variance_ : array, [n_components]
+    explained_variance_ : array, shape (n_components,)
         The variance of the training samples transformed by a projection to
         each component.
 
+    explained_variance_ratio_ : array, shape (n_components,)
+        Percentage of variance explained by each of the selected components.
+
+    singular_values_ : array, shape (n_components,)
+        The singular values corresponding to each of the selected components.
+        The singular values are equal to the 2-norms of the ``n_components``
+        variables in the lower-dimensional space.
+
     Examples
     --------
     >>> from sklearn.decomposition import TruncatedSVD
     >>> from sklearn.random_projection import sparse_random_matrix
     >>> X = sparse_random_matrix(100, 100, density=0.01, random_state=42)
     >>> svd = TruncatedSVD(n_components=5, n_iter=7, random_state=42)
-    >>> svd.fit(X) # doctest: +NORMALIZE_WHITESPACE
+    >>> svd.fit(X)  # doctest: +NORMALIZE_WHITESPACE
     TruncatedSVD(algorithm='randomized', n_components=5, n_iter=7,
             random_state=42, tol=0.0)
-    >>> print(svd.explained_variance_ratio_) # doctest: +ELLIPSIS
+    >>> print(svd.explained_variance_ratio_)  # doctest: +ELLIPSIS
     [ 0.0782... 0.0552... 0.0544... 0.0499... 0.0413...]
-    >>> print(svd.explained_variance_ratio_.sum()) # doctest: +ELLIPSIS
+    >>> print(svd.explained_variance_ratio_.sum())  # doctest: +ELLIPSIS
     0.279...
+    >>> print(svd.singular_values_)  # doctest: +ELLIPSIS
+    [ 2.6318... 2.2215... 2.1939... 2.1010... 1.9317...]
 
     See also
     --------
@@ -185,6 +192,8 @@ def fit_transform(self, X, y=None):
         else:
             full_var = np.var(X, axis=0).sum()
         self.explained_variance_ratio_ = exp_var / full_var
+        self.singular_values_ = Sigma  # Store the singular values.
+
         return X_transformed
 
     def transform(self, X):