2. [MRG] Bilinear similarity

doc/introduction.rst

@@ -45,7 +45,7 @@ measuring the agreement with the training data.
 Mahalanobis Distances
 =====================
 
-In the metric-learn package, all algorithms currently implemented learn 
+In the metric-learn package, most algorithms currently implemented learn 
 so-called Mahalanobis distances. Given a real-valued parameter matrix
 :math:`L` of shape ``(num_dims, n_features)`` where ``n_features`` is the
 number features describing the data, the Mahalanobis distance associated with
@@ -79,6 +79,34 @@ necessarily the identity of indiscernibles.
   parameterizations are equivalent. In practice, an algorithm may thus solve
   the metric learning problem with respect to either :math:`M` or :math:`L`.
 
+.. _bilinear_similarity:
+
+Bilinear Similarity
+===================
+
+Some algorithms in the package don't learn a distance or pseudo-distance, but
+a similarity. The idea is that two pairs are closer if their similarity value
+is high, and viceversa. Given a real-valued parameter matrix :math:`W` of shape
+``(n_features, n_features)`` where ``n_features`` is the number features
+describing the data, the Bilinear Similarity associated with :math:`W` is
+defined as follows:
+
+.. math:: S_W(x, x') = x^T W x'
+
+The matrix :math:`W` is not required to be positive semi-definite (PSD), so
+none of the distance properties are satisfied: nonnegativity, identity of
+indiscernibles, symmetry and triangle inequality.
+
+This allows some algorithms to optimize :math:`S_W` in an online manner using a
+simple and efficient procedure, and thus can be applied to problems with
+millions of training instances and achieves state-of-the-art performance
+on an image search task using :math:`k`-NN.
+
+It also allows to be applied in contexts where the triangle inequality is
+violated by visual judgements and the goal is to approximate perceptual
+similarity. For intance, a man and a horse are both similar to a centaur,
+but not to one another.
+
 .. _use_cases:
 
 Use-cases
@@ -103,6 +131,10 @@ examples (for code illustrating some of these use-cases, see the
   the data into a new embedding space before feeding it into another machine
   learning algorithm.
 
+The most common use-case of metric-learn would be to learn a Mahalanobis metric,
+then transform the data to the learned space, and then resolve one of the task
+above.
+
 The API of metric-learn is compatible with `scikit-learn
 <https://scikit-learn.org/>`_, the leading library for machine
 learning in Python. This allows to easily pipeline metric learners with other

doc/supervised.rst

@@ -41,32 +41,43 @@ two numbers.
 
 Fit, transform, and so on
 -------------------------
-The goal of supervised metric-learning algorithms is to transform
+Generally, the goal of supervised metric-learning algorithms is to transform
 points in a new space, in which the distance between two points from the
 same class will be small, and the distance between two points from different
-classes will be large. To do so, we fit the metric learner (example:
-`NCA`).
+classes will be large.
+
+But there are also some algorithms that learn a similarity, not a distance,
+thus the points cannot be transformed into a new space. In this case, the
+utility comes at using the similarity bewtween points directly.
+
+Mahalanobis learners can transform points into a new space, and to do so,
+we fit the metric learner (example:`NCA`).
 
 >>> from metric_learn import NCA
 >>> nca = NCA(random_state=42)
 >>> nca.fit(X, y)
 NCA(init='auto', max_iter=100, n_components=None,
   preprocessor=None, random_state=42, tol=None, verbose=False)
 
-
 Now that the estimator is fitted, you can use it on new data for several
 purposes.
 
-First, you can transform the data in the learned space, using `transform`:
-Here we transform two points in the new embedding space.
+First, your mahalanobis learner can transform the data in
+the learned space, using `transform`: Here we transform two points in
+the new embedding space.
 
 >>> X_new = np.array([[9.4, 4.1], [2.1, 4.4]])
 >>> nca.transform(X_new)
 array([[ 5.91884732, 10.25406973],
        [ 3.1545886 ,  6.80350083]])
 
-Also, as explained before, our metric learners has learn a distance between
-points. You can use this distance in two main ways:
+.. warning::
+
+    If you try to use `transform` with a similarity learner, an error will
+    appear, as you cannot transform the data using them.
+
+Also, as explained before, mahalanobis metric learners learn a distance
+between points. You can use this distance in two main ways:
 
 - You can either return the distance between pairs of points using the
   `pair_distance` function:
@@ -76,7 +87,8 @@ array([0.49627072, 3.65287282, 6.06079877])
 
 - Or you can return a function that will return the distance (in the new
   space) between two 1D arrays (the coordinates of the points in the original
-  space), similarly to distance functions in `scipy.spatial.distance`.
+  space), similarly to distance functions in `scipy.spatial.distance`. To
+  do that, use the `get_metric` method.
 
 >>> metric_fun = nca.get_metric()
 >>> metric_fun([3.5, 3.6], [5.6, 2.4])
@@ -94,17 +106,48 @@ This is useful because `pair_score` matches the **score** semantic of
 scikit-learn's `Classification metrics
 <https://scikit-learn.org/stable/modules/model_evaluation.html#classification-metrics>`_.
 
+For similarity learners `pair_distance` is not available, as they don't learn
+a distance. Intead you use `pair_score` that has the same behaviour but
+for similarity.
+
+>>> algorithm.pair_score([[[3.5, 3.6], [5.6, 2.4]], [[1.2, 4.2], [2.1, 6.4]], [[3.3, 7.8], [10.9, 0.1]]])
+array([-0.2312, 705.23, -72.8])
+
+.. warning::
+
+    If you try to use `pair_distance` with a similarity learner, an error
+    will appear, as they don't learn a distance nor a pseudo-distance.
+
+You can also call `get_metric` with similarity learners, and you will get
+a function that will return the similarity bewtween 1D arrays.
+
+>>> similarity_fun = algorithm.get_metric()
+>>> similarity_fun([3.5, 3.6], [5.6, 2.4])
+-0.04752
+
+For similarity learners and mahalanobis learners, `pair_score` is
+available. You can interpret that this function returns the **score**
+between points: the more the **score**, the closer the pairs and vice-versa.
+For mahalanobis learners, it is equal to the inverse of the distance.
+
 .. note::
 
     If the metric learner that you use learns a :ref:`Mahalanobis distance
-    <mahalanobis_distances>` (like it is the case for all algorithms
-    currently in metric-learn), you can get the plain learned Mahalanobis
+    <mahalanobis_distances>`, you can get the plain learned Mahalanobis
     matrix using `get_mahalanobis_matrix`.
 
     >>> nca.get_mahalanobis_matrix()
     array([[0.43680409, 0.89169412],
            [0.89169412, 1.9542479 ]])
 
+    If the metric learner that you use learns a :ref:`Bilinear similarity
+    <bilinear_similarity>`, you can get the plain learned Bilinear
+    matrix using `get_bilinear_matrix`.
+
+    >>> algorithm.get_bilinear_matrix()
+    array([[-0.72680409, -0.153213],
+           [1.45542269, 7.8135546 ]])
+
 
 Scikit-learn compatibility
 --------------------------

doc/weakly_supervised.rst

@@ -127,9 +127,16 @@ through the argument `preprocessor` (see below :ref:`fit_ws`)
 Fit, transform, and so on
 -------------------------
 
-The goal of weakly-supervised metric-learning algorithms is to transform
-points in a new space, in which the tuple-wise constraints between points
-are respected.
+Generally, the goal of weakly-supervised metric-learning algorithms is to
+transform points in a new space, in which the tuple-wise constraints between
+points are respected.
+
+But there are also some algorithms that learn a similarity, not a distance,
+thus the points cannot be transformed into a new space. But the goal is the
+same: respect the maximum number of constraints while learning the similarity.
+
+Weakly-supervised mahalanobis learners can transform points into a new space,
+and to do so, we fit the metric learner (example:`MMC`).
 
 >>> from metric_learn import MMC
 >>> mmc = MMC(random_state=42)
@@ -144,18 +151,23 @@ Or alternatively (using a preprocessor):
 >>> mmc = MMC(preprocessor=X, random_state=42)
 >>> mmc.fit(pairs_indice, y)
 
-
 Now that the estimator is fitted, you can use it on new data for several
 purposes.
 
-First, you can transform the data in the learned space, using `transform`:
-Here we transform two points in the new embedding space.
+First, your mahalanobis learner can transform the data in
+the learned space, using `transform`: Here we transform two points in
+the new embedding space.
 
 >>> X_new = np.array([[9.4, 4.1, 4.2], [2.1, 4.4, 2.3]])
 >>> mmc.transform(X_new)
 array([[-3.24667162e+01,  4.62622348e-07,  3.88325421e-08],
        [-3.61531114e+01,  4.86778289e-07,  2.12654397e-08]])
 
+.. warning::
+
+    If you try to use `transform` with a similarity learner, an error will
+    appear, as you cannot transform the data using them.
+
 Also, as explained before, our metric learner has learned a distance between
 points. You can use this distance in two main ways:
 
@@ -166,10 +178,10 @@ points. You can use this distance in two main ways:
 ...                  [[1.2, 4.2, 7.7], [2.1, 6.4, 0.9]]])
 array([7.27607365, 0.88853014])
 
-- Or you can return a function that will return the distance
-  (in the new space) between two 1D arrays (the coordinates of the points in
-  the original space), similarly to distance functions in
-  `scipy.spatial.distance`. To do that, use the `get_metric` method.
+- Or you can return a function that will return the distance (in the new
+  space) between two 1D arrays (the coordinates of the points in the original
+  space), similarly to distance functions in `scipy.spatial.distance`. To
+  do that, use the `get_metric` method.
 
 >>> metric_fun = mmc.get_metric()
 >>> metric_fun([3.5, 3.6, 5.2], [5.6, 2.4, 6.7])
@@ -187,17 +199,48 @@ array([-0.49627072, -3.65287282, -6.06079877])
   scikit-learn's `Classification metrics
   <https://scikit-learn.org/stable/modules/model_evaluation.html#classification-metrics>`_.
 
+For similarity learners `pair_distance` is not available, as they don't learn
+a distance. Intead you use `pair_score` that has the same behaviour but
+for similarity.
+
+>>> algorithm.pair_score([[[3.5, 3.6], [5.6, 2.4]], [[1.2, 4.2], [2.1, 6.4]], [[3.3, 7.8], [10.9, 0.1]]])
+array([-0.2312, 705.23, -72.8])
+
+.. warning::
+
+    If you try to use `pair_distance` with a similarity learner, an error
+    will appear, as they don't learn a distance nor a pseudo-distance.
+
+You can also call `get_metric` with similarity learners, and you will get
+a function that will return the similarity bewtween 1D arrays.
+
+>>> similarity_fun = algorithm.get_metric()
+>>> similarity_fun([3.5, 3.6], [5.6, 2.4])
+-0.04752
+
+For similarity learners and mahalanobis learners, `pair_score` is
+available. You can interpret that this function returns the **score**
+between points: the more the **score**, the closer the pairs and vice-versa.
+For mahalanobis learners, it is equal to the inverse of the distance.
+
 .. note::
 
     If the metric learner that you use learns a :ref:`Mahalanobis distance
-    <mahalanobis_distances>` (like it is the case for all algorithms
-    currently in metric-learn), you can get the plain Mahalanobis matrix using
-    `get_mahalanobis_matrix`.
-
->>> mmc.get_mahalanobis_matrix()
-array([[ 0.58603894, -5.69883982, -1.66614919],
-       [-5.69883982, 55.41743549, 16.20219519],
-       [-1.66614919, 16.20219519,  4.73697721]])
+    <mahalanobis_distances>`, you can get the plain learned Mahalanobis
+    matrix using `get_mahalanobis_matrix`.
+
+    >>> mmc.get_mahalanobis_matrix()
+    array([[ 0.58603894, -5.69883982, -1.66614919],
+        [-5.69883982, 55.41743549, 16.20219519],
+        [-1.66614919, 16.20219519,  4.73697721]])
+
+    If the metric learner that you use learns a :ref:`Bilinear similarity
+    <bilinear_similarity>`, you can get the plain learned Bilinear
+    matrix using `get_bilinear_matrix`.
+
+    >>> algorithm.get_bilinear_matrix()
+    array([[-0.72680409, -0.153213],
+           [1.45542269, 7.8135546 ]])
 
 .. _sklearn_compat_ws: