abcvoting.properties

Axiomatic properties of committees.

Expand for references to abcvoting.properties

Properties of committees

abcvoting.properties.check(property_name, profile, committee, quota=None, algorithm='fastest')

Test whether a committee satisfies a given property.

Parameters:

property_namestr

Name of a property.

profileabcvoting.preferences.Profile

A profile.

committeeiterable of int

A committee.

quotaFraction or float, optional

The quota, i.e., size of a group, to deserve one committee member.

Does apply only to some axiomatic properties. If the chosen property does not use a quota and quota is set to a value, check() raises a ValueError.

algorithmstr, optional

The algorithm to be used.

Returns:

bool

abcvoting.properties.check_EJR(profile, committee, quota=None, algorithm='fastest')

Test whether a committee satisfies Extended Justified Representation (EJR).

Parameters:

profileabcvoting.preferences.Profile

A profile.

committeeiterable of int

A committee.

quotaFraction or float, optional

The quota, i.e., size of a group, to deserve one committee member.

Defaults to n/k, i.e., the number of voters divided by the committee size.

algorithmstr, optional

The algorithm to be used.

Returns:

bool

References

Aziz, H., Brill, M., Conitzer, V., Elkind, E., Freeman, R., & Walsh, T. (2017). Justified representation in approval-based committee voting. Social Choice and Welfare, 48(2), 461-485. https://arxiv.org/abs/1407.8269

Examples

>>> from abcvoting.preferences import Profile
>>> from abcvoting.output import output, DETAILS

>>> profile = Profile(4)
>>> profile.add_voters([[0, 1], [0, 1], [0, 1], [0, 1], [2, 3], [2, 3]])
>>> print(profile)
profile with 6 voters and 4 candidates:
 voter 0:   {0, 1},
 voter 1:   {0, 1},
 voter 2:   {0, 1},
 voter 3:   {0, 1},
 voter 4:   {2, 3},
 voter 5:   {2, 3}

>>> output.set_verbosity(DETAILS)  # enable output for check_EJR
>>> result = check_EJR(profile, committee={0, 2, 3})
Committee {0, 2, 3} does not satisfy EJR.
 (The 2-cohesive group of voters {0, 1, 2, 3} (66.7% of all voters)
 jointly approve the candidates {0, 1}, but none of them approves 2
 candidates in the committee.)

>>> result = check_EJR(profile, committee={0, 1, 2})
Committee {0, 1, 2} satisfies EJR.

abcvoting.properties.check_EJR_plus(profile, committee, quota=None)

Test whether a committee satisfies EJR+.

Parameters:

profileabcvoting.preferences.Profile

A profile.

committeeiterable of int

A committee.

quotaFraction or float, optional

The quota, i.e., size of a group, to deserve one committee member.

Defaults to n/k, i.e., the number of voters divided by the committee size.

Returns:

bool

References

Brill, M., & Peters, J. (2023). Robust and Verifiable Proportionality Axioms for Multiwinner Voting. https://arxiv.org/abs/2302.01989

abcvoting.properties.check_FJR(profile, committee, quota=None, algorithm='fastest')

Test whether a committee satisfies Full Justified Representation (FJR).

Parameters:

profileabcvoting.preferences.Profile

A profile.

committeeiterable of int

A committee.

quotaFraction or float, optional

The quota, i.e., size of a group, to deserve one committee member.

Defaults to n/k, i.e., the number of voters divided by the committee size.

algorithmstr, optional

The algorithm to be used.

Returns:

bool

References

Multi-Winner Voting with Approval Preferences. Martin Lackner and Piotr Skowron. <http://dx.doi.org/10.1007/978-3-031-09016-5>

abcvoting.properties.check_JR(profile, committee, quota=None)

Test whether a committee satisfies Justified Representation (JR).

Parameters:

profileabcvoting.preferences.Profile

A profile.

committeeiterable of int

A committee.

quotaFraction or float, optional

The quota, i.e., size of a group, to deserve one committee member.

Defaults to n/k, i.e., the number of voters divided by the committee size.

Returns:

bool

References

Aziz, H., Brill, M., Conitzer, V., Elkind, E., Freeman, R., & Walsh, T. (2017). Justified representation in approval-based committee voting. Social Choice and Welfare, 48(2), 461-485. https://arxiv.org/abs/1407.8269

Examples

>>> from abcvoting.preferences import Profile
>>> from abcvoting.output import output, DETAILS

>>> profile = Profile(4)
>>> profile.add_voters([[0, 1, 2], [0, 1, 2], [0, 1, 2], [0, 1, 2], [3], [3]])
>>> print(profile)
profile with 6 voters and 4 candidates:
 voter 0:   {0, 1, 2},
 voter 1:   {0, 1, 2},
 voter 2:   {0, 1, 2},
 voter 3:   {0, 1, 2},
 voter 4:   {3},
 voter 5:   {3}

>>> output.set_verbosity(DETAILS)  # enable output for check_JR
>>> result = check_JR(profile, committee={0, 1, 2})
Committee {0, 1, 2} does not satisfy JR.
(The 1-cohesive group of voters {4, 5} (33.3% of all voters) jointly
approve candidate 3, but none of them approve a candidate in the
committee.)

>>> result = check_JR(profile, committee={1, 2, 3})
Committee {1, 2, 3} satisfies JR.

abcvoting.properties.check_PJR(profile, committee, quota=None, algorithm='fastest')

Test whether a committee satisfies Proportional Justified Representation (PJR).

Parameters:

profileabcvoting.preferences.Profile

A profile.

committeeiterable of int

A committee.

quotaFraction or float, optional

The quota, i.e., size of a group, to deserve one committee member.

Defaults to n/k, i.e., the number of voters divided by the committee size.

algorithmstr, optional

The algorithm to be used.

Returns:

bool

References

Sánchez-Fernández, L., Elkind, E., Lackner, M., Fernández, N., Fisteus, J., Val, P. B., & Skowron, P. (2017). Proportional justified representation. In Proceedings of the AAAI Conference on Artificial Intelligence (Vol. 31, No. 1). https://arxiv.org/abs/1611.09928

Examples

>>> from abcvoting.preferences import Profile
>>> from abcvoting.output import output, DETAILS

>>> profile = Profile(4)
>>> profile.add_voters([[0, 1], [0, 1], [0, 1], [0, 1], [2, 3], [2, 3]])
>>> print(profile)
profile with 6 voters and 4 candidates:
 voter 0:   {0, 1},
 voter 1:   {0, 1},
 voter 2:   {0, 1},
 voter 3:   {0, 1},
 voter 4:   {2, 3},
 voter 5:   {2, 3}

>>> output.set_verbosity(DETAILS)  # enable output for check_PJR
>>> result = check_PJR(profile, committee={0, 2, 3})
Committee {0, 2, 3} does not satisfy PJR.
(The 2-cohesive group of voters {0, 1, 2, 3} (66.7% of all voters)
jointly approve the candidates {0, 1}, but they approve fewer than 2
candidates in the committee.)

>>> result = check_PJR(profile, committee={0, 1, 2})
Committee {0, 1, 2} satisfies PJR.

abcvoting.properties.check_core(profile, committee, quota=None, algorithm='fastest')

Test whether a committee is in the core.

Parameters:

profileabcvoting.preferences.Profile

A profile.

committeeiterable of int

A committee.

quotaFraction or float, optional

The quota, i.e., size of a group, to deserve one committee member.

Defaults to n/k, i.e., the number of voters divided by the committee size.

algorithmstr, optional

The algorithm to be used.

Returns:

bool

References

Multi-Winner Voting with Approval Preferences. Martin Lackner and Piotr Skowron. <http://dx.doi.org/10.1007/978-3-031-09016-5>

abcvoting.properties.check_pareto_optimality(profile, committee, algorithm='fastest')

Test whether a committee satisfies Pareto optimality.

Parameters:

profileabcvoting.preferences.Profile: A profile.
committeeiterable of int: A committee.
algorithmstr, optional: The algorithm to be used.

Returns:

bool

References

Multi-Winner Voting with Approval Preferences. Martin Lackner and Piotr Skowron. <http://dx.doi.org/10.1007/978-3-031-09016-5>

Examples

>>> from abcvoting.preferences import Profile
>>> from abcvoting.output import output, DETAILS

>>> profile = Profile(3)
>>> profile.add_voters([[0], [0, 2], [1, 2], [1, 2]])
>>> print(profile)
profile with 4 voters and 3 candidates:
 voter 0:   {0},
 voter 1:   {0, 2},
 voter 2:   {1, 2},
 voter 3:   {1, 2}

>>> output.set_verbosity(DETAILS)  # enable output for check_pareto_optimality
>>> result = check_pareto_optimality(profile, committee={0, 1})
Committee {0, 1} is not Pareto optimal.
(It is dominated by the committee {0, 2}.)
>>> result = check_pareto_optimality(profile, committee={0, 2})
Committee {0, 2} is Pareto optimal.

We see that the committee {0, 2} is Pareto optimal, but not the committee {0, 1}.

abcvoting.properties.check_priceability(profile, committee, algorithm='fastest', stable=False)

Test whether a committee satisfies Priceability.

Parameters:

profileabcvoting.preferences.Profile: A profile.
committeeiterable of int: A committee.
algorithmstr, optional: The algorithm to be used.
stablebool, default=False: Whether to check for stable priceability.

Returns:

bool

References

Multi-Winner Voting with Approval Preferences. Martin Lackner and Piotr Skowron. <http://dx.doi.org/10.1007/978-3-031-09016-5>

abcvoting.properties.check_stable_priceability(profile, committee, algorithm='fastest')

Test whether a committee satisfies stable Priceability.

Parameters:

profileabcvoting.preferences.Profile: A profile.
committeeiterable of int: A committee.
algorithmstr, optional: The algorithm to be used.

Returns:

bool

References

Multi-Winner Voting with Approval Preferences. Martin Lackner and Piotr Skowron. <http://dx.doi.org/10.1007/978-3-031-09016-5>

abcvoting.properties.full_analysis(profile, committee)

Test all implemented properties for the given committee.

Returns a dictionary with the following keys: “pareto”, “jr”, “pjr”, “ejr”, “ejr+”, “fjr”, “priceability”, “stable-priceability” and “core”. The values are True or False, depending on whether this property is satisfied.

Parameters:

profileabcvoting.preferences.Profile: A profile.
committeeiterable of int: A committee.

Returns:

dict

Expand for references to abcvoting.properties.full_analysis

Properties of committees