compsoc package

Submodules

compsoc.evaluate module

Evaluation functions

compsoc.evaluate.evaluate_voting_rules(num_candidates: int, num_voters: int, topn: int, voters_model: str, distortion_ratio: float = 0.0, verbose: bool = False) → dict[str, dict[str, float]]

Evaluates various voting rules and returns a dictionary with the results.

Parameters:

• num_candidates (int) – The number of candidates.

• num_voters (int) – The number of voters.

• topn (int) – The number of top candidates to consider for utility calculation.

• voters_model (str) – The model used to generate the voter profiles.

• distortion_ratio (int, optional) – The distortion rate, defaults to 0.0.

• verbose (bool, optional) – Print additional information if True, defaults to False.

Returns:

A dictionary containing the results for each voting rule.

Return type:

dict[str, dict[str, float]]

compsoc.evaluate.get_rule_utility(profile: Profile, rule: Callable[[Profile, int], any], topn: int, verbose=False)

Calculates the total utility and “top n” utility for a given rule.

Parameters:

• profile (Profile) – The voting profile.

• rule (Callable[[int], int],# | float],) – The voting rule function.

• topn (int) – The number of top candidates to consider for utility calculation.

• verbose (bool, optional) – Print additional information if True, defaults to False.

Returns:

A dictionary containing the total utility for the top candidate and the total utility for top n candidates.

Return type:

dict[str, float]

compsoc.evaluate.voter_subjective_utility_for_elected_candidate(elected: List[int], vote: Tuple[int], topn: int) → tuple

Calculates the subjective utility of an individual voter for an elected candidate.

Parameters:

• elected (List[int]) – List of elected candidates.

• vote (Tuple[int]) – A tuple containing a voter’s ranked candidates.

• topn (int) – The number of top candidates to consider for utility calculation.

Returns:

A tuple containing utility for the top candidate and total utility for top n candidates.

Return type:

tuple

compsoc.plot module

Plotting the scores

compsoc.plot.plot_comparison_results(voter_model: str, results: dict, num_voters: int, num_candidates: int, num_topn: int, number_iterations: int, distortion_ratio=0.0, save_figure: bool = False)

Plot the mean scores for all voting rules.

Parameters:

• voter_model (str) – The generative model to use.

• results (dict) – The voting rule result data to be plotted. Key is the index of iteration.

• num_voters (int) – The number of voters in the model.

• num_candidates (int) – The number of candidates in the model.

• num_topn (int) – The number of top candidates to consider.

• number_iterations (int) – The number of iterations for the simulation.

• save_figure (bool, optional) – If True, saves the figure as a png file, defaults to False.

Returns:

Base64 encoded string representation of the plot image.

Return type:

str

compsoc.profile module

Voting profiles

class compsoc.profile.Profile(pairs: Set[Tuple[int, Tuple[int, ...]]], num_candidates: int | None = None, distorted: bool = False)

Bases: object

A class to represent a voting profile as a set of tuples, where each tuple consists of the number of occurrences and a ballot (an ordering of the candidates). For example, a Profile object with the following data: votes = Profile({(17, (1,3,2,0)), (40, (3,0,1,2)), (52, (1,0,2,3))}) means 17 people like candidate 1 the most, then candidate 3 in the second position, then candidate 2 in the third position, and so on.

Attributes:

pairs (Set[Tuple[int, Tuple[int, …]]]): A set of pairs (number of votes, ballot). candidates (Set[int]): A set of candidates in ballots. total_votes (int): The total number of votes. net_preference_graph (Dict[int, Dict[int, int]]): Represents the net preference graph. votes_per_candidate (List[Dict[int, int]]): The total votes for each candidate per rank position.

classmethod ballot_box(choices)

Creates a VotingProfile instance from a list of ranked candidates.

Parameters:

choices (list of tuples) – A list of ranked candidates, i.e, [(voter’s 1 ranked candidates), (voter’s 2 ranked candidates), (voter’s 3 ranked candidates), …]

Returns:

A VotingProfile instance with the set of (number of votes, candidates ranked).

Return type:

VotingProfile

distort(ratio: float)

Alters a profile to generate an incomplete or “distorted” profile, the ratio must be in [0., 1.[ ratio=0 means no distortion at all, and ratio=1 indicates all ballots only keep the first candidate (just a convention)

does_pareto_dominate(candidate1, candidate2) → bool

Checks if candidate1 is preferred over candidate2 in all ballots.

Parameters:

• candidate1 (int) – The first candidate to be compared.

• candidate2 (int) – The second candidate to be compared.

Returns:

True if candidate1 is preferred in all ballots, False otherwise.

Return type:

bool

get_net_preference(candidate1, candidate2)

Computes the preference between two candidates according to the net preference graph.

Parameters:

• candidate1 (int) – The first candidate to be compared.

• candidate2 (int) – The second candidate to be compared.

Returns:

The preference value of candidate1 over candidate2.

Return type:

int

classmethod parse_voting_data(file_path)

Parses a voting data file and creates a Profile instance.

Parameters:

file_path (str) – Path to the voting data file.

Returns:

A Profile instance.

Return type:

Profile

ranking(scorer) → List[tuple[int, float]]

Returns a list of candidate rankings according to a specified scoring function.

Parameters:

scorer (Callable) – The scoring function (e.g., Borda, Copeland).

Returns:

A list of tuples (candidate, score), ordered by score in descending order.

Return type:

List[Tuple[int, float]]

score(scorer) → List[tuple[int, float]]

Returns a list of candidate scores according to a specified scoring function.

Parameters:

scorer (Callable) – The scoring function (e.g., Borda, Copeland).

Returns:

A sorted list of tuples (candidate, score), ordered by candidate ID in increasing order.

Return type:

List[Tuple[int, float]]

winners(scorer)

Returns a set of candidate winners according to a given scoring function.

Parameters:

scorer (callable) – A scoring function (e.g., Borda, Copeland).

Returns:

A set of winning candidates.

Return type:

set

compsoc.utils module

This module contains utility functions for the compsoc website.

compsoc.utils.int_list_to_str(int_list: list[int]) → str

Converts a list of integers to a comma-separated string.

Parameters:

int_list (list[int]) – A list of integers.

Returns:

A comma-separated string.

Return type:

str

compsoc.utils.str_list_to_in(str_list: str) → list[int]

Converts a comma-separated string to a list of integers.

Parameters:

str_list (str) – A comma-separated string.

Returns:

A list of integers.

Return type:

list[int]

compsoc.voter_model module

Voter models Definition of the ballots of the voters according to different generative models. Results are probabilistic distributions over votes.

compsoc.voter_model.generate_distorted_from_normal_profile(origin_profile: Profile, distortion_ratio: float) → Profile

distort a normal profile to generate a distorted profile, distortion_ratio is from 0. to 1. 0 mesns no ditortion at all, and 1 means all ballots only keeps the first candidate.

compsoc.voter_model.generate_gaussian_votes(mu: float, stdv: float, num_voters: int, num_candidates: int, plot_save: bool | None = False) → List[Tuple[int, Tuple[int, ...]]]

compsoc.voter_model.generate_multinomial_dirichlet_votes(alpha: Tuple[float, ...], num_voters: int, num_candidates: int) → List[Tuple[int, Tuple[int, ...]]]

Generates a list of pairs (count, vote) from a Dirichlet Multinomia model of voters.

compsoc.voter_model.generate_random_votes(number_voters: int, number_candidates: int) → List[Tuple[int, Tuple[int, ...]]]

compsoc.voter_model.get_pairs_from_model(num_candidates: int, num_voters: int, voters_model: str, *args, **kwargs)

Generates a list of pairs (count, vote) from a model of voters.

compsoc.voter_model.get_profile_from_model(num_candidates: int, num_voters: int, voters_model: str, verbose=False) → Profile

Generates a profile from a model of voters.

Module contents