abcvoting.scores
Calculate all kinds of scores.
- exception abcvoting.scores.UnknownScoreFunctionError(scorefct_id)
Exception raised if unknown rule id is used.
- Parameters:
- scorefct_idstr
The score function id that is not known.
- abcvoting.scores.at_least_ell_fct(i, ell)
At-least-ell marginal score function.
This is the additional (marginal) score from a voter for the i-th approved candidate in the committee.
Gives a score of 1 if ell approved candidates are in the committee. The CC score function is equivalent to the at_least_ell_fct score function for ell=1.
- Parameters:
- iint
We are calculating the score for the i-th approved candidate in the committee.
- ellint
Gives a score of 1 if ell approved candidates are in the committee.
- Returns:
- Fraction
The corresponding marginal score.
- abcvoting.scores.av_score_fct(i)
AV marginal score function.
This is the additional (marginal) score from a voter for the i-th approved candidate in the committee.
Note: this is used only for unit tests at the moment, because AV is separable anyway and therefore not implemented as optimization problem.
- Parameters:
- iint
We are calculating the score for the i-th approved candidate in the committee.
- Returns:
- Fraction
The corresponding marginal score.
- abcvoting.scores.cc_score_fct(i)
CC (Chamberlin-Courant) marginal score function.
This is the additional (marginal) score from a voter for the i-th approved candidate in the committee.
- Parameters:
- iint
We are calculating the score for the i-th approved candidate in the committee.
- Returns:
- Fraction
The corresponding marginal score.
- abcvoting.scores.cumulative_score(marginal_scorefct, cand_in_com)
Return cumulative score using the marginal score function marginal_scorefct for a voter.
A cumulative score function f(i) returns the total score for having i candidates in the committee (as opposed to score functions that return the score increase when adding the i-th candidate).
- Parameters:
- marginal_scorefctfunc
The marginal score function.
- cand_in_comint
The number of approved candidates in the committee.
- Returns:
- Fraction
Score of a voter with cand_in_com many approved candidates in the committee.
- abcvoting.scores.geometric_marginal_score_fct(i, base)
Geometric marginal score functions.
This is the additional (marginal) score from a voter for the i-th approved candidate in the committee.
For example, the 2-Geometric marginal scoring function (base=2) is
\[f(i) = 1 / 2^{i-1}.\]For a mathematical description of Geometric score functions, see e.g. Martin Lackner and Piotr Skowron Utilitarian Welfare and Representation Guarantees of Approval-Based Multiwinner Rules In Artificial Intelligence, 288: 103366, 2020. https://arxiv.org/abs/1801.01527
- Parameters:
- iint
We are calculating the score for the i-th approved candidate in the committee.
- basefloat or int or Fraction
The base for the geometric function 1 / base ** (i-1).
- Returns:
- Fraction
The corresponding marginal score.
- abcvoting.scores.get_marginal_scorefct(scorefct_id, committeesize=None)
Return marginal score function (for a Thiele method) given its name.
- Parameters:
- scorefct_idstr
A string identifying the score function.
- committeesizeint, optional
Committee size.
Some marginal score functions require fixing the size of committees.
- Returns:
- function
The corresponding marginal score function.
- abcvoting.scores.marginal_thiele_scores_add(marginal_scorefct, profile, committee)
Return marginal score increases from adding one candidate to the committee.
The function returns a list of length num_cand where the i-th entry contains the marginal score increase when adding candidate i. Candidates that are already in the committee receive a small value (-1).
- Parameters:
- marginal_scorefctfunc
The marginal score function to be used.
- profileabcvoting.preferences.Profile
A profile.
- committeeiterable of int
A committee.
- Returns:
- list
Marginal score increases from adding candidates to the committee.
- abcvoting.scores.marginal_thiele_scores_remove(marginal_scorefct, profile, committee)
Return marginal score decreases from removing one candidate from the committee.
The function returns a list of length num_cand where the i-th entry contains the marginal score decrease when removing candidate i. Candidates that are not in the committee receive a large value (max(marg_util_cand) + 1).
- Parameters:
- marginal_scorefctfunc
The marginal score function to be used.
- profileabcvoting.preferences.Profile
A profile.
- committeeset
A committee.
- Returns:
- list
Marginal score decreases from removing candidates from the committee.
- abcvoting.scores.minimaxav_score(profile, committee)
Return the Minimax AV (MAV) score of a committee.
- Parameters:
- profileabcvoting.preferences.Profile
A profile.
- committeeiterable of int
A committee.
- Returns:
- int
The Minimax AV score of committee.
- abcvoting.scores.monroescore(profile, committee)
Return Monroe score of a given committee.
- Parameters:
- profileabcvoting.preferences.Profile
A profile.
- committeeiterable of int
A committee.
- Returns:
- int
The Monroe score.
- abcvoting.scores.monroescore_flowbased(profile, committee)
Return Monroe score of a given committee.
Uses a flow-based algorithm that works even if committeesize does not divide the number of voters. Slower than monroescore_matching().
- Parameters:
- profileabcvoting.preferences.Profile
A profile.
- committeeset
A committee.
- Returns:
- int
The Monroe score.
- abcvoting.scores.monroescore_matching(profile, committee)
Return Monroe score of a given committee.
Uses a matching-based algorithm that works only if the committee size divides the number of voters.
- Parameters:
- profileabcvoting.preferences.Profile
A profile.
- committeeset
A committee.
- Returns:
- int
The Monroe score.
- abcvoting.scores.num_voters_with_upper_bounded_hamming_distance(upperbound, profile, committee)
Return the number of voters having a Hamming distance <= upperbound to the given committee.
- Parameters:
- upperboundint
The Hamming distance upper bound.
- profileabcvoting.preferences.Profile
A profile.
- committeeset
A committee.
- Returns:
- int
The number of voters having a Hamming distance <= upperbound.
- abcvoting.scores.pav_score_fct(i)
PAV marginal score function.
This is the additional (marginal) score from a voter for the i-th approved candidate in the committee.
- Parameters:
- iint
We are calculating the score for the i-th approved candidate in the committee.
- Returns:
- Fraction
The corresponding marginal score.
- abcvoting.scores.slav_score_fct(i)
SLAV (Sainte-Lague Approval Voting) marginal score function.
This is the additional (marginal) score from a voter for the i-th approved candidate in the committee.
For a mathematical description of this score function, see e.g. Martin Lackner and Piotr Skowron Utilitarian Welfare and Representation Guarantees of Approval-Based Multiwinner Rules In Artificial Intelligence, 288: 103366, 2020. https://arxiv.org/abs/1801.01527
- Parameters:
- iint
We are calculating the score for the i-th approved candidate in the committee.
- Returns:
- Fraction
The corresponding marginal score.
- abcvoting.scores.thiele_score(scorefct_id, profile, committee)
Compute Thiele score of a committee subject to a given scorefct_id.
- Parameters:
- scorefct_idstr
Identifies the score function to be used.
scorefct_id has to be recognized by abcvoting.scores.get_scorefct.
- profileabcvoting.preferences.Profile
A profile.
- committeeset or tuple or list
A committee.
- Returns:
- int or Fraction
The Thiele score using the score function given by scorefct_id.