Interfaces to Other Packages¶

The pref_voting.interfaces modules convert between pref_voting election objects and the election objects of two other voting packages:

VoteKit (MGGG Redistricting Lab): ranked ballots (with ties and truncation) and score ballots.
abcvoting (Lackner et al.): approval-based committee (ABC) voting.

This makes it possible, for instance, to generate profiles with VoteKit’s ballot generators and analyze them with pref_voting’s voting methods, to run VoteKit’s elections on pref_voting profiles, or to apply abcvoting’s committee rules to pref_voting approval profiles.

The correspondence between the main election objects:

pref_voting	VoteKit	abcvoting
`Profile` (linear orders)	`PreferenceProfile` of ranked ballots	—
`ProfileWithTies` (ties, truncation)	`PreferenceProfile` of ranked ballots	—
`GradeProfile` with numeric grades	`PreferenceProfile` of score ballots	—
`GradeProfile` with grades 0/1 (approval)	—	`Profile`

Both packages are optional dependencies: they are only imported when a conversion function is called, and a plain installation of pref_voting is unchanged. To use the interfaces, install the extras:

uv pip install "pref_voting[votekit]"      # VoteKit (requires Python >= 3.11)
uv pip install "pref_voting[abcvoting]"    # abcvoting
uv pip install "pref_voting[interfaces]"   # both

Weights. VoteKit ballots and abcvoting voters carry (possibly fractional) weights, while pref_voting profiles count voters with integer counts. Integer-valued weights are converted directly; fractional weights raise a ValueError unless scale_weights=True is passed, in which case all weights are multiplied by a common denominator (an exact rescaling that preserves the relative weights of the ballots but changes the total number of voters).

All of the conversions are also available as methods on the profile classes: Profile.to_votekit(), ProfileWithTies.to_votekit() / ProfileWithTies.from_votekit(), and GradeProfile.to_votekit() / GradeProfile.from_votekit() / GradeProfile.to_abcvoting() / GradeProfile.from_abcvoting().

For a walkthrough of all the conversions, see the notebook examples/interfaces_demo.ipynb.

VoteKit¶

pref_voting.interfaces.votekit_interface.to_votekit_profile(profile)[source]¶

Convert a Profile or ProfileWithTies to a VoteKit PreferenceProfile of ranked ballots.

Candidates are named using the profile’s cmap. For a ProfileWithTies, tied candidates are placed in the same position of the VoteKit ranking, unranked candidates are omitted from the ballot, and gaps in the ranks are compressed (only the relative order of the ranks matters in a ProfileWithTies).

Parameters:: profile (Profile or ProfileWithTies) – The profile to convert.
Returns:: A VoteKit PreferenceProfile of ranked ballots.

pref_voting.interfaces.votekit_interface.votekit_to_profile_with_ties(vk_profile, scale_weights=False)[source]¶

Convert a VoteKit PreferenceProfile of ranked ballots to a ProfileWithTies.

The candidates of the resulting profile are the candidate names (strings) of the VoteKit profile. Candidates tied in a position of a VoteKit ranking are assigned the same rank; candidates missing from a ballot are unranked; skipped positions (empty frozensets) are preserved as gaps in the ranks.

Parameters:

vk_profile – A VoteKit PreferenceProfile of ranked ballots.
scale_weights (bool, optional) – If True, fractional ballot weights are scaled to integers by clearing denominators; otherwise fractional weights raise a ValueError.

Returns:

A ProfileWithTies.

pref_voting.interfaces.votekit_interface.grade_profile_to_votekit(gprofile)[source]¶

Convert a GradeProfile with numeric grades to a VoteKit PreferenceProfile of score ballots.

Candidates are named using the profile’s cmap.

Warning

VoteKit does not store scores of 0: a candidate assigned the grade 0 becomes an unscored candidate in the VoteKit profile. In particular, for approval ballots (grades 0 and 1), the explicit 0s are not preserved when converting to VoteKit and back.

Parameters:: gprofile (GradeProfile) – A grade profile with numeric grades.
Returns:: A VoteKit PreferenceProfile of score ballots.

pref_voting.interfaces.votekit_interface.votekit_to_grade_profile(vk_profile, grades=None, scale_weights=False)[source]¶

Convert a VoteKit PreferenceProfile of score ballots to a GradeProfile.

The candidates of the resulting profile are the candidate names (strings) of the VoteKit profile. Since a VoteKit profile does not carry a grade scale, the grades of the resulting profile default to the set of score values that appear in the profile; pass grades to specify the intended scale instead. Integer-valued scores (VoteKit stores scores as floats) are converted to ints. Candidates without a score on a ballot are ungraded on that ballot.

Parameters:

vk_profile – A VoteKit PreferenceProfile of score ballots.
grades (list, optional) – The grades of the resulting profile. If provided, every score in the profile must be one of these grades.
scale_weights (bool, optional) – If True, fractional ballot weights are scaled to integers by clearing denominators; otherwise fractional weights raise a ValueError.

Returns:

A GradeProfile.

abcvoting¶

pref_voting.interfaces.abcvoting_interface.to_abcvoting_profile(gprofile)[source]¶

Convert a GradeProfile with grades 0 and 1 to an abcvoting Profile.

The candidates 0, ..., num_cand - 1 of the abcvoting profile are the indices of the (sorted) candidates of the grade profile, and the candidate names of the abcvoting profile are given by the grade profile’s cmap. Each ballot type contributes one abcvoting voter, whose approval set is the set of candidates assigned the grade 1 and whose weight is the ballot count. Use abcvoting.preferences.Profile.convert_to_unit_weights() on the result if unit weights are needed.

Parameters:: gprofile (GradeProfile) – A grade profile with grades 0 and 1.
Returns:: An abcvoting Profile.

pref_voting.interfaces.abcvoting_interface.abcvoting_to_grade_profile(abc_profile, scale_weights=False)[source]¶

Convert an abcvoting Profile to a GradeProfile with grades 0 and 1.

The candidates of the grade profile are the integers 0, ..., num_cand - 1, with the cand_names of the abcvoting profile as the cmap. Each voter contributes one ballot assigning the grade 1 to each approved candidate and the grade 0 to every other candidate, with the voter’s weight as the ballot count.

Parameters:

abc_profile – An abcvoting Profile.
scale_weights (bool, optional) – If True, fractional voter weights are scaled to integers by clearing denominators; otherwise fractional weights raise a ValueError.

Returns:

A GradeProfile with grades 0 and 1.