socialchoicekit.deterministic_tournament module
- class socialchoicekit.deterministic_tournament.BaseTournament(tie_breaker: str = 'random', zero_indexed: bool = False)[source]
Bases:
objectThe abstract tournament rule. This class should not be instantiated directly.
Parameters
- tie_breaker{“random”, “first”, “accept”}
“random”: pick from a uniform distribution among the winners
“first”: pick the alternative with the lowest index
“accept”: return all winners in an array
- zero_indexedbool
If True, the output of the social welfare function and social choice function will be zero-indexed. If False, the output will be one-indexed. One-indexed by default.
- scf(score: ndarray) → ndarray | int[source]
Common logic for computing the social choice function.
Parameters
- scorenp.ndarray
A two dimensional (N, M) numpy array where N is the number of alternatives and M is the number of voters. The element at (i, j) indicates the score arising from voter i’s ordering of alternative j. Obtain this array by calling a score function in a subclass.
Returns
- Union[np.ndarray, int]
A numpy array of the winning alternative(s) or a single winning alternative.
- swf(score: ndarray) → ndarray[source]
Common logic for computing the social welfare function.
Parameters
- scorenp.ndarray
A two dimensional (N, M) numpy array where N is the number of alternatives and M is the number of voters. The element at (i, j) indicates the score arising from voter i’s ordering of alternative j. Obtain this array by calling a score function in a subclass.
Returns
- np.array
A two dimensional (2, M) numpy array where the first row indicates the alternative number and the second row indicates the score.
- class socialchoicekit.deterministic_tournament.Copeland(tie_breaker: str = 'random', zero_indexed: bool = False)[source]
Bases:
BaseTournamentCopeland rewards an alternative x for each pairwise victory x > y over an opponent and punishes her for each defeat, but disregards the margins of victory or defeat.
Parameters
- tie_breaker{“random”, “first”, “accept”}
“random”: pick from a uniform distribution among the winners
“first”: pick the alternative with the lowest index
“accept”: return all winners in an array
- zero_indexedbool
If True, the output of the social welfare function and social choice function will be zero-indexed. If False, the output will be one-indexed. One-indexed by default.
- scf(profile: StrictCompleteProfile) → ndarray | int[source]
The social choice function for this voting rule. Returns a set of alternatives with the highest scores. With a tie breaking rule, returns a single alternative.
Notes
Complexity O(MN)
Parameters
- profile: StrictCompleteProfile
A (N, M) array, where N is the number of voters and M is the number of alternatives. The element at (i, j) indicates the voter’s preference for alternative j, where 1 is the most preferred alternative.
Returns
- Union[np.ndarray, int]
A numpy array of the winning alternative(s) or a single winning alternative.
- score(profile: StrictCompleteProfile) → ndarray[source]
The scoring function for this voting rule. Returns a list of alternatives with their scores.
Notes
Complexity O(M^2 N)
Parameters
- profile: StrictCompleteProfile
A (N, M) array, where N is the number of voters and M is the number of alternatives. The element at (i, j) indicates the voter’s preference for alternative j, where 1 is the most preferred alternative.
Returns
- np.ndarray
A (1, M) array of scores where the element at (0, j) indicates the score for alternative j.
- swf(profile: StrictCompleteProfile) → ndarray[source]
The social welfare function for this voting rule. Returns a ranked list of alternatives with the scores. Note that tie breaking behavior is undefined.
Notes
Complexity O(M^N)
Parameters
- profile: StrictCompleteProfile
A (N, M) array, where N is the number of voters and M is the number of alternatives. The element at (i, j) indicates the voter’s preference for alternative j, where 1 is the most preferred alternative.
Returns
- np.ndarray
A (2, M) array of scores where the element at (0, j) indicates the alternative number for the jth alternative and (1, j) indictes the score for the jth alternative.