scikit-learn
diff --git a/‎sklearn/metrics/pairwise.py
Lines changed: 22 additions & 13 deletions b/‎sklearn/metrics/pairwise.py
Lines changed: 22 additions & 13 deletions
diff --git a/‎sklearn/metrics/tests/test_pairwise.py
Lines changed: 15 additions & 0 deletions b/‎sklearn/metrics/tests/test_pairwise.py
Lines changed: 15 additions & 0 deletions
@@ -106,7 +106,8 @@ def check_pairwise_arrays(X, Y):
 
 
 # Distances
-def euclidean_distances(X, Y=None, Y_norm_squared=None, squared=False):
+def euclidean_distances(X, Y=None, Y_norm_squared=None, squared=False,
+                        X_norm_squared=None):
     """
     Considering the rows of X (and Y=X) as vectors, compute the
     distance matrix between each pair of vectors.
@@ -117,9 +118,9 @@ def euclidean_distances(X, Y=None, Y_norm_squared=None, squared=False):
         dist(x, y) = sqrt(dot(x, x) - 2 * dot(x, y) + dot(y, y))
 
     This formulation has two main advantages. First, it is computationally
-    efficient when dealing with sparse data. Second, if x varies but y
-    remains unchanged, then the right-most dot-product `dot(y, y)` can be
-    pre-computed.
+    efficient when dealing with sparse data. Second, the components `dot(x, x)`
+    or `dot(y, y)` can be pre-computed when getting euclidean distances for
+    multiple sets.
 
     Parameters
     ----------
@@ -134,6 +135,10 @@ def euclidean_distances(X, Y=None, Y_norm_squared=None, squared=False):
     squared : boolean, optional
         Return squared Euclidean distances.
 
+    X_norm_squared : array-like, shape = [n_samples_1], optional
+        Pre-computed dot-products of vectors in X (e.g.,
+        ``(X**2).sum(axis=1)``)
+
     Returns
     -------
     distances : {array, sparse matrix}, shape = [n_samples_1, n_samples_2]
@@ -151,24 +156,28 @@ def euclidean_distances(X, Y=None, Y_norm_squared=None, squared=False):
     array([[ 1.        ],
            [ 1.41421356]])
     """
-    # should not need X_norm_squared because if you could precompute that as
-    # well as Y, then you should just pre-compute the output and not even
-    # call this function.
     X, Y = check_pairwise_arrays(X, Y)
 
-    if Y_norm_squared is not None:
+    if X_norm_squared is not None:
+        XX = array2d(X_norm_squared)
+        if XX.shape == (1, X.shape[0]):
+            XX = XX.T
+        elif XX.shape != (X.shape[0], 1):
+            raise ValueError(
+                "Incompatible dimensions for X and X_norm_squared")
+    else:
+        XX = row_norms(X, squared=True)[:, np.newaxis]
+
+    if X is Y:  # shortcut in the common case euclidean_distances(X, X)
+        YY = XX.T
+    elif Y_norm_squared is not None:
         YY = array2d(Y_norm_squared)
         if YY.shape != (1, Y.shape[0]):
             raise ValueError(
                 "Incompatible dimensions for Y and Y_norm_squared")
     else:
         YY = row_norms(Y, squared=True)[np.newaxis, :]
 
-    if X is Y:  # shortcut in the common case euclidean_distances(X, X)
-        XX = YY.T
-    else:
-        XX = row_norms(X, squared=True)[:, np.newaxis]
-
     distances = safe_sparse_dot(X, Y.T, dense_output=True)
     distances *= -2
     distances += XX
 
@@ -260,6 +260,21 @@ def test_euclidean_distances():
     D = euclidean_distances(X, Y)
     assert_array_almost_equal(D, [[1., 2.]])
 
+    rng = np.random.RandomState(0)
+    X = rng.random_sample((10, 4))
+    Y = rng.random_sample((20, 4))
+    X_norm_sq = (X ** 2).sum(axis=1)
+    Y_norm_sq = (Y ** 2).sum(axis=1)
+
+    D1 = euclidean_distances(X, Y)
+    D2 = euclidean_distances(X, Y, X_norm_squared=X_norm_sq)
+    D3 = euclidean_distances(X, Y, Y_norm_squared=Y_norm_sq)
+    D4 = euclidean_distances(X, Y, X_norm_squared=X_norm_sq,
+                             Y_norm_squared=Y_norm_sq)
+    assert_array_almost_equal(D1, D2)
+    assert_array_almost_equal(D1, D3)
+    assert_array_almost_equal(D1, D4)
+
 
 def test_chi_square_kernel():
     rng = np.random.RandomState(0)