socialchoicekit.utils module
- socialchoicekit.utils.break_tie(alternatives: ndarray, tie_breaker: str = 'random', include_accept: bool = True) → ndarray | int[source]
Breaks a tie among winning alternatives according to the tie breaker.
Parameters
- alternativesnp.ndarray
The alternatives that are tied.
- tie_breaker{“random”, “first”, “accept”}
The tie breaker to use. - “random”: pick from a uniform distribution among the losers to drop - “first”: pick the alternative with the lowest index - “accept”: return all winners in an array
- include_acceptbool
If True, “accept” is a valid tie breaker. If False, “accept” is not a valid tie breaker.
- socialchoicekit.utils.check_bipartite_graph(G: Dict[int, List[int]], X: list, Y: list) → None[source]
Checks that a dictionary represents a bipartite graph.
Parameters
- GDict[int, List[int]]
A dictionary of the form {i: [j, k, …]} where i is the index of a vertex and [j, k, …] are the indices of the vertices that i is connected to. The graph may be directed or undirected. If it is directed, then the edges are assumed to be directed from X to Y.
- X: list
The list of the left vertices (in the first partition) in the bipartite graph G.
- Y: list
The list of the right vertices (in the second partition) in the bipartite graph G.
Raises
- ValueError
If the graph is not bipartite.
- socialchoicekit.utils.check_graph(G: Dict[int, List[int]]) → None[source]
Checks that a dictionary represents a graph.
Parameters
- GDict[int, List[int]]
A dictionary of the form {i: [j, k, …]} where i is the index of a vertex and [j, k, …] are the indices of the vertices that i is connected to. The graph may be directed or undirected.
Raises
- ValueError
If the graph is not a dictionary. If the graph is not two-dimensional. If the graph contains NaN values. If the graph contains values other than integers.
- socialchoicekit.utils.check_profile(profile: ndarray, is_complete: bool = True, is_strict: bool = True) → None[source]
Checks that the profile is a numpy array with the correct dimensions.
Parameters
- profile: np.ndarray
This is the ordinal profile. A (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 agent’s preference for alternative j, where 1 is the most preferred alternative.
- is_complete: bool
If True, the profile does not have any NaN values. If False, the profile has NaN values. True by default.
- is_strict: bool
If True, the profile does not allow ties. If False, the profile allows ties. True by default.
Raises
- ValueError
If the profile is not a numpy array If the profile is not two-dimensional. If the profile contains NaN values. If the profile contains values other than integers from 1 to M.
- socialchoicekit.utils.check_square_matrix(matrix: ndarray) → None[source]
Checks that the matrix is a numpy array that represents a square matrix.
Parameters
- matrix: np.ndarray
This is the matrix to check. An (M, M) array.
Raises
- ValueError
If the matrix is not a numpy array If the matrix is not two-dimensional. If the matrix is not square.
- socialchoicekit.utils.check_tie_breaker(tie_breaker: str, include_accept: bool = True) → None[source]
Checks that the tie breaker is valid.
Parameters
- tie_breaker{“random”, “first”, “accept”}
The tie breaker to check. - “random”: pick from a uniform distribution among the losers to drop - “first”: pick the alternative with the lowest index - “accept”: return all winners in an array
- include_acceptbool
If True, “accept” is a valid tie breaker. If False, “accept” is not a valid tie breaker.
Raises
- ValueError
If the tie breaker is not recognized.
- socialchoicekit.utils.check_valuation_profile(valuation_profile: ndarray, is_complete: bool = False) → None[source]
Checks that the valuation profile is a numpy array with the correct dimensions.
Parameters
- valuation_profile: np.ndarray
This is the (partial) cardinal profile. A (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, the element would be NaN.
- is_complete: bool
If True, the valuation profile does not have any NaN values. If False, the valuation profile has NaN values. False by default.