socialchoicekit.deterministic_scoring module
- class socialchoicekit.deterministic_scoring.BaseScoring(tie_breaker: str = 'random', zero_indexed: bool = False)[source]
Bases:
objectThe abstract scoring 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.
- score(scores_by_voter: ndarray) → ndarray[source]
Common logic for the computing the score.
Parameters
- scores_by_voter: np.ndarray
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 score calculated from the voter’s preference for alternative j.
Returns
- np.ndarray
A (1, M) array of scores where the element at (0, j) indicates the score for alternative j.
- 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_scoring.Borda(tie_breaker: str = 'random', zero_indexed: bool = False)[source]
Bases:
BaseScoringThe Borda voting rule assigns the jth most preferred alternative a score of M-j, where M is the number of alternatives. The Borda voting rule then selects, as the winner(s) of an election (aka the “social choice(s)”) the alternative(s) with the highest scores.
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: CompleteProfile) → 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: CompleteProfile
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: CompleteProfile) → ndarray[source]
The scoring function for this voting rule. Returns a list of alternatives with their scores.
Notes
Complexity O(MN)
Parameters
- profile: CompleteProfile
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: CompleteProfile) → 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(MN + MlogM)
Parameters
- profile: CompleteProfile
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.
- class socialchoicekit.deterministic_scoring.Harmonic(tie_breaker: str = 'random', zero_indexed: bool = False)[source]
Bases:
BaseScoring(Temporary description) The harmonic voting rule assigns the jth most preferred alternative a score of 1/j, The harmonic voting rule then selects, as the winner(s) of an election (aka the “social choice(s)”) the alternative(s) with the highest scores.
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: CompleteProfile) → 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: CompleteProfile
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: CompleteProfile) → ndarray[source]
The scoring function for this voting rule. Returns a list of alternatives with their scores.
Notes
Complexity O(MN)
Parameters
- profile: CompleteProfile
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: CompleteProfile) → 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(MN + MlogM)
Parameters
- profile: CompleteProfile
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.
- class socialchoicekit.deterministic_scoring.KApproval(k: int, tie_breaker: str = 'random', zero_indexed: bool = False)[source]
Bases:
BaseScoringThe k-approval voting rule names the k most-preferred alternatives, and the k-approval voting rule then selects, as the winner(s) of an election (aka the “social choice(s)”) the alternative(s) with the highest number of approvals.
Parameters
- kint
A number greater than 0. If greater than or equal to M, the k-approval rule becomes trivial.
- 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(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
- 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(MN + MlogM)
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.
- class socialchoicekit.deterministic_scoring.Plurality(tie_breaker: str = 'random', zero_indexed: bool = False)[source]
Bases:
BaseScoringThe plurality voting rule names a single, most-preferred alternative, and the plurality voting rule then selects, as the winner(s) of an election (aka the “social choice(s)”) the alternative(s) with a plurality (greatest number) of votes. Alternately, we can identify a ranking with a plurality ballot for the top-ranked alternative (while we ignore the rest of the ranking).
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: Profile) → 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: Profile
A (N, M) array, where N is the number of agents and M is the number of alternatives. The element at (i, j) indicates the agent’s preference for alternative j, where 1 is the most preferred alternative. If the agent’s preference for the alternative is unknown or the alternative is unacceptable, the element would be np.nan.
Returns
- Union[np.ndarray, int]
A numpy array of the winning alternative(s) or a single winning alternative.
- score(profile: Profile) → ndarray[source]
The scoring function for this voting rule. Returns a list of alternatives with their scores.
Notes
Complexity O(MN)
Parameters
profile: Profile A (N, M) array, where N is the number of agents and M is the number of alternatives. The element at (i, j) indicates the agent’s preference for alternative j, where 1 is the most preferred alternative. If the agent’s preference for the alternative is unknown or the alternative is unacceptable, the element would be np.nan.
Returns
- np.ndarray
A (1, M) array of scores where the element at (0, j) indicates the score for alternative j.
- swf(profile: Profile) → 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(MN + MlogM)
Parameters
- profile: Profile
A (N, M) array, where N is the number of agents and M is the number of alternatives. The element at (i, j) indicates the agent’s preference for alternative j, where 1 is the most preferred alternative. If the agent’s preference for the alternative is unknown or the alternative is unacceptable, the element would be np.nan.
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.
- class socialchoicekit.deterministic_scoring.SocialWelfare(tie_breaker: str = 'random', zero_indexed: bool = False)[source]
Bases:
BaseScoringComputes the social welfare for alternatives based on an inputted valuation profile.
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 thesocial choice function will be zero-indexed. If False, the output will be one-indexed. One-indexed by default.
- scf(valuation_profile: ValuationProfile) → 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.
Parameters
- valuation_profile: ValuationProfile
A (N, M) array, where N is the number of agents and M is the number of alternatives. The element at (i, j) indicates the agent’s cardinal utility for alternative j. If the agent finds an item or alternative unacceptable, the element would be np.nan.
Returns
- Union[np.ndarray, int]
A numpy array of the winning alternative(s) or a single winning alternative.
- score(valuation_profile: ValuationProfile) → ndarray[source]
Computes the normalized social welfare for each alternative based on an inputted valuation profile. Note that the valuation profile has to be a cardinal profile, not an ordinal profile.
Parameters
- valuation_profile: ValuationProfile
A (N, M) array, where N is the number of agents and M is the number of alternatives. The element at (i, j) indicates the agent’s cardinal utility for alternative j. If the agent finds an item or alternative unacceptable, the element would be np.nan.
Returns
- np.ndarray
A (M,) array, where M is the number of alternatives. The element at (i,) indicates the social welfare of alternative i.
- class socialchoicekit.deterministic_scoring.Veto(tie_breaker: str = 'random', zero_indexed: bool = False)[source]
Bases:
BaseScoringThe veto voting rule, also known as the anti-plurality rule, names a single, least-preferred alternative, and the veto voting rule then selects, as the winner(s) of an election (aka the “social choice(s)”) the alternative(s) with the fewest vetoes.
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(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
- 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(MN + MlogM)
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.