version to 0.1.8, rebuild docs

Author: akshayka

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 7153fc90f708b5e59666a299be10a5cb
+config: da69227389dc6b0a77a3fbb00fff02eb
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_sources/api/index.rst.txt

@@ -144,7 +144,9 @@ Preprocessing
 Classical embeddings
 --------------------
 
-.. autofunction:: pymde.quadratic.pca
+.. autofunction:: pymde.pca
+
+.. autofunction:: pymde.laplacian_embedding
 
 .. autofunction:: pymde.quadratic.spectral
 

docs/_sources/examples/index.rst.txt

@@ -3,8 +3,8 @@
 Examples
 ========
 
-As with most software, after reading the documentation, the best way
-to learn more is by playing with code.
+After reading the documentation, the best way
+to learn more is by playing with code examples.
 
 Our Python notebooks show how to use PyMDE on real (and synthetic)
 datasets. You can read these notebooks, or better yet, execute them and
@@ -109,8 +109,8 @@ introduces the ``pymde.Graph`` class.
 
 - `Drawing graphs notebook <https://github.com/cvxgrp/pymde/blob/main/examples/drawing_graphs.ipynb>`_
 
-Anchor Constraint
------------------
+Anchor Constraints
+------------------
 With an anchor constraint, you can pin some embedding vectors to values
 that you specify ahead of time. This is useful when you have prior
 knowledge of where some of the items should end up (e.g., you might
@@ -120,4 +120,4 @@ some nodes pinned in place).
 This notebook gives an example of how to use an anchor constraint, using
 graph drawing as an example.
 
-- `Anchor constraints <https://github.com/cvxgrp/pymde/blob/main/examples/anchor_constraints.ipynb>`_
+- `Anchor constraint notebook <https://github.com/cvxgrp/pymde/blob/main/examples/anchor_constraints.ipynb>`_

docs/_sources/getting_started/index.rst.txt

@@ -265,29 +265,29 @@ Classical embeddings
 --------------------
 
 PyMDE provides a few implementations of classical embeddings, for convenience.
-To produce a PCA embedding of a data matrix, call the :any:`pymde.quadratic.pca`
-method:
+To produce a PCA embedding of a data matrix, use the :any:`pymde.pca`
+method, which returns an embedding:
 
 .. code:: python3
 
-   embedding = pymde.quadratic.pca(data_matrix, embedding_dim)
+   embedding = pymde.pca(data_matrix, embedding_dim)
 
-To create a spectral embedding based on a sequence of edges (a ``torch.Tensor``
-of shape ``(n_edges, 2)``) and weights, use :any:`pymde.quadratic.spectral`.
-A Laplacian embedding based on the nearest neighbors of each row in a data
-matrix can be created with
+To create a Laplacian embedding based on the nearest neighbors of each row in a
+data matrix or each node in a graph, use the :any:`pymde.laplacian_embedding`
+method, which returns an MDE problem:
 
 .. code:: python3
 
-   embedding = pymde.preserve_neighbors(data_matrix,
-      attractive_penalty=pymde.penalties.Quadratic,
-      repulsive_penalty=None
-   ).embed()
+   mde = pymde.laplacian_embedding(data, embedding_dim, verbose=True)
+   embedding = mde.embed()
 
+To create a spectral embedding based on a sequence of edges (a ``torch.Tensor``
+of shape ``(n_edges, 2)``) and weights, use :any:`pymde.quadratic.spectral`.
+(These embeddings are called "quadratic embeddings" in the MDE monograph.)
 
 Drawing graphs
 --------------
-Finally, PyMDE can be used to draw graphs in 2 or 3 dimensions.
+PyMDE can be used to draw graphs in 2 or 3 dimensions.
 Here is a very simple example that draws a cycle graph on 3 nodes.
 
 .. code:: python3
@@ -302,7 +302,7 @@ Here is a very simple example that draws a cycle graph on 3 nodes.
 
 .. image:: /files/triangle.png
 
-Here is a more interesting example, in which we embed a ternary tree. The
+Here is a more interesting example, which embeds a ternary tree. The
 tree is created using the `NetworkX <https://networkx.org/>`_ package.
 
 .. code:: python3

docs/_static/css/custom.css

@@ -17,6 +17,11 @@ h1, h2, h3, h4, h5, h6 {
 	font-weight: 400;
 }
 
+h2, h3, h4, h5, h6 {
+  padding-top: 0.25em;
+  margin-bottom: 0.5em;
+}
+
 h1 {
 	font-size: 225%;
 }

docs/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '0.1.7',
+    VERSION: '0.1.8',
     LANGUAGE: 'None',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/api/index.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>API documentation &mdash; pymde 0.1.7 documentation</title>
+  <title>API documentation &mdash; pymde 0.1.8 documentation</title>
 
 
 
@@ -66,7 +66,7 @@
 
 
               <div class="version">
-                v0.1.7
+                v0.1.8
               </div>
 
 
@@ -847,10 +847,9 @@ <h2>MDE<a class="headerlink" href="#mde" title="Permalink to this headline">¶</
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
 <dd class="field-odd"><ul class="simple">
-<li><p><strong>data</strong> (<em>{torch.Tensor</em><em>, </em><em>numpy.ndarray</em><em>, </em><em>scipy.sparse matrix}</em><em>(</em>) – shape=(n_items, n_features)) or pymde.Graph
-The original data, a data matrix or a graph. Neighbors are
-computed using Euclidean distance if the data is a matrix,
-or the shortest-path metric if the data is a graph.</p></li>
+<li><p><strong>data</strong> (<em>{torch.Tensor</em><em>, </em><em>numpy.ndarray</em><em>, </em><em>scipy.sparse matrix}</em><em> or </em><a class="reference internal" href="#pymde.Graph" title="pymde.Graph"><em>pymde.Graph</em></a>) – The original data, a data matrix of shape <code class="docutils literal notranslate"><span class="pre">(n_items,</span> <span class="pre">n_features)</span></code> or
+a graph. Neighbors are computed using Euclidean distance if the data is
+a matrix, or the shortest-path metric if the data is a graph.</p></li>
 <li><p><strong>embedding_dim</strong> (<em>int</em>) – The embedding dimension. Use 2 or 3 for visualization.</p></li>
 <li><p><strong>attractive_penalty</strong> (<em>pymde.Function class</em><em> (or </em><em>factory</em><em>)</em>) – Callable that constructs a distortion function, given positive
 weights. Typically one of the classes from <code class="docutils literal notranslate"><span class="pre">pymde.penalties</span></code>,
@@ -926,8 +925,8 @@ <h2>MDE<a class="headerlink" href="#mde" title="Permalink to this headline">¶</
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
 <dd class="field-odd"><ul class="simple">
-<li><p><strong>data</strong> (<em>{np.ndarray</em><em>, </em><em>torch.Tensor</em><em>, </em><em>scipy.sparse matrix}</em><em>(</em>) – shape=(n_items, n_features)), or pymde.Graph
-A data matrix or a <code class="docutils literal notranslate"><span class="pre">pymde.Graph</span></code> instance.</p></li>
+<li><p><strong>data</strong> (<em>{np.ndarray</em><em>, </em><em>torch.Tensor</em><em>, </em><em>scipy.sparse matrix}</em><em> or </em><a class="reference internal" href="#pymde.Graph" title="pymde.Graph"><em>pymde.Graph</em></a>) – The original data, a data matrix of shape <code class="docutils literal notranslate"><span class="pre">(n_items,</span> <span class="pre">n_features)</span></code> or
+a graph.</p></li>
 <li><p><strong>embedding_dim</strong> (<em>int</em>) – The embedding dimension.</p></li>
 <li><p><strong>loss</strong> (<em>pymde.Function class</em><em> (or </em><em>factory</em><em>)</em>) – Callable that constructs a distortion function, given
 original distances. Typically one of the classes defined in
@@ -1550,8 +1549,8 @@ <h2>Preprocessing<a class="headerlink" href="#preprocessing" title="Permalink to
 <div class="section" id="classical-embeddings">
 <h2>Classical embeddings<a class="headerlink" href="#classical-embeddings" title="Permalink to this headline">¶</a></h2>
 <dl class="py function">
-<dt id="pymde.quadratic.pca">
-<code class="sig-prename descclassname">pymde.quadratic.</code><code class="sig-name descname">pca</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">Y</span></em>, <em class="sig-param"><span class="n">embedding_dim</span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymde.quadratic.pca" title="Permalink to this definition">¶</a></dt>
+<dt id="pymde.pca">
+<code class="sig-prename descclassname">pymde.</code><code class="sig-name descname">pca</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">Y</span></em>, <em class="sig-param"><span class="n">embedding_dim</span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymde.pca" title="Permalink to this definition">¶</a></dt>
 <dd><p>PCA embedding of a data matrix.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
@@ -1570,6 +1569,39 @@ <h2>Classical embeddings<a class="headerlink" href="#classical-embeddings" title
 </dl>
 </dd></dl>
 
+<dl class="py function">
+<dt id="pymde.laplacian_embedding">
+<code class="sig-prename descclassname">pymde.</code><code class="sig-name descname">laplacian_embedding</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">data</span></em>, <em class="sig-param"><span class="n">embedding_dim</span><span class="o">=</span><span class="default_value">2</span></em>, <em class="sig-param"><span class="n">n_neighbors</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">max_distance</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">init</span><span class="o">=</span><span class="default_value">'quadratic'</span></em>, <em class="sig-param"><span class="n">device</span><span class="o">=</span><span class="default_value">'cpu'</span></em>, <em class="sig-param"><span class="n">verbose</span><span class="o">=</span><span class="default_value">False</span></em><span class="sig-paren">)</span> &#x2192; pymde.problem.MDE<a class="headerlink" href="#pymde.laplacian_embedding" title="Permalink to this definition">¶</a></dt>
+<dd><p>Constructs an MDE problem for computing a Laplacian embedding.</p>
+<p>The embedding preserves the nearest neighbors of each item, using
+quadratic distortion functions and a standardization constraint.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>data</strong> (<em>{torch.Tensor</em><em>, </em><em>numpy.ndarray</em><em>, </em><em>scipy.sparse matrix}</em><em> or </em><a class="reference internal" href="#pymde.Graph" title="pymde.Graph"><em>pymde.Graph</em></a>) – The original data, a data matrix of shape <code class="docutils literal notranslate"><span class="pre">(n_items,</span> <span class="pre">n_features)</span></code> or
+a graph. Neighbors are computed using Euclidean distance if the data is
+a matrix, or the shortest-path metric if the data is a graph.</p></li>
+<li><p><strong>embedding_dim</strong> (<em>int</em>) – The embedding dimension. Use 2 or 3 for visualization.</p></li>
+<li><p><strong>n_neighbors</strong> (<em>int</em><em> (</em><em>optional</em><em>)</em>) – The number of nearest neighbors to compute for each row (item) of
+<code class="docutils literal notranslate"><span class="pre">data</span></code>. A sensible value is chosen by default, depending on the
+number of items.</p></li>
+<li><p><strong>max_distance</strong> (<em>float</em><em> (</em><em>optional</em><em>)</em>) – If not None, neighborhoods are restricted to have a radius
+no greater than <code class="docutils literal notranslate"><span class="pre">max_distance</span></code>.</p></li>
+<li><p><strong>init</strong> (<em>str</em>) – Initialization strategy; ‘quadratic’ or ‘random’. If the quadratic
+initialization takes too much time, try a random initialization.</p></li>
+<li><p><strong>device</strong> (<em>str</em><em> (</em><em>optional</em><em>)</em>) – Device for the embedding (eg, ‘cpu’, ‘cuda’).</p></li>
+<li><p><strong>verbose</strong> (<em>bool</em>) – If <code class="docutils literal notranslate"><span class="pre">True</span></code>, print verbose output.</p></li>
+</ul>
+</dd>
+<dt class="field-even">Returns</dt>
+<dd class="field-even"><p>A <code class="docutils literal notranslate"><span class="pre">pymde.MDE</span></code> object, based on the original data.</p>
+</dd>
+<dt class="field-odd">Return type</dt>
+<dd class="field-odd"><p><a class="reference internal" href="#pymde.MDE" title="pymde.MDE">pymde.MDE</a></p>
+</dd>
+</dl>
+</dd></dl>
+
 <dl class="py function">
 <dt id="pymde.quadratic.spectral">
 <code class="sig-prename descclassname">pymde.quadratic.</code><code class="sig-name descname">spectral</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">n_items</span></em>, <em class="sig-param"><span class="n">embedding_dim</span></em>, <em class="sig-param"><span class="n">edges</span></em>, <em class="sig-param"><span class="n">weights</span></em>, <em class="sig-param"><span class="n">cg</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">max_iter</span><span class="o">=</span><span class="default_value">40</span></em>, <em class="sig-param"><span class="n">device</span><span class="o">=</span><span class="default_value">'cpu'</span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymde.quadratic.spectral" title="Permalink to this definition">¶</a></dt>

docs/citing/index.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>Citing &mdash; pymde 0.1.7 documentation</title>
+  <title>Citing &mdash; pymde 0.1.8 documentation</title>
 
 
 
@@ -65,7 +65,7 @@
 
 
               <div class="version">
-                v0.1.7
+                v0.1.8
               </div>
 
 

docs/datasets/index.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>Datasets &mdash; pymde 0.1.7 documentation</title>
+  <title>Datasets &mdash; pymde 0.1.8 documentation</title>
 
 
 
@@ -66,7 +66,7 @@
 
 
               <div class="version">
-                v0.1.7
+                v0.1.8
               </div>
 
 

docs/examples/index.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>Examples &mdash; pymde 0.1.7 documentation</title>
+  <title>Examples &mdash; pymde 0.1.8 documentation</title>
 
 
 
@@ -66,7 +66,7 @@
 
 
               <div class="version">
-                v0.1.7
+                v0.1.8
               </div>
 
 
@@ -107,7 +107,7 @@
 <li class="toctree-l2"><a class="reference internal" href="#us-counties">US Counties</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#dissimilar-edges-and-negative-weights">Dissimilar Edges and Negative Weights</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#drawing-graphs">Drawing Graphs</a></li>
-<li class="toctree-l2"><a class="reference internal" href="#anchor-constraint">Anchor Constraint</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#anchor-constraints">Anchor Constraints</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../api/index.html">API documentation</a></li>
@@ -184,8 +184,8 @@
 
   <div class="section" id="examples">
 <span id="id1"></span><h1>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h1>
-<p>As with most software, after reading the documentation, the best way
-to learn more is by playing with code.</p>
+<p>After reading the documentation, the best way
+to learn more is by playing with code examples.</p>
 <p>Our Python notebooks show how to use PyMDE on real (and synthetic)
 datasets. You can read these notebooks, or better yet, execute them and
 experiment by modifying the cells’ contents and seeing what happens.</p>
@@ -279,8 +279,8 @@ <h2>Dissimilar Edges and Negative Weights<a class="headerlink" href="#dissimilar
 <li><p><a class="reference external" href="https://github.com/cvxgrp/pymde/blob/main/examples/drawing_graphs.ipynb">Drawing graphs notebook</a></p></li>
 </ul>
 </div>
-<div class="section" id="anchor-constraint">
-<h2>Anchor Constraint<a class="headerlink" href="#anchor-constraint" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="anchor-constraints">
+<h2>Anchor Constraints<a class="headerlink" href="#anchor-constraints" title="Permalink to this headline">¶</a></h2>
 <p>With an anchor constraint, you can pin some embedding vectors to values
 that you specify ahead of time. This is useful when you have prior
 knowledge of where some of the items should end up (e.g., you might
@@ -289,7 +289,7 @@ <h2>Anchor Constraint<a class="headerlink" href="#anchor-constraint" title="Perm
 <p>This notebook gives an example of how to use an anchor constraint, using
 graph drawing as an example.</p>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/cvxgrp/pymde/blob/main/examples/anchor_constraints.ipynb">Anchor constraints</a></p></li>
+<li><p><a class="reference external" href="https://github.com/cvxgrp/pymde/blob/main/examples/anchor_constraints.ipynb">Anchor constraint notebook</a></p></li>
 </ul>
 </div>
 </div>

docs/genindex.html

@@ -7,7 +7,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
-  <title>Index &mdash; pymde 0.1.7 documentation</title>
+  <title>Index &mdash; pymde 0.1.8 documentation</title>
 
 
 
@@ -64,7 +64,7 @@
 
 
               <div class="version">
-                v0.1.7
+                v0.1.8
               </div>
 
 
@@ -359,6 +359,8 @@ <h2 id="K">K</h2>
 <h2 id="L">L</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="api/index.html#pymde.laplacian_embedding">laplacian_embedding() (in module pymde)</a>
+</li>
       <li><a href="api/index.html#pymde.penalties.Linear">Linear (class in pymde.penalties)</a>
 </li>
       <li><a href="api/index.html#pymde.penalties.Log">Log (class in pymde.penalties)</a>
@@ -420,7 +422,7 @@ <h2 id="N">N</h2>
 <h2 id="P">P</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="api/index.html#pymde.quadratic.pca">pca() (in module pymde.quadratic)</a>
+      <li><a href="api/index.html#pymde.pca">pca() (in module pymde)</a>
 </li>
       <li><a href="api/index.html#pymde.MDE.play">play() (pymde.MDE method)</a>
 </li>