Docs for composition

COMSOC-Community · Feb 8, 2024 · 1f4970d · 1f4970d
1 parent 29f97b8
commit 1f4970d
Show file tree

Hide file tree

Showing 16 changed files with 683 additions and 66 deletions.
diff --git a/docs-source/source/reference/core/index.rst b/docs-source/source/reference/core/index.rst
@@ -1,6 +1,8 @@
 Core
 ====
 
+.. automodule:: prefsampling.core
+
 .. automodule:: prefsampling.core.composition
     :members:
 

diff --git a/docs-source/source/reference/ordinal/index.rst b/docs-source/source/reference/ordinal/index.rst
@@ -1,6 +1,8 @@
 Ordinal
 =======
 
+.. automodule:: prefsampling.ordinal
+
 .. autofunction:: prefsampling.ordinal.identity
 
 .. autofunction:: prefsampling.ordinal.impartial

diff --git a/docs/_modules/index.html b/docs/_modules/index.html
@@ -265,11 +265,11 @@ <h1>All modules for which code is available</h1>
 <ul><li><a href="prefsampling/approval/euclidean.html">prefsampling.approval.euclidean</a></li>
 <li><a href="prefsampling/approval/identity.html">prefsampling.approval.identity</a></li>
 <li><a href="prefsampling/approval/impartial.html">prefsampling.approval.impartial</a></li>
-<li><a href="prefsampling/approval/mixture.html">prefsampling.approval.mixture</a></li>
 <li><a href="prefsampling/approval/noise.html">prefsampling.approval.noise</a></li>
 <li><a href="prefsampling/approval/partylist.html">prefsampling.approval.partylist</a></li>
 <li><a href="prefsampling/approval/resampling.html">prefsampling.approval.resampling</a></li>
 <li><a href="prefsampling/approval/truncated_urn.html">prefsampling.approval.truncated_urn</a></li>
+<li><a href="prefsampling/core/composition.html">prefsampling.core.composition</a></li>
 <li><a href="prefsampling/core/euclidean.html">prefsampling.core.euclidean</a></li>
 <li><a href="prefsampling/ordinal/didi.html">prefsampling.ordinal.didi</a></li>
 <li><a href="prefsampling/ordinal/euclidean.html">prefsampling.ordinal.euclidean</a></li>

diff --git a/docs/_modules/prefsampling/core/composition.html b/docs/_modules/prefsampling/core/composition.html
diff --git a/docs/_sources/quickstart.rst b/docs/_sources/quickstart.rst
@@ -145,3 +145,52 @@ Approval Samplers
      - | :code:`p`
        | :code:`phi`
      - :code:`noise_type` (defaults to :py:const:`~prefsampling.approval.NoiseType.HAMMING`)
+
+
+Composition of Samplers
+~~~~~~~~~~~~~~~~~~~~~~~
+
+It is often useful to be able to compose samplers, to define mixture for instance. The functions
+:py:func:`~prefsampling.core.mixture` and :py:func:`~prefsampling.core.concatenation` can do that.
+
+The mixture uses different samplers, each being use with a given probability.
+
+.. code-block:: python
+
+    from prefsampling.core import mixture
+    from prefsampling.ordinal import single_peaked_conitzer, single_peaked_walsh, norm_mallows
+
+    # We create a mixture for 100 voters and 10 candidates of the single-peaked samplers using the
+    # Conitzer one with probability 0.6 and the Walsh one with probability 0.4
+    mixture(
+        100,  # num_voters
+        10,  # num_candidates
+        [single_peaked_conitzer, single_peaked_walsh],  # list of samplers
+        [0.6, 0.4],  # weights of the samplers
+        [{}, {}]  # parameters of the samplers
+    )
+
+    # We create a mixture for 100 voters and 10 candidates of different Mallows' models
+    mixture(
+        100,  # num_voters
+        10,  # num_candidates
+        [norm_mallows, norm_mallows, norm_mallows],  # list of samplers
+        [4, 10, 3],  # weights of the samplers
+        [{"norm_phi": 0.4}, {"norm_phi": 0.9}, {"norm_phi": 0.23}]  # parameters of the samplers
+    )
+
+The concatenation simply concatenates the votes returned by different samplers.
+
+.. code-block:: python
+
+    from prefsampling.core import concatenation
+    from prefsampling.ordinal import single_peaked_conitzer, single_peaked_walsh
+
+    # We create a concatenation for 100 voters and 10 candidates. 60 votes are sampled from the
+    # single_peaked_conitzer sampler and 40 votes from the single_peaked_walsh sampler.
+    concatenation(
+        [60, 40],  # num_voters per sampler
+        10,  # num_candidates
+        [single_peaked_conitzer, single_peaked_walsh],  # list of samplers
+        [{}, {}]  # parameters of the samplers
+    )
diff --git a/docs/_sources/reference/core/index.rst b/docs/_sources/reference/core/index.rst
@@ -1,5 +1,10 @@
 Core
 ====
 
+.. automodule:: prefsampling.core
+
+.. automodule:: prefsampling.core.composition
+    :members:
+
 .. automodule:: prefsampling.core.euclidean
     :members:
diff --git a/docs/_sources/reference/ordinal/index.rst b/docs/_sources/reference/ordinal/index.rst
@@ -1,6 +1,8 @@
 Ordinal
 =======
 
+.. automodule:: prefsampling.ordinal
+
 .. autofunction:: prefsampling.ordinal.identity
 
 .. autofunction:: prefsampling.ordinal.impartial

diff --git a/docs/genindex.html b/docs/genindex.html
@@ -316,7 +316,7 @@ <h2 id="C">C</h2>
   <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="reference/tree/index.html#prefsampling.tree.caterpillar_tree">caterpillar_tree() (in module prefsampling.tree)</a>
 </li>
-      <li><a href="reference/approval/index.html#prefsampling.approval.concat">concatenation() (in module prefsampling.approval)</a>
+      <li><a href="reference/core/index.html#prefsampling.core.composition.concatenation">concatenation() (in module prefsampling.core.composition)</a>
 </li>
   </ul></td>
 </tr></table>
@@ -416,15 +416,21 @@ <h2 id="M">M</h2>
   <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="reference/ordinal/index.html#prefsampling.ordinal.mallows">mallows() (in module prefsampling.ordinal)</a>
 </li>
-      <li><a href="reference/approval/index.html#prefsampling.approval.mixture">mixture() (in module prefsampling.approval)</a>
+      <li><a href="reference/core/index.html#prefsampling.core.composition.mixture">mixture() (in module prefsampling.core.composition)</a>
 </li>
       <li>
     module
 
       <ul>
         <li><a href="reference/approval/index.html#module-prefsampling.approval">prefsampling.approval</a>
+</li>
+        <li><a href="reference/core/index.html#module-prefsampling.core">prefsampling.core</a>
+</li>
+        <li><a href="reference/core/index.html#module-prefsampling.core.composition">prefsampling.core.composition</a>
 </li>
         <li><a href="reference/core/index.html#module-prefsampling.core.euclidean">prefsampling.core.euclidean</a>
+</li>
+        <li><a href="reference/ordinal/index.html#module-prefsampling.ordinal">prefsampling.ordinal</a>
 </li>
         <li><a href="reference/tree/index.html#module-prefsampling.tree">prefsampling.tree</a>
 </li>
@@ -460,6 +466,20 @@ <h2 id="P">P</h2>
 
       <ul>
         <li><a href="reference/approval/index.html#module-prefsampling.approval">module</a>
+</li>
+      </ul></li>
+      <li>
+    prefsampling.core
+
+      <ul>
+        <li><a href="reference/core/index.html#module-prefsampling.core">module</a>
+</li>
+      </ul></li>
+      <li>
+    prefsampling.core.composition
+
+      <ul>
+        <li><a href="reference/core/index.html#module-prefsampling.core.composition">module</a>
 </li>
       </ul></li>
   </ul></td>
@@ -469,6 +489,13 @@ <h2 id="P">P</h2>
 
       <ul>
         <li><a href="reference/core/index.html#module-prefsampling.core.euclidean">module</a>
+</li>
+      </ul></li>
+      <li>
+    prefsampling.ordinal
+
+      <ul>
+        <li><a href="reference/ordinal/index.html#module-prefsampling.ordinal">module</a>
 </li>
       </ul></li>
       <li>

diff --git a/docs/objects.inv b/docs/objects.inv
diff --git a/docs/py-modindex.html b/docs/py-modindex.html
@@ -286,11 +286,26 @@ <h1>Python Module Index</h1>
        <td>&#160;&#160;&#160;
        <a href="reference/approval/index.html#module-prefsampling.approval"><code class="xref">prefsampling.approval</code></a></td><td>
        <em></em></td></tr>
+     <tr class="cg-1">
+       <td></td>
+       <td>&#160;&#160;&#160;
+       <a href="reference/core/index.html#module-prefsampling.core"><code class="xref">prefsampling.core</code></a></td><td>
+       <em></em></td></tr>
+     <tr class="cg-1">
+       <td></td>
+       <td>&#160;&#160;&#160;
+       <a href="reference/core/index.html#module-prefsampling.core.composition"><code class="xref">prefsampling.core.composition</code></a></td><td>
+       <em></em></td></tr>
      <tr class="cg-1">
        <td></td>
        <td>&#160;&#160;&#160;
        <a href="reference/core/index.html#module-prefsampling.core.euclidean"><code class="xref">prefsampling.core.euclidean</code></a></td><td>
        <em></em></td></tr>
+     <tr class="cg-1">
+       <td></td>
+       <td>&#160;&#160;&#160;
+       <a href="reference/ordinal/index.html#module-prefsampling.ordinal"><code class="xref">prefsampling.ordinal</code></a></td><td>
+       <em></em></td></tr>
      <tr class="cg-1">
        <td></td>
        <td>&#160;&#160;&#160;

diff --git a/docs/quickstart.html b/docs/quickstart.html
@@ -316,6 +316,7 @@ <h2> Contents </h2>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#samplers">Samplers</a><ul class="nav section-nav flex-column">
 <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#ordinal-samplers">Ordinal Samplers</a></li>
 <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#approval-samplers">Approval Samplers</a></li>
+<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#composition-of-samplers">Composition of Samplers</a></li>
 </ul>
 </li>
 </ul>
@@ -528,6 +529,49 @@ <h3>Approval Samplers<a class="headerlink" href="#approval-samplers" title="Perm
 </tbody>
 </table>
 </section>
+<section id="composition-of-samplers">
+<h3>Composition of Samplers<a class="headerlink" href="#composition-of-samplers" title="Permalink to this heading">#</a></h3>
+<p>It is often useful to be able to compose samplers, to define mixture for instance. The functions
+<code class="xref py py-func docutils literal notranslate"><span class="pre">mixture()</span></code> and <code class="xref py py-func docutils literal notranslate"><span class="pre">concatenation()</span></code> can do that.</p>
+<p>The mixture uses different samplers, each being use with a given probability.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">prefsampling.core</span> <span class="kn">import</span> <span class="n">mixture</span>
+<span class="kn">from</span> <span class="nn">prefsampling.ordinal</span> <span class="kn">import</span> <span class="n">single_peaked_conitzer</span><span class="p">,</span> <span class="n">single_peaked_walsh</span><span class="p">,</span> <span class="n">norm_mallows</span>
+
+<span class="c1"># We create a mixture for 100 voters and 10 candidates of the single-peaked samplers using the</span>
+<span class="c1"># Conitzer one with probability 0.6 and the Walsh one with probability 0.4</span>
+<span class="n">mixture</span><span class="p">(</span>
+    <span class="mi">100</span><span class="p">,</span>  <span class="c1"># num_voters</span>
+    <span class="mi">10</span><span class="p">,</span>  <span class="c1"># num_candidates</span>
+    <span class="p">[</span><span class="n">single_peaked_conitzer</span><span class="p">,</span> <span class="n">single_peaked_walsh</span><span class="p">],</span>  <span class="c1"># list of samplers</span>
+    <span class="p">[</span><span class="mf">0.6</span><span class="p">,</span> <span class="mf">0.4</span><span class="p">],</span>  <span class="c1"># weights of the samplers</span>
+    <span class="p">[{},</span> <span class="p">{}]</span>  <span class="c1"># parameters of the samplers</span>
+<span class="p">)</span>
+
+<span class="c1"># We create a mixture for 100 voters and 10 candidates of different Mallows&#39; models</span>
+<span class="n">mixture</span><span class="p">(</span>
+    <span class="mi">100</span><span class="p">,</span>  <span class="c1"># num_voters</span>
+    <span class="mi">10</span><span class="p">,</span>  <span class="c1"># num_candidates</span>
+    <span class="p">[</span><span class="n">norm_mallows</span><span class="p">,</span> <span class="n">norm_mallows</span><span class="p">,</span> <span class="n">norm_mallows</span><span class="p">],</span>  <span class="c1"># list of samplers</span>
+    <span class="p">[</span><span class="mi">4</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span>  <span class="c1"># weights of the samplers</span>
+    <span class="p">[{</span><span class="s2">&quot;norm_phi&quot;</span><span class="p">:</span> <span class="mf">0.4</span><span class="p">},</span> <span class="p">{</span><span class="s2">&quot;norm_phi&quot;</span><span class="p">:</span> <span class="mf">0.9</span><span class="p">},</span> <span class="p">{</span><span class="s2">&quot;norm_phi&quot;</span><span class="p">:</span> <span class="mf">0.23</span><span class="p">}]</span>  <span class="c1"># parameters of the samplers</span>
+<span class="p">)</span>
+</pre></div>
+</div>
+<p>The concatenation simply concatenates the votes returned by different samplers.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">prefsampling.core</span> <span class="kn">import</span> <span class="n">concatenation</span>
+<span class="kn">from</span> <span class="nn">prefsampling.ordinal</span> <span class="kn">import</span> <span class="n">single_peaked_conitzer</span><span class="p">,</span> <span class="n">single_peaked_walsh</span>
+
+<span class="c1"># We create a concatenation for 100 voters and 10 candidates. 60 votes are sampled from the</span>
+<span class="c1"># single_peaked_conitzer sampler and 40 votes from the single_peaked_walsh sampler.</span>
+<span class="n">concatenation</span><span class="p">(</span>
+    <span class="p">[</span><span class="mi">60</span><span class="p">,</span> <span class="mi">40</span><span class="p">],</span>  <span class="c1"># num_voters per sampler</span>
+    <span class="mi">10</span><span class="p">,</span>  <span class="c1"># num_candidates</span>
+    <span class="p">[</span><span class="n">single_peaked_conitzer</span><span class="p">,</span> <span class="n">single_peaked_walsh</span><span class="p">],</span>  <span class="c1"># list of samplers</span>
+    <span class="p">[{},</span> <span class="p">{}]</span>  <span class="c1"># parameters of the samplers</span>
+<span class="p">)</span>
+</pre></div>
+</div>
+</section>
 </section>
 </section>
 
@@ -581,6 +625,7 @@ <h3>Approval Samplers<a class="headerlink" href="#approval-samplers" title="Perm
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#samplers">Samplers</a><ul class="nav section-nav flex-column">
 <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#ordinal-samplers">Ordinal Samplers</a></li>
 <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#approval-samplers">Approval Samplers</a></li>
+<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#composition-of-samplers">Composition of Samplers</a></li>
 </ul>
 </li>
 </ul>