Urn samplers for approval ballots

docs-source/source/quickstart.rst

@@ -121,11 +121,19 @@ Reference: :py:mod:`prefsampling.approval`
      - ---
      - ---
    * - :py:func:`~prefsampling.approval.impartial`
-     - :code:`rel_num_approvals`
+     - :code:`p`
      - ---
    * - :py:func:`~prefsampling.approval.impartial_constant_size`
      - :code:`rel_num_approvals`
      - ---
+   * - :py:func:`~prefsampling.approval.urn`
+     - | :code:`p`
+       | :code:`alpha`
+     - ---
+   * - :py:func:`~prefsampling.approval.urn_constant_size`
+     - | :code:`rel_num_approvals`
+       | :code:`alpha`
+     - ---
    * - :py:func:`~prefsampling.approval.resampling`
      - | :code:`p`
        | :code:`phi`

docs-source/source/reference/approval/index.rst

@@ -2,4 +2,31 @@ Approval
 ========
 
 .. automodule:: prefsampling.approval
-    :members:
+
+.. automodule:: prefsampling.approval.identity
+
+.. automodule:: prefsampling.approval.empty
+
+.. automodule:: prefsampling.approval.full
+
+.. automodule:: prefsampling.approval.impartial
+
+.. automodule:: prefsampling.approval.impartial_constant_size
+
+.. automodule:: prefsampling.approval.urn
+
+.. automodule:: prefsampling.approval.urn_constant_size
+
+.. automodule:: prefsampling.approval.urn_partylist
+
+.. automodule:: prefsampling.approval.resampling
+
+.. automodule:: prefsampling.approval.disjoint_resampling
+
+.. automodule:: prefsampling.approval.moving_resampling
+
+.. automodule:: prefsampling.approval.euclidean
+
+.. automodule:: prefsampling.approval.noise
+
+.. automodule:: prefsampling.approval.truncated_ordinal

docs/_modules/index.html

@@ -282,14 +282,7 @@ <h1></h1>
 
   <h1>All modules for which code is available</h1>
 <ul><li><a href="prefsampling.html">prefsampling</a></li>
-<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/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_ordinal.html">prefsampling.approval.truncated_ordinal</a></li>
-<li><a href="prefsampling/core/composition.html">prefsampling.core.composition</a></li>
+<ul><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/core/filters.html">prefsampling.core.filters</a></li>
 <li><a href="prefsampling/inputvalidators.html">prefsampling.inputvalidators</a></li>

docs/_modules/prefsampling/ordinal/urn.html

@@ -35,7 +35,7 @@
 <link rel="preload" as="script" href="../../../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae" />
   <script src="../../../_static/vendor/fontawesome/6.5.1/js/all.min.js?digest=8d27b9dea8ad943066ae"></script>
 
-    <script src="../../../_static/documentation_options.js?v=e645c8fa"></script>
+    <script src="../../../_static/documentation_options.js?v=7ed07c24"></script>
     <script src="../../../_static/doctools.js?v=888ff710"></script>
     <script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../../_static/scripts/sphinx-book-theme.js?v=efea14e4"></script>
@@ -159,6 +159,8 @@
 <li class="toctree-l2"><a class="reference internal" href="../../../reference/approval/index.html">Approval</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../../reference/tree/index.html">Tree</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../../reference/core/index.html">Core</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../../reference/constants.html">Constants</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../../reference/inputvalidators.html">Input Validators</a></li>
 </ul>
 </li>
 </ul>
@@ -285,7 +287,7 @@ <h1>Source code for prefsampling.ordinal.urn</h1><div class="highlight"><pre>
 
 <span class="kn">from</span> <span class="nn">prefsampling.inputvalidators</span> <span class="kn">import</span> <span class="n">validate_num_voters_candidates</span>
 
-<span class="kn">from</span> <span class="nn">prefsampling.core.urn</span> <span class="kn">import</span> <span class="n">urn_votes</span>
+<span class="kn">from</span> <span class="nn">prefsampling.core.urn</span> <span class="kn">import</span> <span class="n">urn_scheme</span>
 
 
 <div class="viewcode-block" id="urn">
@@ -323,7 +325,13 @@ <h1>Source code for prefsampling.ordinal.urn</h1><div class="highlight"><pre>
 <span class="sd">    &quot;&quot;&quot;</span>
     <span class="n">rng</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">default_rng</span><span class="p">(</span><span class="n">seed</span><span class="p">)</span>
 
-    <span class="k">return</span> <span class="n">urn_votes</span><span class="p">(</span><span class="n">num_voters</span><span class="p">,</span> <span class="n">num_candidates</span><span class="p">,</span> <span class="n">alpha</span><span class="p">,</span> <span class="n">rng</span><span class="p">)</span></div>
+    <span class="n">votes</span> <span class="o">=</span> <span class="n">urn_scheme</span><span class="p">(</span>
+        <span class="n">num_voters</span><span class="p">,</span>
+        <span class="n">alpha</span><span class="p">,</span>
+        <span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span><span class="o">.</span><span class="n">permutation</span><span class="p">(</span><span class="n">num_candidates</span><span class="p">),</span>
+        <span class="n">rng</span>
+    <span class="p">)</span>
+    <span class="k">return</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">votes</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span></div>
 
 </pre></div>
 

docs/_sources/index.rst

@@ -9,7 +9,7 @@ defined statistical cultures. We consider different type of preferences:
 * Approval: preferences are expressed by indicating a set of approved candidates.
 
 This package is part of the
-`Guide to Numerical Experiments on Elections in Computational Social Choice <https://arxiv.org/abs/2402.11765>`_
+`Guide to Numerical Experiments on Elections in Computational Social Choice <https://arxiv.org/abs/2402.11765>`_.
 If you are using it, we kindly ask you to cite the following reference to credit our work.
 
 

docs/_sources/quickstart.rst

@@ -121,11 +121,19 @@ Reference: :py:mod:`prefsampling.approval`
      - ---
      - ---
    * - :py:func:`~prefsampling.approval.impartial`
-     - :code:`rel_num_approvals`
+     - :code:`p`
      - ---
    * - :py:func:`~prefsampling.approval.impartial_constant_size`
      - :code:`rel_num_approvals`
      - ---
+   * - :py:func:`~prefsampling.approval.urn`
+     - | :code:`p`
+       | :code:`alpha`
+     - ---
+   * - :py:func:`~prefsampling.approval.urn_constant_size`
+     - | :code:`rel_num_approvals`
+       | :code:`alpha`
+     - ---
    * - :py:func:`~prefsampling.approval.resampling`
      - | :code:`p`
        | :code:`phi`

docs/_sources/reference/approval/index.rst

@@ -2,4 +2,31 @@ Approval
 ========
 
 .. automodule:: prefsampling.approval
-    :members:
+
+.. automodule:: prefsampling.approval.identity
+
+.. automodule:: prefsampling.approval.empty
+
+.. automodule:: prefsampling.approval.full
+
+.. automodule:: prefsampling.approval.impartial
+
+.. automodule:: prefsampling.approval.impartial_constant_size
+
+.. automodule:: prefsampling.approval.urn
+
+.. automodule:: prefsampling.approval.urn_constant_size
+
+.. automodule:: prefsampling.approval.urn_partylist
+
+.. automodule:: prefsampling.approval.resampling
+
+.. automodule:: prefsampling.approval.disjoint_resampling
+
+.. automodule:: prefsampling.approval.moving_resampling
+
+.. automodule:: prefsampling.approval.euclidean
+
+.. automodule:: prefsampling.approval.noise
+
+.. automodule:: prefsampling.approval.truncated_ordinal