Continue revising the package

COMSOC-Community · Apr 24, 2024 · bfbbe3b · bfbbe3b
1 parent 27d5d06
commit bfbbe3b
Show file tree

Hide file tree

Showing 36 changed files with 3,270 additions and 1,472 deletions.
diff --git a/docs-source/make.bat b/docs-source/make.bat
@@ -7,6 +7,7 @@ REM Command file for Sphinx documentation
 REM You can set these variables from the command line, and also
 REM from the environment for the first two.
 SET SPHINXOPTS=
+SET SPHINXBUILD=sphinx-build
 SET SOURCEDIR=source
 SET LOCALBUILDDIR=build
 SET GITHUBBUILDDIR=..\docs

diff --git a/...-source/source/reference/validation_plots/approval/disjoint_resampling_0_25.png b/...-source/source/reference/validation_plots/approval/disjoint_resampling_0_25.png
diff --git a/...-source/source/reference/validation_plots/approval/disjoint_resampling_0_33.png b/...-source/source/reference/validation_plots/approval/disjoint_resampling_0_33.png
diff --git a/docs-source/source/reference/validation_plots/approval/resampling_0_25.png b/docs-source/source/reference/validation_plots/approval/resampling_0_25.png
diff --git a/docs-source/source/reference/validation_plots/approval/resampling_0_5.png b/docs-source/source/reference/validation_plots/approval/resampling_0_5.png
diff --git a/docs-source/source/reference/validation_plots/approval/resampling_0_75.png b/docs-source/source/reference/validation_plots/approval/resampling_0_75.png
diff --git a/docs-source/source/reference/validation_plots/approval/resampling_1_0.png b/docs-source/source/reference/validation_plots/approval/resampling_1_0.png
diff --git a/...source/reference/validation_plots/ordinal/euclidean_line_UNBOUNDED_GAUSSIAN.png b/...source/reference/validation_plots/ordinal/euclidean_line_UNBOUNDED_GAUSSIAN.png
diff --git a/...ource/source/reference/validation_plots/ordinal/euclidean_line_UNIFORM_BALL.png b/...ource/source/reference/validation_plots/ordinal/euclidean_line_UNIFORM_BALL.png
diff --git a/...ource/source/reference/validation_plots/ordinal/euclidean_line_UNIFORM_CUBE.png b/...ource/source/reference/validation_plots/ordinal/euclidean_line_UNIFORM_CUBE.png
diff --git a/...e/source/reference/validation_plots/ordinal/euclidean_uniform_GAUSSIAN_BALL.png b/...e/source/reference/validation_plots/ordinal/euclidean_uniform_GAUSSIAN_BALL.png
diff --git a/...e/source/reference/validation_plots/ordinal/euclidean_uniform_GAUSSIAN_CUBE.png b/...e/source/reference/validation_plots/ordinal/euclidean_uniform_GAUSSIAN_CUBE.png
diff --git a/...rce/reference/validation_plots/ordinal/euclidean_uniform_UNBOUNDED_GAUSSIAN.png b/...rce/reference/validation_plots/ordinal/euclidean_uniform_UNBOUNDED_GAUSSIAN.png
diff --git a/...ce/source/reference/validation_plots/ordinal/euclidean_uniform_UNIFORM_BALL.png b/...ce/source/reference/validation_plots/ordinal/euclidean_uniform_UNIFORM_BALL.png
diff --git a/...ce/source/reference/validation_plots/ordinal/euclidean_uniform_UNIFORM_CUBE.png b/...ce/source/reference/validation_plots/ordinal/euclidean_uniform_UNIFORM_CUBE.png
diff --git a/.../source/reference/validation_plots/ordinal/euclidean_uniform_UNIFORM_SPHERE.png b/.../source/reference/validation_plots/ordinal/euclidean_uniform_UNIFORM_SPHERE.png
diff --git a/prefsampling/approval/impartial.py b/prefsampling/approval/impartial.py
@@ -105,6 +105,18 @@ def impartial(
             except ValueError:
                 pass
 
+    Validation
+    ----------
+
+        We only validate the model with a single voter thus the distinction between individual and global does not
+        matter here. Call :math:`p` the probability of approving any candidate, then the probability of generating a
+        given approval ballot of size :math:`k` is:
+
+        .. math::
+            p^k \\times (1 - p)^{m - k},
+
+        where :math:`m` is the number of candidates.
+
     References
     ----------
 
@@ -250,6 +262,15 @@ def impartial_constant_size(
             except ValueError:
                 pass
 
+    Validation
+    ----------
+
+        We only validate the model with a single voter thus the distinction between individual and global does not
+        matter here. For a given value of :code:`rel_num_approvals`, let
+        :math:`s = \\lfoor \\text{rel\\_num\\_approvals} \\times m \\rfloor` be the size of the approval ballots.
+        Then, the probability of generating a given approval ballot of size :math:`k` is 0 if :math:`k \neq s`,
+        and :math:`\\frac{1}{\\binom{m}{s}}` otherwise, where :math:`m` is the number of candidates.
+
     References
     ----------
 

diff --git a/prefsampling/approval/noise.py b/prefsampling/approval/noise.py
@@ -46,6 +46,11 @@ class SetDistance(Enum):
 
 
 class DistanceInfiniteError(ValueError):
+    """
+    Exception thrown when the distance between two points is infinite., typically when dividing by 0 for the
+    Bunke-Shearer or the Jaccard distances.
+    """
+
     pass
 
 
@@ -94,6 +99,8 @@ def noise(
     A collection of `num_voters` vote is generated independently and identically following the
     process described above.
 
+    For an analogous sampler generating ordinal ballots, see :py:func:`~prefsampling.ordinal.mallows.mallows`.
+
     Parameters
     ----------
         num_voters : int