Few things

Author: Simon-Rey

docs-source/source/quickstart.rst

@@ -138,9 +138,9 @@ Approval Samplers
      - :code:`num_legs` (defaults to 1)
    * - :py:func:`~prefsampling.approval.euclidean`
      - ---
-     - | :code:`space` (defaults to :py:const:`~prefsampling.core.euclidean.EuclideanSpace.UNIFORM`)
+     - | :code:`radius` (defaults to 0.5)
+       | :code:`space` (defaults to :py:const:`~prefsampling.core.euclidean.EuclideanSpace.UNIFORM`)
        | :code:`dimension` (defaults to 2)
-       | :code:`radius` (defaults to 0.5)
    * - :py:func:`~prefsampling.approval.noise`
      - | :code:`p`
        | :code:`phi`

docs/_modules/prefsampling/approval/euclidean.html

@@ -272,29 +272,40 @@ <h1>Source code for prefsampling.approval.euclidean</h1><div class="highlight"><
 <span class="k">def</span> <span class="nf">euclidean</span><span class="p">(</span>
     <span class="n">num_voters</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
     <span class="n">num_candidates</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
+    <span class="n">radius</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.5</span><span class="p">,</span>
     <span class="n">space</span><span class="p">:</span> <span class="n">EuclideanSpace</span> <span class="o">=</span> <span class="n">EuclideanSpace</span><span class="o">.</span><span class="n">UNIFORM</span><span class="p">,</span>
     <span class="n">dimension</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
-    <span class="n">radius</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.5</span><span class="p">,</span>
     <span class="n">seed</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
 <span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">set</span><span class="p">[</span><span class="nb">int</span><span class="p">]]:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Generates approval votes from Euclidean model.</span>
+<span class="sd">    Generates approval votes according to the Euclidean model.</span>
+
+<span class="sd">    In the Euclidean model voters and candidates are assigned random positions in a Euclidean space.</span>
+<span class="sd">    A voter then approves of the candidates that are within a certain radius. In other words, a</span>
+<span class="sd">    voter approves of all the candidates that are with distance :code:`radius` of their position.</span>
+
+<span class="sd">    Several Euclidean spaces can be considered. The possibilities are defined in the</span>
+<span class="sd">    :py:class:`~prefsampling.core.euclidean.EuclideanSpace` enumeration. You can also change the</span>
+<span class="sd">    dimension with the parameter :code:`dimension`.</span>
+
+<span class="sd">    A collection of `num_voters` vote is generated independently and identically following the</span>
+<span class="sd">    process described above.</span>
 
 <span class="sd">    Parameters</span>
 <span class="sd">    ----------</span>
-<span class="sd">    num_voters : int</span>
-<span class="sd">        Number of Voters.</span>
-<span class="sd">    num_candidates : int</span>
-<span class="sd">        Number of Candidates.</span>
-<span class="sd">    space : EuclideanSpace, default: :py:const:`~prefsampling.core.euclidean.EuclideanSpace.UNIFORM`</span>
-<span class="sd">        Type of space considered. Should be a constant defined in the</span>
-<span class="sd">        :py:class:`~prefsampling.core.euclidean.EuclideanSpace`.</span>
-<span class="sd">    dimension : int, default: 2</span>
-<span class="sd">        Number of Dimensions.</span>
-<span class="sd">    radius : float, default: 0.5</span>
-<span class="sd">        The radius.</span>
-<span class="sd">    seed : int</span>
-<span class="sd">        Seed for numpy random number generator.</span>
+<span class="sd">        num_voters : int</span>
+<span class="sd">            Number of Voters.</span>
+<span class="sd">        num_candidates : int</span>
+<span class="sd">            Number of Candidates.</span>
+<span class="sd">        radius : float, default: 0.5</span>
+<span class="sd">            Radius of approval.</span>
+<span class="sd">        space : EuclideanSpace, default: :py:const:`~prefsampling.core.euclidean.EuclideanSpace.UNIFORM`</span>
+<span class="sd">            Type of space considered. Should be a constant defined in the</span>
+<span class="sd">            :py:class:`~prefsampling.core.euclidean.EuclideanSpace`.</span>
+<span class="sd">        dimension : int, default: 2</span>
+<span class="sd">            Number of Dimensions.</span>
+<span class="sd">        seed : int</span>
+<span class="sd">            Seed for numpy random number generator.</span>
 
 <span class="sd">    Returns</span>
 <span class="sd">    -------</span>

docs/_modules/prefsampling/approval/identity.html

@@ -270,7 +270,8 @@ <h1>Source code for prefsampling.approval.identity</h1><div class="highlight"><p
     <span class="n">num_voters</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">num_candidates</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">p</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span> <span class="n">seed</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="kc">None</span>
 <span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">set</span><span class="p">[</span><span class="nb">int</span><span class="p">]]:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Generates approval votes from identity culture.</span>
+<span class="sd">    Generates approval votes from the identity culture. These votes are simples: all voters</span>
+<span class="sd">    approves of the candidates `0, 1, 2, ...,  ⌊p * num_candidates⌋` and only these ones.</span>
 
 <span class="sd">    Parameters</span>
 <span class="sd">    ----------</span>
@@ -279,7 +280,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">        p : float</span>
-<span class="sd">            Resampling model parameter, denoting the average vote length.</span>
+<span class="sd">            Proportion of candidates approved.</span>
 <span class="sd">        seed : int</span>
 <span class="sd">            Seed for numpy random number generator.</span>
 
@@ -304,7 +305,7 @@ <h1>Source code for prefsampling.approval.identity</h1><div class="highlight"><p
 <div class="viewcode-block" id="full"><a class="viewcode-back" href="../../../reference/approval/index.html#prefsampling.approval.full">[docs]</a><span class="nd">@validate_num_voters_candidates</span>
 <span class="k">def</span> <span class="nf">full</span><span class="p">(</span><span class="n">num_voters</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">num_candidates</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">seed</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">set</span><span class="p">[</span><span class="nb">int</span><span class="p">]]:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Generates approval votes where each voter approves all the candidates.</span>
+<span class="sd">    Generates approval votes where all voters approve of all the candidates.</span>
 
 <span class="sd">    Parameters</span>
 <span class="sd">    ----------</span>

docs/_modules/prefsampling/approval/impartial.html

@@ -274,14 +274,18 @@ <h1>Source code for prefsampling.approval.impartial</h1><div class="highlight"><
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Generates approval votes from impartial culture.</span>
 
+<span class="sd">    Under the approval culture, when generating a single vote, each candidate has the same</span>
+<span class="sd">    probability :code:`p` of being approved. This models ensures that the average number of</span>
+<span class="sd">    approved candidate per voter is `p * num_candidate`.</span>
+
 <span class="sd">    Parameters</span>
 <span class="sd">    ----------</span>
 <span class="sd">        num_voters : int</span>
 <span class="sd">            Number of Voters.</span>
 <span class="sd">        num_candidates : int</span>
 <span class="sd">            Number of Candidates.</span>
 <span class="sd">        p : float</span>
-<span class="sd">            Resampling model parameter, denoting the average vote length.</span>
+<span class="sd">            Probability of approving of any given candidates.</span>
 <span class="sd">        seed : int</span>
 <span class="sd">            Seed for numpy random number generator.</span>
 

docs/_modules/prefsampling/approval/noise.html

@@ -306,7 +306,7 @@ <h1>Source code for prefsampling.approval.noise</h1><div class="highlight"><pre>
     <span class="n">seed</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
 <span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">set</span><span class="p">]:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Generates approval votes from noise model.</span>
+<span class="sd">    Generates approval votes under the noise model.</span>
 
 <span class="sd">    Parameters</span>
 <span class="sd">    ----------</span>

docs/_modules/prefsampling/approval/truncated_urn.html

@@ -271,11 +271,7 @@ <h1>Source code for prefsampling.approval.truncated_urn</h1><div class="highligh
 
 <div class="viewcode-block" id="truncated_urn"><a class="viewcode-back" href="../../../reference/approval/index.html#prefsampling.approval.truncated_urn">[docs]</a><span class="nd">@validate_num_voters_candidates</span>
 <span class="k">def</span> <span class="nf">truncated_urn</span><span class="p">(</span>
-    <span class="n">num_voters</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
-    <span class="n">num_candidates</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
-    <span class="n">alpha</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span>
-    <span class="n">p</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span>
-    <span class="n">seed</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">num_voters</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">num_candidates</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">alpha</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span> <span class="n">p</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span> <span class="n">seed</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="kc">None</span>
 <span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">set</span><span class="p">[</span><span class="nb">int</span><span class="p">]]:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Generates approval votes from a truncated variant of Polya-Eggenberger urn culture.</span>

docs/_sources/quickstart.rst

@@ -138,9 +138,9 @@ Approval Samplers
      - :code:`num_legs` (defaults to 1)
    * - :py:func:`~prefsampling.approval.euclidean`
      - ---
-     - | :code:`space` (defaults to :py:const:`~prefsampling.core.euclidean.EuclideanSpace.UNIFORM`)
+     - | :code:`radius` (defaults to 0.5)
+       | :code:`space` (defaults to :py:const:`~prefsampling.core.euclidean.EuclideanSpace.UNIFORM`)
        | :code:`dimension` (defaults to 2)
-       | :code:`radius` (defaults to 0.5)
    * - :py:func:`~prefsampling.approval.noise`
      - | :code:`p`
        | :code:`phi`

docs/quickstart.html

@@ -511,9 +511,9 @@ <h3>Approval Samplers<a class="headerlink" href="#approval-samplers" title="Perm
 <tr class="row-odd"><td><p><a class="reference internal" href="reference/approval/index.html#prefsampling.approval.euclidean" title="prefsampling.approval.euclidean"><code class="xref py py-func docutils literal notranslate"><span class="pre">euclidean()</span></code></a></p></td>
 <td><p>—</p></td>
 <td><div class="line-block">
+<div class="line"><code class="code docutils literal notranslate"><span class="pre">radius</span></code> (defaults to 0.5)</div>
 <div class="line"><code class="code docutils literal notranslate"><span class="pre">space</span></code> (defaults to <a class="reference internal" href="reference/core/index.html#prefsampling.core.euclidean.EuclideanSpace.UNIFORM" title="prefsampling.core.euclidean.EuclideanSpace.UNIFORM"><code class="xref py py-const docutils literal notranslate"><span class="pre">UNIFORM</span></code></a>)</div>
 <div class="line"><code class="code docutils literal notranslate"><span class="pre">dimension</span></code> (defaults to 2)</div>
-<div class="line"><code class="code docutils literal notranslate"><span class="pre">radius</span></code> (defaults to 0.5)</div>
 </div>
 </td>
 </tr>