socialchoicekit.elicitation_utils module

class socialchoicekit.elicitation_utils.Elicitor(memoize: bool = True, zero_indexed: bool = False)[source]

Bases: object

The Elicitor class responds to queries by the elicitation algorithms. This class is the base class and hence is not meant to be instantiated.

Parameters

memoize: bool: IF True, the elicitor will memoize the elicited values. If False, the elicitor may ask repeated questions. When the memoized value is referenced, the elicitation count will not change. True by default.
zero_indexedbool: If True, the input of the elicit function will be zero-indexed. If False, the input will be one-indexed. One-indexed by default.

elicit(agent: int, alternative: int) → float[source]

Returns the agent’s preference for the alternative.

Parameters

agent: int: The agent’s index.
alternative: int: The alternative’s index.

Returns

float: The agent’s preference for the alternative.

elicit_multiple(agents: ndarray, alternatives: ndarray) → ndarray[source]

Given an agents array and an alternative array both of size N, returns an array of size N containing the elicited values. (The ith agent is elicited about the ith alternative.)

Parameters

agents: np.ndarray: The agents array. Must contain only integers that correspond to a valid agent.
alternatives: np.ndarray: The alternatives array. Must contain only integers that correspond to a valid alternative.

Returns

np.ndarray: The elicited values. Size is the same as the size of the two input arrays.

class socialchoicekit.elicitation_utils.IntegerElicitor(memoize: bool = True, zero_indexed: bool = False)[source]

Bases: Elicitor

This class is the base class for elicitors that elicit integer values Therefore, this is not meant to be instantiated.

Parameters

memoize: bool: IF True, the elicitor will memoize the elicited values. If False, the elicitor may ask repeated questions. When the memoized value is referenced, the elicitation count will not change. True by default.
zero_indexedbool: If True, the input of the elicit function will be zero-indexed. If False, the input will be one-indexed. One-indexed by default.

elicit(agent: int, alternative: int) → int[source]

Returns the agent’s preference for the alternative.

Parameters

agent: int: The agent’s index.
alternative: int: The alternative’s index.

Returns

int: The agent’s preference for the alternative.

elicit_multiple(agents: ndarray, alternatives: ndarray) → ndarray[source]

Given an agents array and an alternative array both of size N, returns an array of size N containing the elicited values. (The ith agent is elicited about the ith alternative.)

Parameters

agents: np.ndarray: The agents array. Must contain only integers that correspond to a valid agent.
alternatives: np.ndarray: The alternatives array. Must contain only integers that correspond to a valid alternative.

Returns

np.ndarray: The elicited values. Size is the same as the size of the two input arrays. The array is of integer type.

class socialchoicekit.elicitation_utils.IntegerLambdaElicitor(elicitation_function: Callable[[int, int], float], memoize: bool = True, zero_indexed: bool = True)[source]

Bases: IntegerElicitor

Responds to queries by calling a user-provided function.

Parameters

elicitation_function: Callable[[int, int], float]: A function that takes in the agent’s index and the alternative’s index and returns the agent’s preference for the alternative. This function should return an integer but in float form.
memoize: bool: If True, the elicitor will memoize the elicited values. If False, the elicitor may ask repeated questions. When the memoized value is referenced, the elicitation count will not change. True by default.
zero_indexedbool: If True, the input of the elicit function will be zero-indexed. If False, the input will be one-indexed. Zero-indexed by default.

class socialchoicekit.elicitation_utils.IntegerSynchronousStdInElicitor(preflib_instance: OrdinalInstance | None = None, memoize: bool = True, zero_indexed: bool = False)[source]

Bases: IntegerElicitor

Responds to queries by reading each answer from the standard input synchronously. Outputs questions in English to the standard output.

Parameters

zero_indexedbool: If True, the input of the elicit function will be zero-indexed. If False, the input will be one-indexed. One-indexed by default.
memoize: bool: IF True, the elicitor will memoize the elicited values. If False, the elicitor may ask repeated questions. When the memoized value is referenced, the elicitation count will not change. True by default.

class socialchoicekit.elicitation_utils.IntegerValuationProfileElicitor(valuation_profile: IntegerValuationProfile, memoize: bool = True)[source]

Bases: IntegerElicitor

Responds to queries from an integer valuation profile that is fully pre-populated.

Parameters

valuation_profile: IntegerValuationProfile: This is the cardinal 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.
memoize: bool: IF True, the elicitor will memoize the elicited values. If False, the elicitor may ask repeated questions. When the memoized value is referenced, the elicitation count will not change. True by default.

class socialchoicekit.elicitation_utils.LambdaElicitor(elicitation_function: Callable[[int, int], float], memoize: bool = True, zero_indexed: bool = True)[source]

Bases: Elicitor

Responds to queries by calling a user-provided function.

Parameters

elicitation_function: Callable[[int, int], float]: A function that takes in the agent’s index and the alternative’s index and returns the agent’s preference for the alternative.
memoize: bool: If True, the elicitor will memoize the elicited values. If False, the elicitor may ask repeated questions. When the memoized value is referenced, the elicitation count will not change. True by default.
zero_indexedbool: If True, the input of the elicit function will be zero-indexed. If False, the input will be one-indexed. Zero-indexed by default.

class socialchoicekit.elicitation_utils.SynchronousStdInElicitor(preflib_instance: OrdinalInstance | None = None, memoize: bool = True, zero_indexed: bool = False)[source]

Bases: Elicitor

Responds to queries by reading each answer from the standard input synchronously. Outputs questions in English to the standard output.

Parameters

zero_indexedbool: If True, the input of the elicit function will be zero-indexed. If False, the input will be one-indexed. One-indexed by default.
memoize: bool: IF True, the elicitor will memoize the elicited values. If False, the elicitor may ask repeated questions. When the memoized value is referenced, the elicitation count will not change. True by default.

class socialchoicekit.elicitation_utils.ValuationProfileElicitor(valuation_profile: ValuationProfile, memoize: bool = True)[source]

Bases: Elicitor

Responds to queries from a valuation profile that is fully pre-populated.

Parameters

valuation_profile: ValuationProfile: This is the cardinal 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. If the agent finds an alternative unacceptable, the element would be np.nan.
memoize: bool: IF True, the elicitor will memoize the elicited values. If False, the elicitor may ask repeated questions. When the memoized value is referenced, the elicitation count will not change. True by default.