interregnum.methods.biproportional package

Bi-proportional seats allocation (alternate scaling method).

Consider this implementation as experimental. For a realiable reference implementation, please use Bazi.

References

• [Zachariasen:2006]

• [Pukelsheim:2013]

• [Oelbermann:2016]

---

class interregnum.methods.biproportional.BAPResultData(log=<factory>, rounds=0, transfers=0, party_divisors=<factory>, district_divisors=<factory>)

Bases: EventLog, Generic[PartyName, DistrictName]

Result data for bi-proportional allocations.

Parameters:

• log (list[Event])

• rounds (int)

• transfers (int)

• party_divisors (Sequence[Divisors[PartyName]])

• district_divisors (Sequence[Divisors[DistrictName]])

district_divisors: Sequence[Divisors[DistrictName]]

party_divisors: Sequence[Divisors[PartyName]]

rounds: int = 0

transfers: int = 0

class interregnum.methods.biproportional.BiproportionalAllocator(round_f, nice_quota=True, sort_parties=False)

Bases: Allocator[AnyName, BAPResultData[PartyName, DistrictName]]

Bi-proportional allocator.

Allocates seats based on two proportional allocations: one for parties and one for districts.

See [Zachariasen:2006], [Pukelsheim:2013], [Oelbermann:2016]

allocators collection keys:

• biproportional

• alternate_scaling

• alternate_scaling_tie_transfer

Create a bi-proportional allocator.

round_f

round function with associated signpost sequence

nice_quota

when True, pick a human readable quota from the valid range

sort_parties

Sort parties for the sake of reproducibility.

Parameters:

• round_f (str | RoundingWithSignpost)

• nice_quota (bool)

• sort_parties (bool)

calc(party_seats, district_seats, candidates, exclude_candidates=None, party_name_f=None, district_name_f=None, candidate_name_f=None)

Allocate seats to candidates.

Parameters:

• party_seats (Iterable[tuple[PartyName, int]]) – seats allocated to parties globally

• district_seats (Iterable[tuple[DistrictName, int]]) – seats allocated to districts

• candidates (Iterable[tuple[AnyName, int | Fraction] | tuple[AnyName, int | Fraction, int] | Candidate[AnyName]]) – list of candidates votes with names composed of party and district

• exclude_candidates (Iterable[AnyName] | None) – exclude candidates in this list from winning seats

• party_name_f (Callable[[AnyName], PartyName] | None) – function to extract party names

• district_name_f (Callable[[AnyName], DistrictName] | None) – function to extract district names

• candidate_name_f (Callable[[tuple[PartyName, DistrictName]], AnyName] | None) – function to create a candidate name from party and district

• provided (When no name manipulation function is)

• condidered (candidates are)

• name (to be provided with names composed as tuples (party)

• name). (district)

Return type:

Result[AnyName, BAPResultData[PartyName, DistrictName]]

nice_quota: bool = True

round_f: str | RoundingWithSignpost

sort_parties: bool = False

class interregnum.methods.biproportional.Divisors

Bases: TypedDict, Generic[AnyName]

Divisor range for single-proportional candidate.

divisor: DivisorRange

name: AnyName

interregnum.methods.biproportional.contender2tuple_f(party_f, district_f, contender)

Convert a contender to (party, district).

Parameters:

• party_f (Callable[[AnyName], PartyName])

• district_f (Callable[[AnyName], DistrictName])

• contender (AnyName)

Return type:

tuple[PartyName, DistrictName]

interregnum.methods.biproportional.extract_district_name(contender)

Get district name from a contender.

Parameters:

contender (tuple[Unpack[_Ts], DistrictName])

Return type:

DistrictName

interregnum.methods.biproportional.extract_party_name(contender)

Get party name from a contender.

Parameters:

contender (tuple[PartyName, ...])

Return type:

PartyName

interregnum.methods.biproportional.ident(item)

Return the same.

Parameters:

item (AnyName)

Return type:

AnyName

Submodules

interregnum.methods.biproportional.table module

Auxiliar table for the bi-proportional allocator.

class interregnum.methods.biproportional.table.AbstractTable

Bases: Generic[RowName, ColName]

Definition for a bi-proportional allocator calculation matrix.

__str__()

Return a human-readable representation.

Return type:

str

col_discrepancies(col_seats)

Split cols by under and over apportioned.

Parameters:

col_seats (dict[ColName, int])

Return type:

Tuple[FrozenSet[Vertex], FrozenSet[Vertex]]

discrepancies()

Split rows by under and over apportioed.

Return type:

Tuple[FrozenSet[Vertex], FrozenSet[Vertex]]

iter_rows()

Iterate items by row.

Return type:

Generator[tuple[RowName, VectorSummary, dict[ColName, MatrixCell]], None, None]

original()

Return the original table, without transpositions.

Return type:

AbstractTable[RowName, ColName] | AbstractTable[ColName, RowName]

row_discrepancies(row_seats)

Split rows by under and over apportioned.

Parameters:

row_seats (dict[RowName, int])

Return type:

Tuple[FrozenSet[Vertex], FrozenSet[Vertex]]

seats_by_axis()

Return sums per rows and cols.

Return type:

tuple[dict[RowName, int], dict[ColName, int]]

transpose()

Return a transposed table.

Return type:

AbstractTable[ColName, RowName]

update_share()

Update share for every cell.

Return type:

None

col_data: dict[ColName, VectorSummary]

matrix: TransposableMatrix[RowName, ColName, MatrixCell]

row_data: dict[RowName, VectorSummary]

class interregnum.methods.biproportional.table.DivisorRange(divisor, min_divisor, max_divisor)

Bases: object

A divisor range.

Store a representative divisor, minimum and maximum.

Parameters:

• divisor (int | Fraction)

• min_divisor (int | Fraction | float)

• max_divisor (int | Fraction | float)

nice()

Set divisor as a nice value easy to read.

Return type:

None

divisor: int | Fraction

max_divisor: int | Fraction | float

min_divisor: int | Fraction | float

class interregnum.methods.biproportional.table.MatrixCell(votes=0, seats=0, share=Fraction(0, 1), sign=Discrepancy.EXACT)

Bases: object

A matrix cell with info about votes, seats, share and discrepancies.

Parameters:

• votes (int)

• seats (int)

• share (FScore)

• sign (Discrepancy)

classmethod empty(*_args)

Return an empty cell.

Parameters:

_args (Any)

Return type:

MatrixCell

__str__()

Return a human-readable representation.

Return type:

str

seats

share

sign

votes

class interregnum.methods.biproportional.table.Table(row_seats, col_seats)

Bases: AbstractTable[RowName, ColName]

Transposable table for bi-proportional allocator calculation.

Create a table.

row_seats and col_seats store the two proportional allocations.

Parameters:

• row_seats (dict[RowName, int])

• col_seats (dict[ColName, int])

original()

Return the original matrix, not a transposed one.

Return type:

Table[RowName, ColName]

transpose()

Return a transposed matrix.

Return type:

AbstractTable[ColName, RowName]

col_data: dict[ColName, VectorSummary]

matrix: TransposableMatrix[RowName, ColName, MatrixCell]

row_data: dict[RowName, VectorSummary]

class interregnum.methods.biproportional.table.VectorSummary(seats=0, divisor=None)

Bases: object

Summary for a vector (row or column).

Create a vector summary.

Parameters:

• seats (int) – allocated seats

• divisor (DivisorRange | None) – divisor range

qrange

seats

class interregnum.methods.biproportional.table.Vertex(is_row, index)

Bases: NamedTuple

Row or column element.

Create new instance of Vertex(is_row, index)

Parameters:

• is_row (bool)

• index (Any)

index: Any

Alias for field number 1

is_row: bool

Alias for field number 0

interregnum.methods.biproportional.tally module

Tally computations for bi-proportional allocators.

class interregnum.methods.biproportional.tally.BPTallyBoard(quota_f, method_f, tuple_f, table, _is_row=True)

Bases: Generic[AnyName, PartyName, DistrictName]

Bi-proportional allocator tally board.

Parameters:

• quota_f (interregnum.quotas.QuotaResolver) – a quota resolver

• method_f (interregnum.methods.singlevote.iterative_divisor.IterativeDivisorAllocator[interregnum.methods.biproportional.tally.PartyName] | interregnum.methods.singlevote.iterative_divisor.IterativeDivisorAllocator[interregnum.methods.biproportional.tally.DistrictName]) – a iterative divisor method

• tuple_f (Callable[[interregnum.methods.types.AnyName], tuple[interregnum.methods.biproportional.tally.PartyName, interregnum.methods.biproportional.tally.DistrictName]]) – function that split a candidate name into party and district name

• table (AbstractTable[DistrictName, PartyName] | AbstractTable[PartyName, DistrictName])

• _is_row (bool)

allocate_rows(under, over)

Allocate row candidates and compute discrepancies.

Parameters:

• under (frozenset[Vertex])

• over (frozenset[Vertex])

Return type:

None

exclude(table, candidates=None)

Exclude candidates in this list from winning seats.

Parameters:

• table (AbstractTable[DistrictName, PartyName])

• candidates (Iterable[Candidate[AnyName]] | None)

Return type:

None

find_transfer_paths(initial_labels)

Breadth first search.

Parameters:

initial_labels (Iterable[Vertex])

Return type:

tuple[set[Vertex], dict[Vertex, Vertex]]

reset_table()

Return to the original table.

Return type:

None

transfer(under, vertex_from, predecessor)

Transfer a discrepancy.

Return number of transfers.

Parameters:

• under (frozenset[Vertex])

• vertex_from (Vertex)

• predecessor (dict[Vertex, Vertex])

Return type:

int

transfer_ties()

Transfer ties to other candidates in order to reduce discrepancies.

Return type:

int

transpose_table()

Transpose table.

Return type:

None

method_f: IterativeDivisorAllocator[PartyName] | IterativeDivisorAllocator[DistrictName]

quota_f: QuotaResolver

table: AbstractTable[DistrictName, PartyName] | AbstractTable[PartyName, DistrictName]

tuple_f: Callable[[AnyName], tuple[PartyName, DistrictName]]