Continue updating the docs

Author: Simon-Rey

prefsampling/approval/identity.py

@@ -28,10 +28,20 @@ def identity(
         list[set[int]]
             Approval votes.
 
-    Raises
-    ------
-        ValueError
-            When `rel_num_approvals` is not in the [0, 1] interval.
+    Examples
+    --------
+
+        .. testcode::
+
+            from prefsampling.approval import identity
+
+            # Sample a unanimous profile with 2 voters and 3 candidates.
+            # Voters approve 60% of the candidates (1 in this case).
+            identity(2, 3, 0.6)
+
+            # The seed will not change anything here, but you can still set it.
+            identity(2, 3, seed=1002)
+
     """
 
     if rel_num_approvals < 0 or 1 < rel_num_approvals:

prefsampling/approval/impartial.py

@@ -19,6 +19,9 @@ def impartial(
     A collection of `num_voters` vote is generated independently and identically following the
     process described above.
 
+    See :py:func:`prefsampling.approval.impartial.impartial_constant_size` for a version in which
+    all voters approve of the same number of candidates.
+
     Parameters
     ----------
         num_voters : int
@@ -35,10 +38,19 @@ def impartial(
         list[set]
             Approval votes.
 
-    Raises
-    ------
-        ValueError
-            When `p` not in [0,1] interval.
+    Examples
+    --------
+
+        .. testcode::
+
+            from prefsampling.approval import impartial
+
+            # Sample from an impartial culture with 2 voters and 3 candidates where
+            # a candidate is approved with 60% probability.
+            impartial(2, 3, 0.6)
+
+            # For reproducibility, you can set the seed.
+            impartial(2, 3, 0.6, seed=1002)
     """
 
     if p < 0 or 1 < p:
@@ -67,6 +79,9 @@ def impartial_constant_size(
     A collection of `num_voters` vote is generated independently and identically following the
     process described above.
 
+    See :py:func:`prefsampling.approval.impartial.impartial` for a version in the probability of
+    approving any candidate is constant and independent.
+
     Parameters
     ----------
         num_voters : int
@@ -83,10 +98,19 @@ def impartial_constant_size(
         list[set]
             Approval votes.
 
-    Raises
-    ------
-        ValueError
-            When `rel_num_approvals` is not in [0, 1] interval.
+    Examples
+    --------
+
+        .. testcode::
+
+            from prefsampling.approval import impartial_constant_size
+
+            # Sample from an impartial culture with 2 voters and 3 candidates where
+            # all voters approve of 60% of the candidates (in this case 1).
+            impartial_constant_size(2, 3, 0.6)
+
+            # For reproducibility, you can set the seed.
+            impartial_constant_size(2, 3, 0.6, seed=1002)
     """
 
     if rel_num_approvals < 0 or 1 < rel_num_approvals:

prefsampling/approval/urn.py

@@ -11,7 +11,6 @@ def urn(
     num_voters: int, num_candidates: int, p: float, alpha: float, seed: int = None
 ) -> list[set]:
     """
-
     Generates votes following the Pólya-Eggenberger urn culture. The process is as follows. The urn
     is initially empty and votes are generated one after the other, in turns. When generating a
     vote, the following happens. With a probability of 1/(urn_size + 1),an approval ballots in

prefsampling/core/composition.py

@@ -44,6 +44,45 @@ def mixture(
             Note that this is only the seed for this function.
             If you want to use particular seed for the functions generating votes,
             you should pass it as parameter within the :code:`sampler_parameters` list.
+
+    Examples
+    --------
+
+        .. testcode::
+
+            from prefsampling.core import mixture
+            from prefsampling.ordinal import mallows
+
+            # A mixture of two Mallows' models with different phi and central votes.
+            # The first model has weight 0.7 and the second 0.3.
+            # There are 10 voters and 5 candidates.
+
+            mixture(
+                10,
+                5,
+                [mallows, mallows],
+                [0.7, 0.3],
+                [
+                    {'phi': 0.2, 'central_vote': range(5)},
+                    {'phi': 0.9, 'central_vote': [4, 3, 2, 1, 0]}
+                ],
+            )
+
+            # The weights are re-normalised if they don't add up to one.
+            # The real weights here would be 3/4, 1/4.
+
+            from prefsampling.approval import noise, identity
+
+            mixture(
+                10,
+                5,
+                [noise, identity],
+                [0.3, 0.1],
+                [
+                    {'p': 0.2, 'phi': 0.4},
+                    {'rel_num_approvals': 0.6}
+                ],
+            )
     """
     if len(samplers) != len(weights):
         raise ValueError(
@@ -103,10 +142,28 @@ def concatenation(
             List of dictionaries passed as keyword parameters of the samplers. Number of voters and
             number of candidates of these dictionaries are not taken into account.
 
-    Returns
-    -------
-        np.ndarray
-            Ordinal votes.
+    Examples
+    --------
+
+        .. testcode::
+
+            from prefsampling.core import concatenation
+            from prefsampling.ordinal import mallows
+
+            # A concatenation of two Mallows' models with different phi and central votes.
+            # 4 votes are sampled from the first model and 6 votes from the second.
+            # There are 5 candidates
+
+            mixture(
+                [4, 6],
+                5,
+                [mallows, mallows],
+                [0.7, 0.3],
+                [
+                    {'phi': 0.2, 'central_vote': range(5)},
+                    {'phi': 0.9, 'central_vote': [4, 3, 2, 1, 0]}
+                ],
+            )
     """
 
     if len(num_voters_per_sampler) != len(samplers):

prefsampling/core/filters.py

@@ -27,6 +27,32 @@ def permute_voters(
     -------
         np.ndarray
             Ordinal votes.
+
+    Examples
+    --------
+
+        .. testcode::
+
+            from prefsampling.ordinal import didi
+            from prefsampling.core import permute_voters
+
+            # Get some votes
+            ordinal_votes = didi(2, 3, (0.5, 0.2, 0.1))
+
+            # Randomly permute the voters
+            permute_voters(ordinal_votes)
+
+            # The syntax is the same with approval votes
+
+            from prefsampling.approval import resampling
+
+            approval_votes = resampling(2, 3, 0.5, 0.2)
+            permute_voters(approval_votes)
+
+            # You can set the seed for reproducibility
+
+            permute_voters(approval_votes, seed=234)
+
     """
     rng = np.random.default_rng(seed)
     rng.shuffle(votes)
@@ -59,6 +85,31 @@ def rename_candidates(
     -------
         list[set[int]] or np.ndarray
             Votes with renamed candidates.
+
+    Examples
+    --------
+
+        .. testcode::
+
+            from prefsampling.ordinal import didi
+            from prefsampling.core import rename_candidates
+
+            # Get some votes
+            ordinal_votes = didi(2, 3, (0.5, 0.2, 0.1))
+
+            # Randomly permute the voters
+            rename_candidates(ordinal_votes)
+
+            # With approval votes, you need to give the number of candidates
+
+            from prefsampling.approval import resampling
+
+            approval_votes = resampling(2, 3, 0.5, 0.2)
+            rename_candidates(approval_votes, num_candidates=3)
+
+            # You can set the seed for reproducibility
+
+            permute_voters(approval_votes, num_candidates=3, seed=234)
     """
     rng = np.random.default_rng(seed)
 
@@ -85,8 +136,11 @@ def resample_as_central_vote(
     votes: np.ndarray | list[set[int]], sampler: Callable, sampler_parameters: dict
 ) -> np.ndarray | list[set[int]]:
     """
-    Resamples the votes by using them as the central vote of a given sampler. Only samplers that
-    accept a :code:`central_vote` argument can be used.
+    Resamples the votes by using them as the central vote of a given sampler. The outcome is
+    obtained as follows: for each input vote, we pass it to the sampler as central vote; a single
+    vote is then resampled and added to the outcome.
+
+    Only samplers that accept a :code:`central_vote` argument can be used.
 
     Votes are copied before being returned to avoid loss of data.
 
@@ -104,6 +158,36 @@ def resample_as_central_vote(
     -------
         list[set[int]] or np.ndarray
             Votes resampled.
+
+    Examples
+    --------
+
+        .. testcode::
+
+            from prefsampling.ordinal import urn, mallows
+            from prefsampling.core import rename_candidates
+
+            # Get some votes
+            ordinal_votes = urn(2, 3, 0.2)
+
+            # We resample them by passing them as central vote to a Mallows' model
+            resample_as_central_vote(ordinal_votes, mallows, {'phi': 0.3})
+
+            # The syntax is the same with approval votes
+
+            from prefsampling.approval import urn, resampling
+
+            approval_votes = urn(2, 3, 0.5, 0.2)
+            resample_as_central_vote(approval_votes, resampling, {'phi': 0.4, 'p': 0.8})
+
+            # To ensure reproducibility, you need to pass the seed everywhere
+            seed = 4234
+            approval_votes = urn(2, 3, 0.5, 0.2, seed=seed)
+            resample_as_central_vote(
+                approval_votes,
+                resampling,
+                {'phi': 0.4, 'p': 0.8, 'seed':seed}
+            )
     """
     res = deepcopy(votes)
     sampler_parameters["num_voters"] = 1

prefsampling/ordinal/identity.py

@@ -37,7 +37,7 @@ def identity(num_voters: int, num_candidates: int, seed: int = None) -> np.ndarr
 
             from prefsampling.ordinal import identity
 
-            # Sample from a unanimous profile with 2 voters and 3 candidates
+            # Sample a unanimous profile with 2 voters and 3 candidates
             identity(2, 3)
 
             # The seed will not change anything here, but you can still set it.

prefsampling/tree/schroeder.py

@@ -172,7 +172,7 @@ def schroeder_tree_lescanne(
 ) -> Node:
     """
     Samples a random Schröder tree following the algorithm provided by `Lescanne (2022)
-    <https://arxiv.org/abs/2205.11982>`_. The sampler is directcly taken from the `corresponding
+    <https://arxiv.org/abs/2205.11982>`_. The sampler is directly taken from the `corresponding
     GitHub repository <https://github.com/PierreLescanne/Motzkin>`_ (no licence available).
 
     If a specific number of internal nodes is given, trees are sampled at random until the required
@@ -308,7 +308,9 @@ def schroeder_tree_brute_force(
     """
     all_trees = all_schroeder_tree(num_leaves, num_internal_nodes=num_internal_nodes)
     rng = np.random.default_rng(seed)
-    return rng.choice(all_trees)
+    res = rng.choice(all_trees)
+    res.rename_frontier()
+    return res
 
 
 def _partition_schroeder_nodes(num_nodes: int, num_leaves: int) -> list[list[int]]:

tests/test_samplers/ordinal/test_all_ordinal_samplers.py

@@ -2,12 +2,6 @@
 
 import numpy as np
 
-from prefsampling.core import (
-    permute_voters,
-    rename_candidates,
-    resample_as_central_vote,
-    mixture,
-)
 from prefsampling.ordinal import mallows
 from tests.test_samplers.ordinal.test_ordinal_didi import (
     all_test_samplers_ordinal_didi,

tests/test_samplers/test_all_samplers.py

@@ -5,8 +5,8 @@
 
 
 def all_random_samplers():
-    samplers = all_test_samplers_approval()
-    samplers += all_test_samplers_ordinal()
+    samplers = all_test_samplers_ordinal()
+    samplers += all_test_samplers_approval()
     return samplers