Urn samplers for approval ballots

COMSOC-Community · Mar 7, 2024 · 0be75ec · 0be75ec
1 parent 749bc52
commit 0be75ec
Show file tree

Hide file tree

Showing 15 changed files with 1,099 additions and 521 deletions.
diff --git a/docs-source/source/reference/approval/index.rst b/docs-source/source/reference/approval/index.rst
@@ -3,30 +3,30 @@ Approval
 
 .. automodule:: prefsampling.approval
 
-.. automodule:: prefsampling.approval.identity
+.. autofunction:: prefsampling.approval.identity
 
-.. automodule:: prefsampling.approval.empty
+.. autofunction:: prefsampling.approval.empty
 
-.. automodule:: prefsampling.approval.full
+.. autofunction:: prefsampling.approval.full
 
-.. automodule:: prefsampling.approval.impartial
+.. autofunction:: prefsampling.approval.impartial
 
-.. automodule:: prefsampling.approval.impartial_constant_size
+.. autofunction:: prefsampling.approval.impartial_constant_size
 
-.. automodule:: prefsampling.approval.urn
+.. autofunction:: prefsampling.approval.urn
 
-.. automodule:: prefsampling.approval.urn_constant_size
+.. autofunction:: prefsampling.approval.urn_constant_size
 
-.. automodule:: prefsampling.approval.urn_partylist
+.. autofunction:: prefsampling.approval.urn_partylist
 
-.. automodule:: prefsampling.approval.resampling
+.. autofunction:: prefsampling.approval.resampling
 
-.. automodule:: prefsampling.approval.disjoint_resampling
+.. autofunction:: prefsampling.approval.disjoint_resampling
 
-.. automodule:: prefsampling.approval.moving_resampling
+.. autofunction:: prefsampling.approval.moving_resampling
 
-.. automodule:: prefsampling.approval.euclidean
+.. autofunction:: prefsampling.approval.euclidean
 
-.. automodule:: prefsampling.approval.noise
+.. autofunction:: prefsampling.approval.noise
 
-.. automodule:: prefsampling.approval.truncated_ordinal
+.. autofunction:: prefsampling.approval.truncated_ordinal
diff --git a/docs/_modules/index.html b/docs/_modules/index.html
@@ -282,7 +282,14 @@ <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/core/composition.html">prefsampling.core.composition</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/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/approval/urn.html">prefsampling.approval.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/core/filters.html">prefsampling.core.filters</a></li>
 <li><a href="prefsampling/inputvalidators.html">prefsampling.inputvalidators</a></li>

diff --git a/docs/_modules/prefsampling/approval/identity.html b/docs/_modules/prefsampling/approval/identity.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>
@@ -302,7 +304,7 @@ <h1>Source code for prefsampling.approval.identity</h1><div class="highlight"><p
 <span class="sd">        num_candidates : int</span>
 <span class="sd">            Number of Candidates.</span>
 <span class="sd">        rel_num_approvals : float</span>
-<span class="sd">            Proportion of candidates approved.</span>
+<span class="sd">            Proportion of approved candidates in a ballot.</span>
 <span class="sd">        seed : int</span>
 <span class="sd">            Seed for numpy random number generator.</span>
 
@@ -318,7 +320,8 @@ <h1>Source code for prefsampling.approval.identity</h1><div class="highlight"><p
 <span class="sd">    &quot;&quot;&quot;</span>
 
     <span class="k">if</span> <span class="n">rel_num_approvals</span> <span class="o">&lt;</span> <span class="mi">0</span> <span class="ow">or</span> <span class="mi">1</span> <span class="o">&lt;</span> <span class="n">rel_num_approvals</span><span class="p">:</span>
-        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Incorrect value of p: </span><span class="si">{</span><span class="n">rel_num_approvals</span><span class="si">}</span><span class="s2">. Value should be in [0, 1]&quot;</span><span class="p">)</span>
+        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Incorrect value of rel_num_approvals: </span><span class="si">{</span><span class="n">rel_num_approvals</span><span class="si">}</span><span class="s2">. Value should &quot;</span>
+                         <span class="sa">f</span><span class="s2">&quot;be in [0, 1]&quot;</span><span class="p">)</span>
 
     <span class="n">k</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">rel_num_approvals</span> <span class="o">*</span> <span class="n">num_candidates</span><span class="p">)</span>
     <span class="k">return</span> <span class="p">[</span><span class="nb">set</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">k</span><span class="p">))</span> <span class="k">for</span> <span class="n">_</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">num_voters</span><span class="p">)]</span></div>

diff --git a/docs/_modules/prefsampling/approval/impartial.html b/docs/_modules/prefsampling/approval/impartial.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>
@@ -283,7 +285,7 @@ <h1>Source code for prefsampling.approval.impartial</h1><div class="highlight"><
 
 <span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
 
-<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="p">,</span> <span class="n">validate_int</span>
+<span class="kn">from</span> <span class="nn">prefsampling.inputvalidators</span> <span class="kn">import</span> <span class="n">validate_num_voters_candidates</span>
 
 
 <div class="viewcode-block" id="impartial">
@@ -360,7 +362,7 @@ <h1>Source code for prefsampling.approval.impartial</h1><div class="highlight"><
 <span class="sd">        num_candidates : int</span>
 <span class="sd">            Number of Candidates.</span>
 <span class="sd">        rel_num_approvals : float</span>
-<span class="sd">            Number of approvals per ballot, i.e., size of the approval ballot.</span>
+<span class="sd">            Proportion of approved candidates in a ballot.</span>
 <span class="sd">        seed : int</span>
 <span class="sd">            Seed for numpy random number generator.</span>
 
@@ -376,7 +378,8 @@ <h1>Source code for prefsampling.approval.impartial</h1><div class="highlight"><
 <span class="sd">    &quot;&quot;&quot;</span>
 
     <span class="k">if</span> <span class="n">rel_num_approvals</span> <span class="o">&lt;</span> <span class="mi">0</span> <span class="ow">or</span> <span class="mi">1</span> <span class="o">&lt;</span> <span class="n">rel_num_approvals</span><span class="p">:</span>
-        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Incorrect value of p: </span><span class="si">{</span><span class="n">rel_num_approvals</span><span class="si">}</span><span class="s2">. Value should be in [0,1]&quot;</span><span class="p">)</span>
+        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Incorrect value of rel_num_approvals: </span><span class="si">{</span><span class="n">rel_num_approvals</span><span class="si">}</span><span class="s2">. Value should&quot;</span>
+                         <span class="sa">f</span><span class="s2">&quot; be in [0,1]&quot;</span><span class="p">)</span>
 
     <span class="n">num_approvals</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">rel_num_approvals</span> <span class="o">*</span> <span class="n">num_candidates</span><span class="p">)</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>