diff options
author | Rémi Flamary <remi.flamary@gmail.com> | 2019-06-24 17:13:33 +0200 |
---|---|---|
committer | Rémi Flamary <remi.flamary@gmail.com> | 2019-06-24 17:13:33 +0200 |
commit | 4e2f6b45662fe206414652ccc8f715c420f3b9cd (patch) | |
tree | e3b16e092590986db9a32014f9b1a53d2903b3e6 | |
parent | 8c935200558a1071d8df33bc752afed60e2f49f7 (diff) |
first shot part OT Wass
-rw-r--r-- | docs/source/howto.rst | 25 | ||||
-rw-r--r-- | docs/source/index.rst | 2 | ||||
-rw-r--r-- | docs/source/quickstart.rst | 119 | ||||
-rw-r--r-- | docs/source/readme.rst | 7 |
4 files changed, 126 insertions, 27 deletions
diff --git a/docs/source/howto.rst b/docs/source/howto.rst deleted file mode 100644 index 48b1532..0000000 --- a/docs/source/howto.rst +++ /dev/null @@ -1,25 +0,0 @@ - -How to ? -======== - -In the following we provide some pointers about which functions and classes -to use for different problems related to optimal transport (OTs). - -1. **How to solve a discrete optimal transport problem ?** - - The solver for discrete is the function :py:mod:`ot.emd` that returns - the OT transport matrix. If you want to solve a regularized OT you can - use :py:mod:`ot.sinkhorn`. - - More detailed examples can be seen on this :ref:`auto_examples/plot_OT_2D_samples` - - Here is a simple use case: - - .. code:: python - - # a,b are 1D histograms (sum to 1 and positive) - # M is the ground cost matrix - T=ot.emd(a,b,M) # exact linear program - T_reg=ot.sinkhorn(a,b,M,reg) # entropic regularized OT - - diff --git a/docs/source/index.rst b/docs/source/index.rst index d92f50f..03943e8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,7 +13,7 @@ Contents :maxdepth: 3 self - howto + quickstart all auto_examples/index diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 0000000..3d3ce98 --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,119 @@ + +Quick start +=========== + + + +In the following we provide some pointers about which functions and classes +to use for different problems related to optimal transport (OT). + + +Optimal transport and Wasserstein distance +------------------------------------------ + +The optimal transport problem between discrete distributions is often expressed +as + .. math:: + \gamma^* = arg\min_\gamma \sum_{i,j}\gamma_{i,j}M_{i,j} + + s.t. \gamma 1 = a; \gamma^T 1= b; \gamma\geq 0 + +where : + +- :math:`M\in\mathbb{R}_+^{m\times n}` is the metric cost matrix defining the cost to move mass from bin :math:`a_i` to bin :math:`b_j`. +- :math:`a` and :math:`b` are histograms (positive, sum to 1) that represent the weights of each samples in the source an target distributions. + +Solving the linear program above can be done using the function :any:`ot.emd` +that will return the optimal transport matrix :math:`\gamma^*`: + +.. code:: python + + # a,b are 1D histograms (sum to 1 and positive) + # M is the ground cost matrix + T=ot.emd(a,b,M) # exact linear program + +.. hint:: + Examples of use for :any:`ot.emd` are available in the following examples: + + - :any:`auto_examples/plot_OT_2D_samples` + - :any:`auto_examples/plot_OT_1D` + - :any:`auto_examples/plot_OT_L1_vs_L2` + + +The value of the OT solution is often more of interest that the OT matrix : + + .. math:: + W(a,b)=\min_\gamma \sum_{i,j}\gamma_{i,j}M_{i,j} + + s.t. \gamma 1 = a; \gamma^T 1= b; \gamma\geq 0 + + +where :math:`W(a,b)` is the `Wasserstein distance +<https://en.wikipedia.org/wiki/Wasserstein_metric>`_ between distributions a and b +It is a metrix that has nice statistical +properties. It can computed from an already estimated OT matrix with +:code:`np.sum(T*M)` or directly with the function :any:`ot.emd2`. + +.. code:: python + + # a,b are 1D histograms (sum to 1 and positive) + # M is the ground cost matrix + W=ot.emd2(a,b,M) # Wasserstein distance / EMD value + +.. note:: + In POT, most functions that solve OT or regularized OT problems have two + versions that return the OT matrix or the value of the optimal solution. Fir + instance :any:`ot.emd` return the OT matrix and :any:`ot.emd2` return the + Wassertsein distance. + + +Regularized Optimal Transport +----------------------------- + +Wasserstein Barycenters +----------------------- + +Monge mapping and Domain adaptation with Optimal transport +---------------------------------------- + + +Other applications +------------------ + + +GPU acceleration +---------------- + + + +How to? +------- + + + +1. **How to solve a discrete optimal transport problem ?** + + The solver for discrete is the function :py:mod:`ot.emd` that returns + the OT transport matrix. If you want to solve a regularized OT you can + use :py:mod:`ot.sinkhorn`. + + + + Here is a simple use case: + + .. code:: python + + # a,b are 1D histograms (sum to 1 and positive) + # M is the ground cost matrix + T=ot.emd(a,b,M) # exact linear program + T_reg=ot.sinkhorn(a,b,M,reg) # entropic regularized OT + + More detailed examples can be seen on this + :doc:`auto_examples/plot_OT_2D_samples` + + +2. **Compute a Wasserstein distance** + + + + diff --git a/docs/source/readme.rst b/docs/source/readme.rst index d1063e8..b7828d3 100644 --- a/docs/source/readme.rst +++ b/docs/source/readme.rst @@ -206,7 +206,12 @@ nbviewer <https://nbviewer.jupyter.org/github/rflamary/POT/tree/master/notebooks Acknowledgements ---------------- -The contributors to this library are: +This toolbox has been created and is maintained by + +- `Rémi Flamary <http://remi.flamary.com/>`__ +- `Nicolas Courty <http://people.irisa.fr/Nicolas.Courty/>`__ + +The contributors to this library are - `Rémi Flamary <http://remi.flamary.com/>`__ - `Nicolas Courty <http://people.irisa.fr/Nicolas.Courty/>`__ |