[MRG+2] DOC correct docstring for sample_gaussian (scikit-learn#6957)

* DOC correct docstring for sample_gaussian

Docstring did not match function behaviour. Caused some trouble trying to implement a compatible version for a different distribution.

* MAINT Use _sample_gaussian internally

This avoids triggering the deprecation warning. sample_gaussian is just a thin
wrapper.

* Fix _sample_gaussian test path

_sample_gaussian is not publicly exported in mixture, so use gmm module.

Author: Kai

sklearn/mixture/gmm.py

@@ -84,7 +84,7 @@ def sample_gaussian(mean, covar, covariance_type='diag', n_samples=1,
     mean : array_like, shape (n_features,)
         Mean of the distribution.
 
-    covar : array_like, optional
+    covar : array_like
         Covariance of the distribution. The shape depends on `covariance_type`:
             scalar if 'spherical',
             (n_features) if 'diag',
@@ -99,9 +99,17 @@ def sample_gaussian(mean, covar, covariance_type='diag', n_samples=1,
 
     Returns
     -------
-    X : array, shape (n_features, n_samples)
-        Randomly generated sample
+    X : array
+        Randomly generated sample. The shape depends on `n_samples`:
+        (n_features,) if `1`
+        (n_features, n_samples) otherwise
     """
+    _sample_gaussian(mean, covar, covariance_type='diag', n_samples=1,
+                     random_state=None)
+
+
+def _sample_gaussian(mean, covar, covariance_type='diag', n_samples=1,
+                     random_state=None):
     rng = check_random_state(random_state)
     n_dim = len(mean)
     rand = rng.randn(n_dim, n_samples)
@@ -423,7 +431,7 @@ def sample(self, n_samples=1, random_state=None):
                     cv = self.covars_[comp][0]
                 else:
                     cv = self.covars_[comp]
-                X[comp_in_X] = sample_gaussian(
+                X[comp_in_X] = _sample_gaussian(
                     self.means_[comp], cv, self.covariance_type,
                     num_comp_in_X, random_state=random_state).T
         return X

sklearn/mixture/tests/test_gmm.py

@@ -33,15 +33,15 @@ def test_sample_gaussian():
     mu = rng.randint(10) * rng.rand(n_features)
     cv = (rng.rand(n_features) + 1.0) ** 2
 
-    samples = mixture.sample_gaussian(
+    samples = mixture.gmm._sample_gaussian(
         mu, cv, covariance_type='diag', n_samples=n_samples)
 
     assert_true(np.allclose(samples.mean(axis), mu, atol=1.3))
     assert_true(np.allclose(samples.var(axis), cv, atol=1.5))
 
     # the same for spherical covariances
     cv = (rng.rand() + 1.0) ** 2
-    samples = mixture.sample_gaussian(
+    samples = mixture.gmm._sample_gaussian(
         mu, cv, covariance_type='spherical', n_samples=n_samples)
 
     assert_true(np.allclose(samples.mean(axis), mu, atol=1.5))
@@ -51,16 +51,15 @@ def test_sample_gaussian():
     # and for full covariances
     A = rng.randn(n_features, n_features)
     cv = np.dot(A.T, A) + np.eye(n_features)
-    samples = mixture.sample_gaussian(
+    samples = mixture.gmm._sample_gaussian(
         mu, cv, covariance_type='full', n_samples=n_samples)
     assert_true(np.allclose(samples.mean(axis), mu, atol=1.3))
     assert_true(np.allclose(np.cov(samples), cv, atol=2.5))
 
     # Numerical stability check: in SciPy 0.12.0 at least, eigh may return
     # tiny negative values in its second return value.
-    from sklearn.mixture import sample_gaussian
-    x = sample_gaussian([0, 0], [[4, 3], [1, .1]],
-                        covariance_type='full', random_state=42)
+    x = mixture.gmm._sample_gaussian(
+        [0, 0], [[4, 3], [1, .1]], covariance_type='full', random_state=42)
     assert_true(np.isfinite(x).all())