From 429abe06d53e1ebdd2492b275f70ba1bfe751f0f Mon Sep 17 00:00:00 2001 From: Laetitia Chapel Date: Fri, 17 Apr 2020 11:49:28 +0200 Subject: partial added on quick start guide --- ot/partial.py | 68 +++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 52 insertions(+), 16 deletions(-) (limited to 'ot/partial.py') diff --git a/ot/partial.py b/ot/partial.py index d32e054..f325d98 100755 --- a/ot/partial.py +++ b/ot/partial.py @@ -1,4 +1,3 @@ -#!/usr/bin/env python3 # -*- coding: utf-8 -*- """ Partial OT @@ -30,7 +29,9 @@ def partial_wasserstein_lagrange(a, b, M, reg_m=None, nb_dummies=1, log=False, 1^T \gamma^T 1 = m \leq \min\{\|a\|_1, \|b\|_1\} - or equivalently: + or equivalently (see Chizat, L., Peyré, G., Schmitzer, B., & Vialard, F. X. + (2018). An interpolating distance between optimal transport and Fisher–Rao + metrics. Foundations of Computational Mathematics, 18(1), 1-44.) .. math:: \gamma = \arg\min_\gamma <\gamma,M>_F + \sqrt(\lambda/2) @@ -47,7 +48,8 @@ def partial_wasserstein_lagrange(a, b, M, reg_m=None, nb_dummies=1, log=False, - :math:`\lambda` is the lagragian cost. Tuning its value allows attaining a given mass to be transported m - The formulation of the problem has been proposed in [26]_ + The formulation of the problem has been proposed in [28]_ + Parameters ---------- @@ -59,9 +61,17 @@ def partial_wasserstein_lagrange(a, b, M, reg_m=None, nb_dummies=1, log=False, cost matrix for the quadratic cost reg_m : float, optional Lagragian cost + nb_dummies : int, optional, default:1 + number of reservoir points to be added (to avoid numerical + instabilities, increase its value if an error is raised) log : bool, optional record log if True + .. warning:: + When dealing with a large number of points, the EMD solver may face + some instabilities, especially when the mass associated to the dummy + point is large. To avoid them, increase the number of dummy points + (allows a smoother repartition of the mass over the points). Returns ------- @@ -88,7 +98,7 @@ def partial_wasserstein_lagrange(a, b, M, reg_m=None, nb_dummies=1, log=False, References ---------- - .. [26] Caffarelli, L. A., & McCann, R. J. (2010) Free boundaries in + .. [28] Caffarelli, L. A., & McCann, R. J. (2010) Free boundaries in optimal transport and Monge-Ampere obstacle problems. Annals of mathematics, 673-730. @@ -182,6 +192,13 @@ def partial_wasserstein(a, b, M, m=None, nb_dummies=1, log=False, **kwargs): record log if True + .. warning:: + When dealing with a large number of points, the EMD solver may face + some instabilities, especially when the mass associated to the dummy + point is large. To avoid them, increase the number of dummy points + (allows a smoother repartition of the mass over the points). + + Returns ------- :math:`gamma` : (dim_a x dim_b) ndarray @@ -206,10 +223,10 @@ def partial_wasserstein(a, b, M, m=None, nb_dummies=1, log=False, **kwargs): References ---------- - .. [26] Caffarelli, L. A., & McCann, R. J. (2010) Free boundaries in + .. [28] Caffarelli, L. A., & McCann, R. J. (2010) Free boundaries in optimal transport and Monge-Ampere obstacle problems. Annals of mathematics, 673-730. - .. [28] Chapel, L., Alaya, M., Gasso, G. (2019). "Partial Gromov- + .. [29] Chapel, L., Alaya, M., Gasso, G. (2019). "Partial Gromov- Wasserstein with Applications on Positive-Unlabeled Learning". arXiv preprint arXiv:2002.08276. @@ -289,6 +306,13 @@ def partial_wasserstein2(a, b, M, m=None, nb_dummies=1, log=False, **kwargs): record log if True + .. warning:: + When dealing with a large number of points, the EMD solver may face + some instabilities, especially when the mass associated to the dummy + point is large. To avoid them, increase the number of dummy points + (allows a smoother repartition of the mass over the points). + + Returns ------- :math:`gamma` : (dim_a x dim_b) ndarray @@ -311,10 +335,10 @@ def partial_wasserstein2(a, b, M, m=None, nb_dummies=1, log=False, **kwargs): References ---------- - .. [26] Caffarelli, L. A., & McCann, R. J. (2010) Free boundaries in + .. [28] Caffarelli, L. A., & McCann, R. J. (2010) Free boundaries in optimal transport and Monge-Ampere obstacle problems. Annals of mathematics, 673-730. - .. [28] Chapel, L., Alaya, M., Gasso, G. (2019). "Partial Gromov- + .. [29] Chapel, L., Alaya, M., Gasso, G. (2019). "Partial Gromov- Wasserstein with Applications on Positive-Unlabeled Learning". arXiv preprint arXiv:2002.08276. """ @@ -411,7 +435,7 @@ def partial_gromov_wasserstein(C1, C2, p, q, m=None, nb_dummies=1, G0=None, - a and b are the sample weights - m is the amount of mass to be transported - The formulation of the problem has been proposed in [28]_ + The formulation of the problem has been proposed in [29]_ Parameters @@ -435,13 +459,12 @@ def partial_gromov_wasserstein(C1, C2, p, q, m=None, nb_dummies=1, G0=None, (default: 1) numItermax : int, optional Max number of iterations + tol : float, optional + tolerance for stopping iterations log : bool, optional return log if True verbose : bool, optional Print information along iterations - armijo : bool, optional - If True the steps of the line-search is found via an armijo research. Else closed form is used. - If there is convergence issues use False. **kwargs : dict parameters can be directly passed to the emd solver @@ -477,7 +500,7 @@ def partial_gromov_wasserstein(C1, C2, p, q, m=None, nb_dummies=1, G0=None, References ---------- - .. [28] Chapel, L., Alaya, M., Gasso, G. (2019). "Partial Gromov- + .. [29] Chapel, L., Alaya, M., Gasso, G. (2019). "Partial Gromov- Wasserstein with Applications on Positive-Unlabeled Learning". arXiv preprint arXiv:2002.08276. @@ -546,7 +569,7 @@ def partial_gromov_wasserstein(C1, C2, p, q, m=None, nb_dummies=1, G0=None, def partial_gromov_wasserstein2(C1, C2, p, q, m=None, nb_dummies=1, G0=None, - thres=0.75, numItermax=1000, tol=1e-7, + thres=1, numItermax=1000, tol=1e-7, log=False, verbose=False, **kwargs): r""" Solves the partial optimal transport problem @@ -570,7 +593,7 @@ def partial_gromov_wasserstein2(C1, C2, p, q, m=None, nb_dummies=1, G0=None, - a and b are the sample weights - m is the amount of mass to be transported - The formulation of the problem has been proposed in [28]_ + The formulation of the problem has been proposed in [29]_ Parameters @@ -594,6 +617,8 @@ def partial_gromov_wasserstein2(C1, C2, p, q, m=None, nb_dummies=1, G0=None, (default: 1) numItermax : int, optional Max number of iterations + tol : float, optional + tolerance for stopping iterations log : bool, optional return log if True verbose : bool, optional @@ -602,6 +627,13 @@ def partial_gromov_wasserstein2(C1, C2, p, q, m=None, nb_dummies=1, G0=None, parameters can be directly passed to the emd solver + .. warning:: + When dealing with a large number of points, the EMD solver may face + some instabilities, especially when the mass associated to the dummy + point is large. To avoid them, increase the number of dummy points + (allows a smoother repartition of the mass over the points). + + Returns ------- partial_gw_dist : (dim_a x dim_b) ndarray @@ -627,7 +659,7 @@ def partial_gromov_wasserstein2(C1, C2, p, q, m=None, nb_dummies=1, G0=None, References ---------- - .. [28] Chapel, L., Alaya, M., Gasso, G. (2019). "Partial Gromov- + .. [29] Chapel, L., Alaya, M., Gasso, G. (2019). "Partial Gromov- Wasserstein with Applications on Positive-Unlabeled Learning". arXiv preprint arXiv:2002.08276. @@ -831,6 +863,8 @@ def entropic_partial_gromov_wasserstein(C1, C2, p, q, reg, m=None, G0=None, Initialisation of the transportation matrix numItermax : int, optional Max number of iterations + tol : float, optional + Stop threshold on error (>0) log : bool, optional return log if True verbose : bool, optional @@ -966,6 +1000,8 @@ def entropic_partial_gromov_wasserstein2(C1, C2, p, q, reg, m=None, G0=None, Initialisation of the transportation matrix numItermax : int, optional Max number of iterations + tol : float, optional + Stop threshold on error (>0) log : bool, optional return log if True verbose : bool, optional -- cgit v1.2.3