socialchoicekit.elicitation_voting module

class socialchoicekit.elicitation_voting.BaseElicitationVoting(tie_breaker: str = 'random', zero_indexed: bool = False)

Bases: object

The abstract base elicitation voting rule. This class should not be instantiated directly.

While there is a tie-breaking mechanism for this class, it is only used to tie-break between alternatives that have the same score. It is not used to decide which alternative would be queried (if they have the same cardinal utility).

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

Common logic for the social choice function.

Parameters

score: np.ndarray

A M-array, where M is the number of alternatives. The ith element indicates the social welfare value for alternative i.

Returns

Union[np.ndarray, int]

A numpy array of the winning alternative(s) or a single winning alternative.

class socialchoicekit.elicitation_voting.KARV(k: int = 1, tie_breaker: str = 'random', zero_indexed: bool = False)

Bases: BaseElicitationVoting

k-Acceptable Range Voting [ABFV2021] is a generalization of Lambda-Prefix Range Voting that partitions alternatives into k + 1 sets for every agent to create a simulated value function using binary search.

Parameters

k: int

The number of positions to query.

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.

get_simulated_cardinal_profile(profile: ~socialchoicekit.profile_utils.StrictCompleteProfile, elicitor: ~socialchoicekit.elicitation_utils.Elicitor = <socialchoicekit.elicitation_utils.SynchronousStdInElicitor object>) → CompleteValuationProfile

Obtain the simulated cardinal profile.

Parameters

profile: StrictCompeleteProfile

This is the ordinal profile. 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.

elicitor: Elicitor

The elicitor that will be used to query the agents.

Returns

CompleteValuationProfile

A (N, M) array where the element at (i, j) indicates the simulated welfare of alternative j for agent i.

scf(profile: ~socialchoicekit.profile_utils.StrictCompleteProfile, elicitor: ~socialchoicekit.elicitation_utils.Elicitor = <socialchoicekit.elicitation_utils.SynchronousStdInElicitor object>) → ndarray | int

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

profile: StrictCompleteProfile

This is the ordinal profile. 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.

elicitor: Elicitor

The elicitor that will be used to query the agents.

Returns

Union[np.ndarray, int]

A numpy array of the winning alternative(s) or a single winning alternative.

score(profile: ~socialchoicekit.profile_utils.StrictCompleteProfile, elicitor: ~socialchoicekit.elicitation_utils.Elicitor = <socialchoicekit.elicitation_utils.SynchronousStdInElicitor object>) → ndarray

The scoring function for this voting rule. Returns a list of alternatives with their scores.

Parameters

profile: StrictCompeleteProfile

This is the ordinal profile. 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.

elicitor: Elicitor

The elicitor that will be used to query the agents.

Returns

np.ndarray

A (1, M) array of scores where the element at (0, j) indicates the score for alternative j.

class socialchoicekit.elicitation_voting.LambdaPRV(lambda_: int = 1, tie_breaker: str = 'random', zero_indexed: bool = False)

Bases: BaseElicitationVoting

Lambda-Prefix Range Voting [ABFV2021] is the most basic elicitation voting rule that queries every agent at the first lambda >= 1 positions.

Parameters

lambda_: int

The number of positions to query.

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: ~socialchoicekit.profile_utils.StrictCompleteProfile, elicitor: ~socialchoicekit.elicitation_utils.Elicitor = <socialchoicekit.elicitation_utils.SynchronousStdInElicitor object>) → ndarray | int

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

profile: StrictCompleteProfile

This is the ordinal profile. 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.

elicitor: Elicitor

The elicitor that will be used to query the agents.

Returns

Union[np.ndarray, int]

A numpy array of the winning alternative(s) or a single winning alternative.

score(profile: ~socialchoicekit.profile_utils.StrictCompleteProfile, elicitor: ~socialchoicekit.elicitation_utils.Elicitor = <socialchoicekit.elicitation_utils.SynchronousStdInElicitor object>) → ndarray

The scoring function for this voting rule. Returns a list of alternatives with their scores.

Parameters

profile: StrictCompleteProfile

This is the ordinal profile. 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.

elicitor: Elicitor

The elicitor that will be used to query the agents.

Returns

np.ndarray

A M-array of scores where the jth element indicates the score for alternative j.