iframe-proxy | Sunbelt Computer Software

674 lines (632 loc) · 79.2 KB
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>ot.coot &mdash; POT Python Optimal Transport 0.9.6 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
      <link rel="stylesheet" type="text/css" href="../_static/sg_gallery.css?v=d2d258e8" />
      <link rel="stylesheet" type="text/css" href="../_static/sg_gallery-binder.css?v=f4aeca0c" />
      <link rel="stylesheet" type="text/css" href="../_static/sg_gallery-dataframe.css?v=2082cf3c" />
      <link rel="stylesheet" type="text/css" href="../_static/sg_gallery-rendered-html.css?v=1277b6f3" />
      <script src="../_static/jquery.js?v=5d32c60e"></script>
      <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
      <script src="../_static/documentation_options.js?v=564a08b9"></script>
      <script src="../_static/doctools.js?v=9bcbadda"></script>
      <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
      <script async="async" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="ot.da" href="ot.da.html" />
    <link rel="prev" title="ot.bregman" href="ot.bregman.html" /> 
<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >
          <a href="../index.html" class="icon icon-home">
            POT Python Optimal Transport
              <img src="../_static/logo_dark.svg" class="logo" alt="Logo"/>
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html">POT: Python Optimal Transport</a></li>
<li class="toctree-l1"><a class="reference internal" href="../auto_examples/plot_quickstart_guide.html">Quickstart Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../auto_examples/index.html">Examples gallery</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user_guide.html">User guide</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../all.html">API and modules</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="ot.backend.html">ot.backend</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.batch.html">ot.batch</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.bregman.html">ot.bregman</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">ot.coot</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#functions">Functions</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#ot.coot.co_optimal_transport"><code class="docutils literal notranslate"><span class="pre">co_optimal_transport()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#examples-using-ot-coot-co-optimal-transport">Examples using <code class="docutils literal notranslate"><span class="pre">ot.coot.co_optimal_transport</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#examples-using-ot-coot-co-optimal-transport2">Examples using <code class="docutils literal notranslate"><span class="pre">ot.coot.co_optimal_transport2</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.da.html">ot.da</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.datasets.html">ot.datasets</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.dr.html">ot.dr</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.factored.html">ot.factored</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.gaussian.html">ot.gaussian</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.gmm.html">ot.gmm</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.gnn.html">ot.gnn</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.gromov.html">ot.gromov</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.lowrank.html">ot.lowrank</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.lp.html">ot.lp</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.mapping.html">ot.mapping</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.optim.html">ot.optim</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.partial.html">ot.partial</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.plot.html">ot.plot</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.regpath.html">ot.regpath</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.sliced.html">ot.sliced</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.smooth.html">ot.smooth</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.stochastic.html">ot.stochastic</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.unbalanced.html">ot.unbalanced</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.utils.html">ot.utils</a></li>
<li class="toctree-l2"><a class="reference internal" href="ot.weak.html">ot.weak</a></li>
<li class="toctree-l2"><a class="reference internal" href="../all.html#module-ot">Main <code class="xref py py-mod docutils literal notranslate"><span class="pre">ot</span></code> functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releases.html">Releases</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributors.html">Contributors</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">Contributing to POT</a></li>
<li class="toctree-l1"><a class="reference internal" href="../code_of_conduct.html">Code of conduct</a></li>
        </div>
      </div>
    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">POT Python Optimal Transport</a>
      </nav>
      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="../all.html">API and modules</a></li>
      <li class="breadcrumb-item active">ot.coot</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../_sources/gen_modules/ot.coot.rst.txt" rel="nofollow"> View page source</a>
      </li>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
  <section id="module-ot.coot">
<span id="ot-coot"></span><h1>ot.coot<a class="headerlink" href="#module-ot.coot" title="Link to this heading"></a></h1>
<p>CO-Optimal Transport solver</p>
<section id="functions">
<h2>Functions<a class="headerlink" href="#functions" title="Link to this heading"></a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="ot.coot.co_optimal_transport">
<span class="sig-prename descclassname"><span class="pre">ot.coot.</span></span><span class="sig-name descname"><span class="pre">co_optimal_transport</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">X</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">Y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wx_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wx_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wy_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wy_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">epsilon</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">alpha</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">M_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">M_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">warmstart</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nits_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">100</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tol_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-07</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">eval_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nits_ot</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">500</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tol_sinkhorn</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-07</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">method_sinkhorn</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'sinkhorn'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">early_stopping_tol</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-06</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">log</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbose</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/ot/coot.html#co_optimal_transport"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#ot.coot.co_optimal_transport" title="Link to this definition"></a></dt>
<dd><p>Compute the CO-Optimal Transport between two matrices.</p>
<p>Return the sample and feature transport plans between
<span class="math notranslate nohighlight">\((\mathbf{X}, \mathbf{w}_{xs}, \mathbf{w}_{xf})\)</span> and
<span class="math notranslate nohighlight">\((\mathbf{Y}, \mathbf{w}_{ys}, \mathbf{w}_{yf})\)</span>.</p>
<p>The function solves the following CO-Optimal Transport (COOT) problem:</p>
<div class="math notranslate nohighlight">
\[\begin{split}\mathbf{COOT}_{\alpha, \varepsilon} = \mathop{\arg \min}_{\mathbf{P}, \mathbf{Q}}
&amp;\quad \sum_{i,j,k,l}
(\mathbf{X}_{i,k} - \mathbf{Y}_{j,l})^2 \mathbf{P}_{i,j} \mathbf{Q}_{k,l}
+ \alpha_s \sum_{i,j} \mathbf{P}_{i,j} \mathbf{M^{(s)}}_{i, j} \\
&amp;+ \alpha_f \sum_{k, l} \mathbf{Q}_{k,l} \mathbf{M^{(f)}}_{k, l}
+ \varepsilon_s \mathbf{KL}(\mathbf{P} | \mathbf{w}_{xs} \mathbf{w}_{ys}^T)
+ \varepsilon_f \mathbf{KL}(\mathbf{Q} | \mathbf{w}_{xf} \mathbf{w}_{yf}^T)\end{split}\]</div>
<p>Where :</p>
<ul class="simple">
<li><p><span class="math notranslate nohighlight">\(\mathbf{X}\)</span>: Data matrix in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{Y}\)</span>: Data matrix in the target space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{M^{(s)}}\)</span>: Additional sample matrix</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{M^{(f)}}\)</span>: Additional feature matrix</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{xs}\)</span>: Distribution of the samples in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{xf}\)</span>: Distribution of the features in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{ys}\)</span>: Distribution of the samples in the target space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{yf}\)</span>: Distribution of the features in the target space</p></li>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This function allows epsilon to be zero.
In that case, the <a class="reference internal" href="ot.lp.html#ot.lp.emd" title="ot.lp.emd"><code class="xref any py py-func docutils literal notranslate"><span class="pre">ot.lp.emd</span></code></a> solver of POT will be used.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>X</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>n_feature_x</em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a>) – First input matrix.</p></li>
<li><p><strong>Y</strong> (<em>(</em><em>n_sample_y</em><em>, </em><em>n_feature_y</em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a>) – Second input matrix.</p></li>
<li><p><strong>wx_samp</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on rows (samples) of matrix X.
Uniform distribution by default.</p></li>
<li><p><strong>wx_feat</strong> (<em>(</em><em>n_feature_x</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on columns (features) of matrix X.
Uniform distribution by default.</p></li>
<li><p><strong>wy_samp</strong> (<em>(</em><em>n_sample_y</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on rows (samples) of matrix Y.
Uniform distribution by default.</p></li>
<li><p><strong>wy_feat</strong> (<em>(</em><em>n_feature_y</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on columns (features) of matrix Y.
Uniform distribution by default.</p></li>
<li><p><strong>epsilon</strong> (<em>scalar</em><em> or </em><em>indexable object</em><em> of </em><em>length 2</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 0</em><em>)</em>) – Regularization parameters for entropic approximation of sample and feature couplings.
Allow the case where epsilon contains 0. In that case, the EMD solver is used instead of
Sinkhorn solver. If epsilon is scalar, then the same epsilon is applied to
both regularization of sample and feature couplings.</p></li>
<li><p><strong>alpha</strong> (<em>scalar</em><em> or </em><em>indexable object</em><em> of </em><em>length 2</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 0</em><em>)</em>) – Coefficient parameter of linear terms with respect to the sample and feature couplings.
If alpha is scalar, then the same alpha is applied to both linear terms.</p></li>
<li><p><strong>M_samp</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>n_sample_y</em><em>)</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Sample matrix with respect to the linear term on sample coupling.</p></li>
<li><p><strong>M_feat</strong> (<em>(</em><em>n_feature_x</em><em>, </em><em>n_feature_y</em><em>)</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Feature matrix with respect to the linear term on feature coupling.</p></li>
<li><p><strong>warmstart</strong> (<em>dictionary</em><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – <dl class="simple">
<dt>Contains 4 keys:</dt><dd><ul>
<li><p>”duals_sample” and “duals_feature” whose values are
tuples of 2 vectors of size (n_sample_x, n_sample_y) and (n_feature_x, n_feature_y).
Initialization of sample and feature dual vectors
if using Sinkhorn algorithm. Zero vectors by default.</p></li>
<li><p>”pi_sample” and “pi_feature” whose values are matrices
of size (n_sample_x, n_sample_y) and (n_feature_x, n_feature_y).
Initialization of sample and feature couplings.
Uniform distributions by default.</p></li>
<li><p><strong>nits_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 100</em><em>)</em>) – Number of Block Coordinate Descent (BCD) iterations to solve COOT.</p></li>
<li><p><strong>tol_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-7</em><em>)</em>) – Tolerance of BCD scheme. If the L1-norm between the current and previous
sample couplings is under this threshold, then stop BCD scheme.</p></li>
<li><p><strong>eval_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1</em><em>)</em>) – Multiplier of iteration at which the COOT cost is evaluated. For example,
if <cite>eval_bcd = 8</cite>, then the cost is calculated at iterations 8, 16, 24, etc…</p></li>
<li><p><strong>nits_ot</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 100</em><em>)</em>) – Number of iterations to solve each of the
two optimal transport problems in each BCD iteration.</p></li>
<li><p><strong>tol_sinkhorn</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-7</em><em>)</em>) – Tolerance of Sinkhorn algorithm to stop the Sinkhorn scheme for
entropic optimal transport problem (if any) in each BCD iteration.
Only triggered when Sinkhorn solver is used.</p></li>
<li><p><strong>method_sinkhorn</strong> (<em>string</em><em>, </em><em>optional</em><em> (</em><em>default = &quot;sinkhorn&quot;</em><em>)</em>) – Method used in POT’s <cite>ot.sinkhorn</cite> solver.
Only support “sinkhorn” and “sinkhorn_log”.</p></li>
<li><p><strong>early_stopping_tol</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-6</em><em>)</em>) – Tolerance for the early stopping. If the absolute difference between
the last 2 recorded COOT distances is under this tolerance, then stop BCD scheme.</p></li>
<li><p><strong>log</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><em>bool</em></a><em>, </em><em>optional</em><em> (</em><em>default = False</em><em>)</em>) – If True then the cost and 4 dual vectors, including
2 from sample and 2 from feature couplings, are recorded.</p></li>
<li><p><strong>verbose</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><em>bool</em></a><em>, </em><em>optional</em><em> (</em><em>default = False</em><em>)</em>) – If True then print the COOT cost at every multiplier of <cite>eval_bcd</cite>-th iteration.</p></li>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><ul>
<li><p><strong>pi_samp</strong> (<em>(n_sample_x, n_sample_y) array-like, float</em>) – Sample coupling matrix.</p></li>
<li><p><strong>pi_feat</strong> (<em>(n_feature_x, n_feature_y) array-like, float</em>) – Feature coupling matrix.</p></li>
<li><p><strong>log</strong> (<em>dictionary, optional</em>) –</p>
<dl class="simple">
<dt>Returned if <cite>log</cite> is True. The keys are:</dt><dd><dl class="simple">
<dt>duals_sample<span class="classifier">(n_sample_x, n_sample_y) tuple, float</span></dt><dd><p>Pair of dual vectors when solving OT problem w.r.t the sample coupling.</p>
<dt>duals_feature<span class="classifier">(n_feature_x, n_feature_y) tuple, float</span></dt><dd><p>Pair of dual vectors when solving OT problem w.r.t the feature coupling.</p>
<dt>distances<span class="classifier">list, float</span></dt><dd><p>List of COOT distances along iterations.</p>
<p class="rubric">References</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id1" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>49<span class="fn-bracket">]</span></span>
<p>I. Redko, T. Vayer, R. Flamary, and N. Courty, CO-Optimal Transport,
Advances in Neural Information Processing ny_sampstems, 33 (2020).</p>
<section id="examples-using-ot-coot-co-optimal-transport">
<h3>Examples using <code class="docutils literal notranslate"><span class="pre">ot.coot.co_optimal_transport</span></code><a class="headerlink" href="#examples-using-ot-coot-co-optimal-transport" title="Link to this heading"></a></h3>
<div class="sphx-glr-thumbnails"><div class="sphx-glr-thumbcontainer" tooltip="This example is designed to show how to use the CO-Optimal Transport [47]_ in POT. CO-Optimal Transport allows to calculate the distance between two arbitrary-size matrices, and to align their rows and columns. In this example, we consider two random matrices X_1 and X_2 defined by (X_1)_{i,j} = \cos(\frac{i}{n_1} \pi) + \cos(\frac{j}{d_1} \pi) + \sigma \mathcal N(0,1) and (X_2)_{i,j} = \cos(\frac{i}{n_2} \pi) + \cos(\frac{j}{d_2} \pi) + \sigma \mathcal N(0,1)."><img alt="" src="../_images/sphx_glr_plot_COOT_thumb.png" />
<p><a class="reference internal" href="../auto_examples/others/plot_COOT.html#sphx-glr-auto-examples-others-plot-coot-py"><span class="std std-ref">Row and column alignments with CO-Optimal Transport</span></a></p>
  <div class="sphx-glr-thumbnail-title">Row and column alignments with CO-Optimal Transport</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="In this example, we consider two point clouds living in different Euclidean spaces, where the outliers are artificially injected into the target data. We illustrate two methods which allow to filter out these outliers."><img alt="" src="../_images/sphx_glr_plot_outlier_detection_with_COOT_and_unbalanced_COOT_thumb.png" />
<p><a class="reference internal" href="../auto_examples/others/plot_outlier_detection_with_COOT_and_unbalanced_COOT.html#sphx-glr-auto-examples-others-plot-outlier-detection-with-coot-and-unbalanced-coot-py"><span class="std std-ref">Detecting outliers by learning sample marginal distribution with CO-Optimal Transport and by using unbalanced Co-Optimal Transport</span></a></p>
  <div class="sphx-glr-thumbnail-title">Detecting outliers by learning sample marginal distribution with CO-Optimal Transport and by using unbalanced Co-Optimal Transport</div>
</div></div><div class="sphx-glr-clear"></div><dl class="py function">
<dt class="sig sig-object py" id="ot.coot.co_optimal_transport2">
<span class="sig-prename descclassname"><span class="pre">ot.coot.</span></span><span class="sig-name descname"><span class="pre">co_optimal_transport2</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">X</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">Y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wx_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wx_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wy_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wy_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">epsilon</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">alpha</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">M_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">M_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">warmstart</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">log</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbose</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">early_stopping_tol</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-06</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nits_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">100</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tol_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-07</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">eval_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nits_ot</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">500</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tol_sinkhorn</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-07</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">method_sinkhorn</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'sinkhorn'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/ot/coot.html#co_optimal_transport2"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#ot.coot.co_optimal_transport2" title="Link to this definition"></a></dt>
<dd><p>Compute the CO-Optimal Transport distance between two measures.</p>
<p>Returns the CO-Optimal Transport distance between
<span class="math notranslate nohighlight">\((\mathbf{X}, \mathbf{w}_{xs}, \mathbf{w}_{xf})\)</span> and
<span class="math notranslate nohighlight">\((\mathbf{Y}, \mathbf{w}_{ys}, \mathbf{w}_{yf})\)</span>.</p>
<p>The function solves the following CO-Optimal Transport (COOT) problem:</p>
<div class="math notranslate nohighlight">
\[\begin{split}\mathbf{COOT}_{\alpha, \varepsilon} = \mathop{\arg \min}_{\mathbf{P}, \mathbf{Q}}
&amp;\quad \sum_{i,j,k,l}
(\mathbf{X}_{i,k} - \mathbf{Y}_{j,l})^2 \mathbf{P}_{i,j} \mathbf{Q}_{k,l}
+ \alpha_1 \sum_{i,j} \mathbf{P}_{i,j} \mathbf{M^{(s)}}_{i, j} \\
&amp;+ \alpha_2 \sum_{k, l} \mathbf{Q}_{k,l} \mathbf{M^{(f)}}_{k, l}
+ \varepsilon_1 \mathbf{KL}(\mathbf{P} | \mathbf{w}_{xs} \mathbf{w}_{ys}^T)
+ \varepsilon_2 \mathbf{KL}(\mathbf{Q} | \mathbf{w}_{xf} \mathbf{w}_{yf}^T)\end{split}\]</div>
<p>where :</p>
<ul class="simple">
<li><p><span class="math notranslate nohighlight">\(\mathbf{X}\)</span>: Data matrix in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{Y}\)</span>: Data matrix in the target space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{M^{(s)}}\)</span>: Additional sample matrix</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{M^{(f)}}\)</span>: Additional feature matrix</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{xs}\)</span>: Distribution of the samples in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{xf}\)</span>: Distribution of the features in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{ys}\)</span>: Distribution of the samples in the target space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{yf}\)</span>: Distribution of the features in the target space</p></li>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This function allows epsilon to be zero.
In that case, the <a class="reference internal" href="ot.lp.html#ot.lp.emd" title="ot.lp.emd"><code class="xref any py py-func docutils literal notranslate"><span class="pre">ot.lp.emd</span></code></a> solver of POT will be used.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>X</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>n_feature_x</em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a>) – First input matrix.</p></li>
<li><p><strong>Y</strong> (<em>(</em><em>n_sample_y</em><em>, </em><em>n_feature_y</em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a>) – Second input matrix.</p></li>
<li><p><strong>wx_samp</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on rows (samples) of matrix X.
Uniform distribution by default.</p></li>
<li><p><strong>wx_feat</strong> (<em>(</em><em>n_feature_x</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on columns (features) of matrix X.
Uniform distribution by default.</p></li>
<li><p><strong>wy_samp</strong> (<em>(</em><em>n_sample_y</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on rows (samples) of matrix Y.
Uniform distribution by default.</p></li>
<li><p><strong>wy_feat</strong> (<em>(</em><em>n_feature_y</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on columns (features) of matrix Y.
Uniform distribution by default.</p></li>
<li><p><strong>epsilon</strong> (<em>scalar</em><em> or </em><em>indexable object</em><em> of </em><em>length 2</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 0</em><em>)</em>) – Regularization parameters for entropic approximation of sample and feature couplings.
Allow the case where epsilon contains 0. In that case, the EMD solver is used instead of
Sinkhorn solver. If epsilon is scalar, then the same epsilon is applied to
both regularization of sample and feature couplings.</p></li>
<li><p><strong>alpha</strong> (<em>scalar</em><em> or </em><em>indexable object</em><em> of </em><em>length 2</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 0</em><em>)</em>) – Coefficient parameter of linear terms with respect to the sample and feature couplings.
If alpha is scalar, then the same alpha is applied to both linear terms.</p></li>
<li><p><strong>M_samp</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>n_sample_y</em><em>)</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Sample matrix with respect to the linear term on sample coupling.</p></li>
<li><p><strong>M_feat</strong> (<em>(</em><em>n_feature_x</em><em>, </em><em>n_feature_y</em><em>)</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Feature matrix with respect to the linear term on feature coupling.</p></li>
<li><p><strong>warmstart</strong> (<em>dictionary</em><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – <dl>
<dt>Contains 4 keys:</dt><dd><ul>
<li><p>”duals_sample” and “duals_feature” whose values are</p></li>
<p>tuples of 2 vectors of size (n_sample_x, n_sample_y) and (n_feature_x, n_feature_y).
Initialization of sample and feature dual vectors
if using Sinkhorn algorithm. Zero vectors by default.
- “pi_sample” and “pi_feature” whose values are matrices
of size (n_sample_x, n_sample_y) and (n_feature_x, n_feature_y).
Initialization of sample and feature couplings.
Uniform distributions by default.</p>
<li><p><strong>nits_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 100</em><em>)</em>) – Number of Block Coordinate Descent (BCD) iterations to solve COOT.</p></li>
<li><p><strong>tol_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-7</em><em>)</em>) – Tolerance of BCD scheme. If the L1-norm between the current and previous
sample couplings is under this threshold, then stop BCD scheme.</p></li>
<li><p><strong>eval_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1</em><em>)</em>) – Multiplier of iteration at which the COOT cost is evaluated. For example,
if <cite>eval_bcd = 8</cite>, then the cost is calculated at iterations 8, 16, 24, etc…</p></li>
<li><p><strong>nits_ot</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 100</em><em>)</em>) – Number of iterations to solve each of the
two optimal transport problems in each BCD iteration.</p></li>
<li><p><strong>tol_sinkhorn</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-7</em><em>)</em>) – Tolerance of Sinkhorn algorithm to stop the Sinkhorn scheme for
entropic optimal transport problem (if any) in each BCD iteration.
Only triggered when Sinkhorn solver is used.</p></li>
<li><p><strong>method_sinkhorn</strong> (<em>string</em><em>, </em><em>optional</em><em> (</em><em>default = &quot;sinkhorn&quot;</em><em>)</em>) – Method used in POT’s <cite>ot.sinkhorn</cite> solver.
Only support “sinkhorn” and “sinkhorn_log”.</p></li>
<li><p><strong>early_stopping_tol</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-6</em><em>)</em>) – Tolerance for the early stopping. If the absolute difference between
the last 2 recorded COOT distances is under this tolerance, then stop BCD scheme.</p></li>
<li><p><strong>log</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><em>bool</em></a><em>, </em><em>optional</em><em> (</em><em>default = False</em><em>)</em>) – If True then the cost and 4 dual vectors, including
2 from sample and 2 from feature couplings, are recorded.</p></li>
<li><p><strong>verbose</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><em>bool</em></a><em>, </em><em>optional</em><em> (</em><em>default = False</em><em>)</em>) – If True then print the COOT cost at every multiplier of <cite>eval_bcd</cite>-th iteration.</p></li>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><ul class="simple">
<li><p><em>float</em> – CO-Optimal Transport distance.</p></li>
<li><p><em>dict</em> – Contains logged information from <a class="reference internal" href="#id0" title="ot.coot.co_optimal_transport"><code class="xref any py py-func docutils literal notranslate"><span class="pre">co_optimal_transport</span></code></a> solver.
Only returned if <cite>log</cite> parameter is True</p></li>
<p class="rubric">References</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id2" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>47<span class="fn-bracket">]</span></span>
<p>I. Redko, T. Vayer, R. Flamary, and N. Courty, CO-Optimal Transport,
Advances in Neural Information Processing ny_sampstems, 33 (2020).</p>
<section id="examples-using-ot-coot-co-optimal-transport2">
<h3>Examples using <code class="docutils literal notranslate"><span class="pre">ot.coot.co_optimal_transport2</span></code><a class="headerlink" href="#examples-using-ot-coot-co-optimal-transport2" title="Link to this heading"></a></h3>
<div class="sphx-glr-thumbnails"><div class="sphx-glr-thumbcontainer" tooltip="This example is designed to show how to use the CO-Optimal Transport [47]_ in POT. CO-Optimal Transport allows to calculate the distance between two arbitrary-size matrices, and to align their rows and columns. In this example, we consider two random matrices X_1 and X_2 defined by (X_1)_{i,j} = \cos(\frac{i}{n_1} \pi) + \cos(\frac{j}{d_1} \pi) + \sigma \mathcal N(0,1) and (X_2)_{i,j} = \cos(\frac{i}{n_2} \pi) + \cos(\frac{j}{d_2} \pi) + \sigma \mathcal N(0,1)."><img alt="" src="../_images/sphx_glr_plot_COOT_thumb.png" />
<p><a class="reference internal" href="../auto_examples/others/plot_COOT.html#sphx-glr-auto-examples-others-plot-coot-py"><span class="std std-ref">Row and column alignments with CO-Optimal Transport</span></a></p>
  <div class="sphx-glr-thumbnail-title">Row and column alignments with CO-Optimal Transport</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="In this example, we consider two point clouds living in different Euclidean spaces, where the outliers are artificially injected into the target data. We illustrate two methods which allow to filter out these outliers."><img alt="" src="../_images/sphx_glr_plot_outlier_detection_with_COOT_and_unbalanced_COOT_thumb.png" />
<p><a class="reference internal" href="../auto_examples/others/plot_outlier_detection_with_COOT_and_unbalanced_COOT.html#sphx-glr-auto-examples-others-plot-outlier-detection-with-coot-and-unbalanced-coot-py"><span class="std std-ref">Detecting outliers by learning sample marginal distribution with CO-Optimal Transport and by using unbalanced Co-Optimal Transport</span></a></p>
  <div class="sphx-glr-thumbnail-title">Detecting outliers by learning sample marginal distribution with CO-Optimal Transport and by using unbalanced Co-Optimal Transport</div>
</div></div><div class="sphx-glr-clear"></div><dl class="py function">
<dt class="sig sig-object py" id="id0">
<span class="sig-prename descclassname"><span class="pre">ot.coot.</span></span><span class="sig-name descname"><span class="pre">co_optimal_transport</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">X</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">Y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wx_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wx_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wy_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wy_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">epsilon</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">alpha</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">M_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">M_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">warmstart</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nits_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">100</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tol_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-07</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">eval_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nits_ot</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">500</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tol_sinkhorn</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-07</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">method_sinkhorn</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'sinkhorn'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">early_stopping_tol</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-06</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">log</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbose</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/ot/coot.html#co_optimal_transport"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#id0" title="Link to this definition"></a></dt>
<dd><p>Compute the CO-Optimal Transport between two matrices.</p>
<p>Return the sample and feature transport plans between
<span class="math notranslate nohighlight">\((\mathbf{X}, \mathbf{w}_{xs}, \mathbf{w}_{xf})\)</span> and
<span class="math notranslate nohighlight">\((\mathbf{Y}, \mathbf{w}_{ys}, \mathbf{w}_{yf})\)</span>.</p>
<p>The function solves the following CO-Optimal Transport (COOT) problem:</p>
<div class="math notranslate nohighlight">
\[\begin{split}\mathbf{COOT}_{\alpha, \varepsilon} = \mathop{\arg \min}_{\mathbf{P}, \mathbf{Q}}
&amp;\quad \sum_{i,j,k,l}
(\mathbf{X}_{i,k} - \mathbf{Y}_{j,l})^2 \mathbf{P}_{i,j} \mathbf{Q}_{k,l}
+ \alpha_s \sum_{i,j} \mathbf{P}_{i,j} \mathbf{M^{(s)}}_{i, j} \\
&amp;+ \alpha_f \sum_{k, l} \mathbf{Q}_{k,l} \mathbf{M^{(f)}}_{k, l}
+ \varepsilon_s \mathbf{KL}(\mathbf{P} | \mathbf{w}_{xs} \mathbf{w}_{ys}^T)
+ \varepsilon_f \mathbf{KL}(\mathbf{Q} | \mathbf{w}_{xf} \mathbf{w}_{yf}^T)\end{split}\]</div>
<p>Where :</p>
<ul class="simple">
<li><p><span class="math notranslate nohighlight">\(\mathbf{X}\)</span>: Data matrix in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{Y}\)</span>: Data matrix in the target space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{M^{(s)}}\)</span>: Additional sample matrix</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{M^{(f)}}\)</span>: Additional feature matrix</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{xs}\)</span>: Distribution of the samples in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{xf}\)</span>: Distribution of the features in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{ys}\)</span>: Distribution of the samples in the target space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{yf}\)</span>: Distribution of the features in the target space</p></li>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This function allows epsilon to be zero.
In that case, the <a class="reference internal" href="ot.lp.html#ot.lp.emd" title="ot.lp.emd"><code class="xref any py py-func docutils literal notranslate"><span class="pre">ot.lp.emd</span></code></a> solver of POT will be used.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>X</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>n_feature_x</em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a>) – First input matrix.</p></li>
<li><p><strong>Y</strong> (<em>(</em><em>n_sample_y</em><em>, </em><em>n_feature_y</em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a>) – Second input matrix.</p></li>
<li><p><strong>wx_samp</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on rows (samples) of matrix X.
Uniform distribution by default.</p></li>
<li><p><strong>wx_feat</strong> (<em>(</em><em>n_feature_x</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on columns (features) of matrix X.
Uniform distribution by default.</p></li>
<li><p><strong>wy_samp</strong> (<em>(</em><em>n_sample_y</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on rows (samples) of matrix Y.
Uniform distribution by default.</p></li>
<li><p><strong>wy_feat</strong> (<em>(</em><em>n_feature_y</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on columns (features) of matrix Y.
Uniform distribution by default.</p></li>
<li><p><strong>epsilon</strong> (<em>scalar</em><em> or </em><em>indexable object</em><em> of </em><em>length 2</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 0</em><em>)</em>) – Regularization parameters for entropic approximation of sample and feature couplings.
Allow the case where epsilon contains 0. In that case, the EMD solver is used instead of
Sinkhorn solver. If epsilon is scalar, then the same epsilon is applied to
both regularization of sample and feature couplings.</p></li>
<li><p><strong>alpha</strong> (<em>scalar</em><em> or </em><em>indexable object</em><em> of </em><em>length 2</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 0</em><em>)</em>) – Coefficient parameter of linear terms with respect to the sample and feature couplings.
If alpha is scalar, then the same alpha is applied to both linear terms.</p></li>
<li><p><strong>M_samp</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>n_sample_y</em><em>)</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Sample matrix with respect to the linear term on sample coupling.</p></li>
<li><p><strong>M_feat</strong> (<em>(</em><em>n_feature_x</em><em>, </em><em>n_feature_y</em><em>)</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Feature matrix with respect to the linear term on feature coupling.</p></li>
<li><p><strong>warmstart</strong> (<em>dictionary</em><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – <dl class="simple">
<dt>Contains 4 keys:</dt><dd><ul>
<li><p>”duals_sample” and “duals_feature” whose values are
tuples of 2 vectors of size (n_sample_x, n_sample_y) and (n_feature_x, n_feature_y).
Initialization of sample and feature dual vectors
if using Sinkhorn algorithm. Zero vectors by default.</p></li>
<li><p>”pi_sample” and “pi_feature” whose values are matrices
of size (n_sample_x, n_sample_y) and (n_feature_x, n_feature_y).
Initialization of sample and feature couplings.
Uniform distributions by default.</p></li>
<li><p><strong>nits_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 100</em><em>)</em>) – Number of Block Coordinate Descent (BCD) iterations to solve COOT.</p></li>
<li><p><strong>tol_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-7</em><em>)</em>) – Tolerance of BCD scheme. If the L1-norm between the current and previous
sample couplings is under this threshold, then stop BCD scheme.</p></li>
<li><p><strong>eval_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1</em><em>)</em>) – Multiplier of iteration at which the COOT cost is evaluated. For example,
if <cite>eval_bcd = 8</cite>, then the cost is calculated at iterations 8, 16, 24, etc…</p></li>
<li><p><strong>nits_ot</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 100</em><em>)</em>) – Number of iterations to solve each of the
two optimal transport problems in each BCD iteration.</p></li>
<li><p><strong>tol_sinkhorn</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-7</em><em>)</em>) – Tolerance of Sinkhorn algorithm to stop the Sinkhorn scheme for
entropic optimal transport problem (if any) in each BCD iteration.
Only triggered when Sinkhorn solver is used.</p></li>
<li><p><strong>method_sinkhorn</strong> (<em>string</em><em>, </em><em>optional</em><em> (</em><em>default = &quot;sinkhorn&quot;</em><em>)</em>) – Method used in POT’s <cite>ot.sinkhorn</cite> solver.
Only support “sinkhorn” and “sinkhorn_log”.</p></li>
<li><p><strong>early_stopping_tol</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-6</em><em>)</em>) – Tolerance for the early stopping. If the absolute difference between
the last 2 recorded COOT distances is under this tolerance, then stop BCD scheme.</p></li>
<li><p><strong>log</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><em>bool</em></a><em>, </em><em>optional</em><em> (</em><em>default = False</em><em>)</em>) – If True then the cost and 4 dual vectors, including
2 from sample and 2 from feature couplings, are recorded.</p></li>
<li><p><strong>verbose</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><em>bool</em></a><em>, </em><em>optional</em><em> (</em><em>default = False</em><em>)</em>) – If True then print the COOT cost at every multiplier of <cite>eval_bcd</cite>-th iteration.</p></li>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><ul>
<li><p><strong>pi_samp</strong> (<em>(n_sample_x, n_sample_y) array-like, float</em>) – Sample coupling matrix.</p></li>
<li><p><strong>pi_feat</strong> (<em>(n_feature_x, n_feature_y) array-like, float</em>) – Feature coupling matrix.</p></li>
<li><p><strong>log</strong> (<em>dictionary, optional</em>) –</p>
<dl class="simple">
<dt>Returned if <cite>log</cite> is True. The keys are:</dt><dd><dl class="simple">
<dt>duals_sample<span class="classifier">(n_sample_x, n_sample_y) tuple, float</span></dt><dd><p>Pair of dual vectors when solving OT problem w.r.t the sample coupling.</p>
<dt>duals_feature<span class="classifier">(n_feature_x, n_feature_y) tuple, float</span></dt><dd><p>Pair of dual vectors when solving OT problem w.r.t the feature coupling.</p>
<dt>distances<span class="classifier">list, float</span></dt><dd><p>List of COOT distances along iterations.</p>
<p class="rubric">References</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id3" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>49<span class="fn-bracket">]</span></span>
<p>I. Redko, T. Vayer, R. Flamary, and N. Courty, CO-Optimal Transport,
Advances in Neural Information Processing ny_sampstems, 33 (2020).</p>
<dl class="py function">
<dt class="sig sig-object py" id="id4">
<span class="sig-prename descclassname"><span class="pre">ot.coot.</span></span><span class="sig-name descname"><span class="pre">co_optimal_transport2</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">X</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">Y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wx_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wx_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wy_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wy_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">epsilon</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">alpha</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">M_samp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">M_feat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">warmstart</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">log</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbose</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">early_stopping_tol</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-06</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nits_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">100</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tol_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-07</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">eval_bcd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nits_ot</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">500</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tol_sinkhorn</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-07</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">method_sinkhorn</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'sinkhorn'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/ot/coot.html#co_optimal_transport2"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#id4" title="Link to this definition"></a></dt>
<dd><p>Compute the CO-Optimal Transport distance between two measures.</p>
<p>Returns the CO-Optimal Transport distance between
<span class="math notranslate nohighlight">\((\mathbf{X}, \mathbf{w}_{xs}, \mathbf{w}_{xf})\)</span> and
<span class="math notranslate nohighlight">\((\mathbf{Y}, \mathbf{w}_{ys}, \mathbf{w}_{yf})\)</span>.</p>
<p>The function solves the following CO-Optimal Transport (COOT) problem:</p>
<div class="math notranslate nohighlight">
\[\begin{split}\mathbf{COOT}_{\alpha, \varepsilon} = \mathop{\arg \min}_{\mathbf{P}, \mathbf{Q}}
&amp;\quad \sum_{i,j,k,l}
(\mathbf{X}_{i,k} - \mathbf{Y}_{j,l})^2 \mathbf{P}_{i,j} \mathbf{Q}_{k,l}
+ \alpha_1 \sum_{i,j} \mathbf{P}_{i,j} \mathbf{M^{(s)}}_{i, j} \\
&amp;+ \alpha_2 \sum_{k, l} \mathbf{Q}_{k,l} \mathbf{M^{(f)}}_{k, l}
+ \varepsilon_1 \mathbf{KL}(\mathbf{P} | \mathbf{w}_{xs} \mathbf{w}_{ys}^T)
+ \varepsilon_2 \mathbf{KL}(\mathbf{Q} | \mathbf{w}_{xf} \mathbf{w}_{yf}^T)\end{split}\]</div>
<p>where :</p>
<ul class="simple">
<li><p><span class="math notranslate nohighlight">\(\mathbf{X}\)</span>: Data matrix in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{Y}\)</span>: Data matrix in the target space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{M^{(s)}}\)</span>: Additional sample matrix</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{M^{(f)}}\)</span>: Additional feature matrix</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{xs}\)</span>: Distribution of the samples in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{xf}\)</span>: Distribution of the features in the source space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{ys}\)</span>: Distribution of the samples in the target space</p></li>
<li><p><span class="math notranslate nohighlight">\(\mathbf{w}_{yf}\)</span>: Distribution of the features in the target space</p></li>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This function allows epsilon to be zero.
In that case, the <a class="reference internal" href="ot.lp.html#ot.lp.emd" title="ot.lp.emd"><code class="xref any py py-func docutils literal notranslate"><span class="pre">ot.lp.emd</span></code></a> solver of POT will be used.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>X</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>n_feature_x</em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a>) – First input matrix.</p></li>
<li><p><strong>Y</strong> (<em>(</em><em>n_sample_y</em><em>, </em><em>n_feature_y</em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a>) – Second input matrix.</p></li>
<li><p><strong>wx_samp</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on rows (samples) of matrix X.
Uniform distribution by default.</p></li>
<li><p><strong>wx_feat</strong> (<em>(</em><em>n_feature_x</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on columns (features) of matrix X.
Uniform distribution by default.</p></li>
<li><p><strong>wy_samp</strong> (<em>(</em><em>n_sample_y</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on rows (samples) of matrix Y.
Uniform distribution by default.</p></li>
<li><p><strong>wy_feat</strong> (<em>(</em><em>n_feature_y</em><em>, </em><em>) </em><em>array-like</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Histogram assigned on columns (features) of matrix Y.
Uniform distribution by default.</p></li>
<li><p><strong>epsilon</strong> (<em>scalar</em><em> or </em><em>indexable object</em><em> of </em><em>length 2</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 0</em><em>)</em>) – Regularization parameters for entropic approximation of sample and feature couplings.
Allow the case where epsilon contains 0. In that case, the EMD solver is used instead of
Sinkhorn solver. If epsilon is scalar, then the same epsilon is applied to
both regularization of sample and feature couplings.</p></li>
<li><p><strong>alpha</strong> (<em>scalar</em><em> or </em><em>indexable object</em><em> of </em><em>length 2</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 0</em><em>)</em>) – Coefficient parameter of linear terms with respect to the sample and feature couplings.
If alpha is scalar, then the same alpha is applied to both linear terms.</p></li>
<li><p><strong>M_samp</strong> (<em>(</em><em>n_sample_x</em><em>, </em><em>n_sample_y</em><em>)</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Sample matrix with respect to the linear term on sample coupling.</p></li>
<li><p><strong>M_feat</strong> (<em>(</em><em>n_feature_x</em><em>, </em><em>n_feature_y</em><em>)</em><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – Feature matrix with respect to the linear term on feature coupling.</p></li>
<li><p><strong>warmstart</strong> (<em>dictionary</em><em>, </em><em>optional</em><em> (</em><em>default = None</em><em>)</em>) – <dl>
<dt>Contains 4 keys:</dt><dd><ul>
<li><p>”duals_sample” and “duals_feature” whose values are</p></li>
<p>tuples of 2 vectors of size (n_sample_x, n_sample_y) and (n_feature_x, n_feature_y).
Initialization of sample and feature dual vectors
if using Sinkhorn algorithm. Zero vectors by default.
- “pi_sample” and “pi_feature” whose values are matrices
of size (n_sample_x, n_sample_y) and (n_feature_x, n_feature_y).
Initialization of sample and feature couplings.
Uniform distributions by default.</p>
<li><p><strong>nits_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 100</em><em>)</em>) – Number of Block Coordinate Descent (BCD) iterations to solve COOT.</p></li>
<li><p><strong>tol_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-7</em><em>)</em>) – Tolerance of BCD scheme. If the L1-norm between the current and previous
sample couplings is under this threshold, then stop BCD scheme.</p></li>
<li><p><strong>eval_bcd</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1</em><em>)</em>) – Multiplier of iteration at which the COOT cost is evaluated. For example,
if <cite>eval_bcd = 8</cite>, then the cost is calculated at iterations 8, 16, 24, etc…</p></li>
<li><p><strong>nits_ot</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><em>optional</em><em> (</em><em>default = 100</em><em>)</em>) – Number of iterations to solve each of the
two optimal transport problems in each BCD iteration.</p></li>
<li><p><strong>tol_sinkhorn</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-7</em><em>)</em>) – Tolerance of Sinkhorn algorithm to stop the Sinkhorn scheme for
entropic optimal transport problem (if any) in each BCD iteration.
Only triggered when Sinkhorn solver is used.</p></li>
<li><p><strong>method_sinkhorn</strong> (<em>string</em><em>, </em><em>optional</em><em> (</em><em>default = &quot;sinkhorn&quot;</em><em>)</em>) – Method used in POT’s <cite>ot.sinkhorn</cite> solver.
Only support “sinkhorn” and “sinkhorn_log”.</p></li>
<li><p><strong>early_stopping_tol</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>, </em><em>optional</em><em> (</em><em>default = 1e-6</em><em>)</em>) – Tolerance for the early stopping. If the absolute difference between
the last 2 recorded COOT distances is under this tolerance, then stop BCD scheme.</p></li>
<li><p><strong>log</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><em>bool</em></a><em>, </em><em>optional</em><em> (</em><em>default = False</em><em>)</em>) – If True then the cost and 4 dual vectors, including
2 from sample and 2 from feature couplings, are recorded.</p></li>
<li><p><strong>verbose</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><em>bool</em></a><em>, </em><em>optional</em><em> (</em><em>default = False</em><em>)</em>) – If True then print the COOT cost at every multiplier of <cite>eval_bcd</cite>-th iteration.</p></li>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><ul class="simple">
<li><p><em>float</em> – CO-Optimal Transport distance.</p></li>
<li><p><em>dict</em> – Contains logged information from <a class="reference internal" href="#id0" title="ot.coot.co_optimal_transport"><code class="xref any py py-func docutils literal notranslate"><span class="pre">co_optimal_transport</span></code></a> solver.
Only returned if <cite>log</cite> parameter is True</p></li>
<p class="rubric">References</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id5" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>47<span class="fn-bracket">]</span></span>
<p>I. Redko, T. Vayer, R. Flamary, and N. Courty, CO-Optimal Transport,
Advances in Neural Information Processing ny_sampstems, 33 (2020).</p>
           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="ot.bregman.html" class="btn btn-neutral float-left" title="ot.bregman" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="ot.da.html" class="btn btn-neutral float-right" title="ot.da" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
  <div role="contentinfo">
    <p>&#169; Copyright 2016-2025, POT Contributors.</p>
  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
        </div>
      </div>
    </section>
  <div class="rst-versions" data-toggle="rst-versions" role="note"
aria-label="versions">
  <!--  add shift_up to the class for force viewing ,
  data-toggle="rst-current-version" -->
    <span class="rst-current-version"  style="margin-bottom:1mm;">
      <span class="fa fa-book"> Python Optimal Transport</span> 0.9.6
      <hr  style="margin-bottom:1.5mm;margin-top:5mm;">
     <!--  versions
      <span class="fa fa-caret-down"></span>-->
      <span class="rst-current-version" style="display: inline-block;padding:
      0px;color:#fcfcfcab;float:left;font-size: 100%;">
        Versions: 
        <a href="https://pythonot.github.io/" 
        style="padding: 3px;color:#fcfcfc;font-size: 100%;">Release</a>
        <a href="https://pythonot.github.io/master" 
        style="padding: 3px;color:#fcfcfc;font-size: 100%;">Development</a>
        <a href="https://github.com/PythonOT/POT"
        style="padding: 3px;color:#fcfcfc;font-size: 100%;">Code</a>
      </span>
    </span>
    <div class="rst-other-versions">
<div class="injected">
    <dt>Versions</dt>
    <dd><a href="https://pythonot.github.io/">Release</a></dd>
    <dd><a href="https://pythonot.github.io/master">Development</a></dd>
    <dt><a href="https://github.com/PythonOT/POT">Code on Github</a></dt>       
  </div><script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
  </script> 
Sunbelt Computer Software

PL/B Language Development and Support

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Sunbelt Computer Software

PL/B Language Development and Support

Uh oh!

FilesExpand file tree

ot.coot.html

Latest commit

History

ot.coot.html

File metadata and controls
