socialchoicekit.profile_utils module
- class socialchoicekit.profile_utils.CompleteProfile[source]
Bases:
ProfileProfiles that do not have any NaN values.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the rank of alternative or item j in the preference list of agent i. The rank is an integer, where 1 is the most preferred.
- static of(arr: ndarray) → CompleteProfile[source]
- class socialchoicekit.profile_utils.CompleteProfileWithTies[source]
Bases:
ProfileWithTies,CompleteProfileCorresponds to ToC (Orders with Ties - Complete List) in Preflib.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the rank of alternative or item j in the preference list of agent i. The rank is an integer, where 1 is the most preferred. The profile allows ties (i.e., two or more alternatives can have the same rank for an agent).
- static of(arr: ndarray) → CompleteProfileWithTies[source]
- class socialchoicekit.profile_utils.CompleteValuationProfile[source]
Bases:
ValuationProfileValuation profiles that do not have any NaN values.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the utility value (agent’s cardinal preference) for alternative or item j.
- static of(arr: ndarray) → CompleteValuationProfile[source]
- class socialchoicekit.profile_utils.IncompleteProfile[source]
Bases:
ProfileProfiles that have NaN values.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the rank of alternative or item j in the preference list of agent i. The rank is an integer, where 1 is the most preferred. If the rank is unknown or the item is unacceptable, the element would be NaN.
- static of(arr: ndarray) → IncompleteProfile[source]
- class socialchoicekit.profile_utils.IncompleteProfileWithTies[source]
Bases:
ProfileWithTies,IncompleteProfileCorresponds to ToI (Orders with Ties - Incomplete List) in Preflib.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the rank of alternative or item j in the preference list of agent i. The rank is an integer, where 1 is the most preferred. If the rank is unknown or the item is unacceptable, the element would be NaN. The profile allows ties (i.e., two or more alternatives can have the same rank for an agent).
- static of(arr: ndarray) → IncompleteProfileWithTies[source]
- class socialchoicekit.profile_utils.IncompleteValuationProfile[source]
Bases:
ValuationProfileValuation profiles that have NaN values.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the utility value (agent’s cardinal preference) for alternative or item j. If the value is unknown or the item is unacceptable, the element would be NaN.
- static of(arr: ndarray) → IncompleteValuationProfile[source]
- class socialchoicekit.profile_utils.IntegerValuationProfile[source]
Bases:
CompleteValuationProfileValuation profile with only integer values. An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the utility value (agent’s cardinal preference) for alternative or item j. Note that an integer valuation profile must be complete because it cannot have NaN values.
- static of(arr: ndarray) → IntegerValuationProfile[source]
- class socialchoicekit.profile_utils.Profile[source]
Bases:
ndarrayThe generic profile class. In the background, this is just a numpy array.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the rank of alternative or item j in the preference list of agent i. The rank is an integer, where 1 is the most preferred. If the rank is unknown or the item is unacceptable, the element would be NaN.
- class socialchoicekit.profile_utils.ProfileWithTies[source]
Bases:
ProfileProfiles that allow ties.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the rank of alternative or item j in the preference list of agent i. The rank is an integer, where 1 is the most preferred. If the rank is unknown or the item is unacceptable, the element would be NaN. The profile allows ties (i.e., two or more alternatives can have the same rank for an agent).
- static of(arr: ndarray) → ProfileWithTies[source]
- class socialchoicekit.profile_utils.StrictCompleteProfile[source]
Bases:
StrictProfile,CompleteProfileCorresponds to SoC (Strict Orders - Complete List) in Preflib.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the rank of alternative or item j in the preference list of agent i. The rank is an integer, where 1 is the most preferred. The profile does not allow ties (i.e., no two alternatives can have the same rank for an agent).
- static of(arr: ndarray) → StrictCompleteProfile[source]
- class socialchoicekit.profile_utils.StrictIncompleteProfile[source]
Bases:
StrictProfile,IncompleteProfileCorresponds to SoI (Strict Orders - Incomplete List) in Preflib.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the rank of alternative or item j in the preference list of agent i. The rank is an integer, where 1 is the most preferred. If the rank is unknown or the item is unacceptable, the element would be NaN. The profile does not allow ties (i.e., no two alternatives can have the same rank for an agent).
- static of(arr: ndarray) → StrictIncompleteProfile[source]
- class socialchoicekit.profile_utils.StrictProfile[source]
Bases:
ProfileProfiles that do not allow ties.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the rank of alternative or item j in the preference list of agent i. The rank is an integer, where 1 is the most preferred. If the rank is unknown or the item is unacceptable, the element would be NaN. The profile does not allow ties (i.e., no two alternatives can have the same rank for an agent).
- static of(arr: ndarray) → StrictProfile[source]
- class socialchoicekit.profile_utils.ValuationProfile[source]
Bases:
ndarrayThe generic valuation profile class. In the background, this is just a numpy array.
An (N, M) array, where N is the number of agents and M is the number of alternatives or items. The element at (i, j) indicates the utility value (agent’s cardinal preference) for alternative or item j. If the value is unknown or the item is unacceptable, the element would be NaN.
- static of(arr: ndarray) → ValuationProfile[source]
- socialchoicekit.profile_utils.compute_ordinal_profile(cardinal_profile: ValuationProfile) → StrictProfile[source]
Computes the ordinal utility from the inputted cardinal utility. The input cardinal utility does not need to be normalized or complete.
Parameters
- cardinal_profile: ValuationProfile
A (N, M) array, where N is the number of agents and M is the number of items or 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
- StrictProfile
A (N, M) array, where N is the number of agents and M is the number of items or alternatives. The element at (i, j) indicates the agent’s ordinal utility for alternative j, where 1 is the most preferred alternative and M is the least preferred alternative. If the agent finds an item or alternative unacceptable, the element would be np.nan. This would be a StrictCompleteProfile if the input cardinal_profile is a CompleteValuationProfile. Otherwise, this would be a StrictIncompleteProfile.
- socialchoicekit.profile_utils.incomplete_profile_to_complete_profile(profile: Profile, tie_breaker: str = 'random') → CompleteProfile[source]
Converts an incomplete profile to a complete profile. np.nan values will be assigned a rank such that they are least preferred.
Parameters
profile: Profile
- tie_breaker: {“random”, “first”, “accept”}
“random”: shuffle np.nan items into a random order
“first”: sort the np.nan items in ascending order
“accept”: give all np.nan items the same rank - this results in a non-strict profile
Returns
- StrictCompleteProfile
if profile is StrictProfile and tie_breaker is not “accept”
- CompleteProfileWithTies
otherwise
- socialchoicekit.profile_utils.incomplete_valuation_profile_to_complete_valuation_profile(valuation_profile: ValuationProfile) → CompleteValuationProfile[source]
Converts an incomplete valuation profile to a complete valuation profile. np.nan values will be assigned a value of 0.
Parameters
valuation_profile: ValuationProfile
Returns
CompleteValuationProfile
- socialchoicekit.profile_utils.is_consistent_valuation_profile(valuation_profile: ValuationProfile, profile: Profile)[source]
Checks if the supplied valuation profile is consistent with the supplied ordinal profile.
Parameters
valuation_profile: ValuationProfile
profile: Profile
Returns
- bool
True if the valuation profile is consistent with the ordinal profile. False otherwise.
- socialchoicekit.profile_utils.profile_with_ties_to_strict_profile(profile: Profile, tie_breaker: str = 'random')[source]
Converts a profile with ties to a strict profile. If there are ties, the tie_breaker will be used to break the ties.
Parameters
profile: Profile
- tie_breaker: {“random”, “first”}
accept is not allowed. - “random”: shuffle the tied items into a random order - “first”: sort the tied items in ascending order
Returns
- StrictCompleteProfile
if profile is CompleteProfile
- StrictIncompleteProfile
otherwise