RunasSudo
/
pyRCV2
Archived
1
Fork 0
Code Issues Pull Requests Activity

Update documentation

This commit is contained in:
RunasSudo 2021-01-04 17:51:24 +11:00
parent fb33a96d37
commit 6f5cf70abb
Signed by: RunasSudo
GPG Key ID: 7234E476BF21C61A
2 changed files with 76 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -14,8 +14,8 @@ pyRCV2 accepts data in the [BLT file format](http://www.dia.govt.nz/diawebsite.N
* weighted inclusive Gregory STV (e.g. [Scottish STV](https://www.opavote.com/methods/scottish-stv-rules))
* unweighted inclusive Gregory STV (e.g. [Australian Senate STV](https://www.legislation.gov.au/Details/C2020C00400/Html/Text#_Toc59107700))
* exclusive Gregory STV (e.g. [PRSA 1977](https://www.prsa.org.au/rule1977.htm) and [ERS97](https://www.electoral-reform.org.uk/latest-news-and-research/publications/how-to-conduct-an-election-by-the-single-transferable-vote-3rd-edition/))
* [Wright STV](https://www.aph.gov.au/Parliamentary_Business/Committees/House_of_Representatives_Committees?url=em/elect07/subs/sub051.1.pdf)
* exclusive Gregory STV (e.g. [PRSA 1977](https://www.prsa.org.au/rule1977.htm))
pyRCV2 is highly customisable, including options for:

126
docs/options.md
View File

@ -8,95 +8,119 @@ The preset dropdown allows you to choose from a hardcoded list of preloaded STV
* [Australian Senate STV](https://www.legislation.gov.au/Details/C2020C00400/Html/Text#_Toc59107700)
* [Wright STV](https://www.aph.gov.au/Parliamentary_Business/Committees/House_of_Representatives_Committees?url=em/elect07/subs/sub051.1.pdf)
* [PRSA 1977](https://www.prsa.org.au/rule1977.htm)
* [ERS97](https://www.electoral-reform.org.uk/latest-news-and-research/publications/how-to-conduct-an-election-by-the-single-transferable-vote-3rd-edition/)
This functionality is not available on the Python command line.
## Quota (-q/--quota, -c/--quota-criterion)
The quota dropdowns allow you to define the quota used in the election, and the quota criterion used to elect candidates. The quota may be set to:
* Droop: ⌊*V*/(*S*+1)⌋ + 1
* Droop (exact): *V*/(*S*+1) (also known as the Newland-Britton or Hagenbach-Bischoff quota)
* Hare: *V*/*S*
* Hare (exact): ⌊*V*/*S*⌋ + 1
where *V* is the number of votes, *S* is the number of seats and ⌊…⌋ denotes the floor function (round down to the nearest integer, discarding any remainder).
The quota criterion may be set to >= (candidates are elected if they meet or exceed the quota) or > (candidates are elected only if they strictly exceed the quota).
Note that the combination ‘>= Droop (exact)’ can result in more candidates meeting the quota than there are available vacancies, hence this particular combination is not recommended.
The default is ‘>= Droop’, which is the most common STV quota, but we recommend ‘> Droop (exact)’ as this prevents the quota being unnecessarily large when fractional surplus distribution methods (as in pyRCV2) are used.
## Progressive quota (--prog-quota)
When this option is disabled (default), the quota is calculated once after all first-preference votes are allocated, and remains constant throughout the count. [OpaVote](https://www.opavote.com/help/online-counts) calls this a ‘static threshold’.
When this option is enabled, the quota is recalculated at the end of every stage, and may decrease throughout the count as votes are exhausted. OpaVote calls this a ‘dynamic threshold’.
## Bulk election (--no-bulk-election)
When bulk election is enabled (default), all remaining candidates are declared elected in a single round once the number of not-excluded candidates exactly equals the number of vacancies to fill. Further surplus distributions are not performed. This is typical of most STV rules.
When bulk election is disabled, surpluses continue to be distributed even once the number of not-excluded candidates exactly equals the number of vacancies to fill. Once there are no more surpluses to distribute, the candidates are declared elected, one by one, in descending order of votes. This ensures that only one candidate is ever elected in each round and the order of election is well-defined, which is required e.g. for some affirmative action rules.
## Numbers (-n/--numbers), Decimal places (--decimals)
This dropdown allows you to select how numbers (vote totals, etc.) are represented internally in memory. The options are:
* Fixed: Numbers are represented as fixed-precision decimals, up to a certain number of decimal places (default: 5).
* Rational: Numbers are represented exactly as fractions, resulting in the elimination of rounding error, but increasing computational complexity when the number of surplus transfers is very large.
* Native: Numbers are represented as native integers or floating-point numbers. This is fast, but not recommended as unexpectedly large rounding errors may be introduced in some circumstances.
* *Fixed*: Numbers are represented as fixed-precision decimals, up to a certain number of decimal places (default: 5).
* *Rational*: Numbers are represented exactly as fractions, resulting in the elimination of rounding error, but increasing computational complexity when the number of surplus transfers is very large.
* *Native*: Numbers are represented as native integers or floating-point numbers. This is fast, but not recommended as unexpectedly large rounding errors may be introduced in some circumstances.
### Round votes/ballot weights to [n] d.p. (--round-votes, --round-weights)
## Quota-related options
When rounding is enabled, the votes credited to candidates during surplus transfers and exclusions, and/or the weights of the ballot papers, are rounded to the specified number of decimal places.
### Quota (-q/--quota)
This enables, for example, votes to be counted only in integers, while ballot weights and transfer values are calculated to higher precision (according to the Numbers) option.
The quota dropdowns allow you to define the quota used in the election, and the quota criterion used to elect candidates. The quota may be set to:
* *Droop* and *Droop (exact)*: *V*/(*S*+1)
* *Hare* and *Hare (exact)*: *V*/*S*
where *V* is the number of votes and *S* is the number of seats.
The ‘*(exact)*’ version of each quota has effect only if *Round quota to [n] d.p.* is enabled. When that setting is enabled, *Droop* and *Hare* will increment the quota up to the next available rounded unit (even if the quotient is exact already), while the ‘*(exact)*’ versions will round the quota up if and only if the quotient is not already exact.
When *Round quota to [n] d.p.* is not enabled, *Droop* (or *Droop (exact)*) is also known as the Newland-Britton or Hagenbach-Bischoff quota.
### Quota criterion (-c/--quota-criterion)
The quota criterion may be set to *>=* (candidates are elected if they meet or exceed the quota) or *>* (candidates are elected only if they strictly exceed the quota).
Note that the combination ‘*>= Droop (exact)*’ (with *Round quota to [n] d.p.* enabled) can result in more candidates meeting the quota than there are available vacancies, hence this particular combination is not recommended.
The default is ‘*>= Droop*’, which is the most common STV quota, but we recommend ‘*> Droop (exact)*’ as this prevents the quota being unnecessarily large when fractional surplus distribution methods (as in pyRCV2) are used.
### Quota mode (--quota-mode)
This option allows you to specify whether the votes required for election can change during the count. The options are:
* *Static quota*: The quota is calculated once after all first-preference votes are allocated, and remains constant throughout the count. [OpaVote](https://www.opavote.com/help/online-counts) calls this a ‘static threshold’.
* *Progressive quota*: The quota is recalculated at the end of every stage, and may decrease throughout the count as votes are exhausted. OpaVote calls this a ‘dynamic threshold’.
* *Static with ERS97 rules*: The quota is static, but candidates may be elected if their vote exceeds (or equals, according to the *Quota criterion*) the total active vote, divided by (*S* + 1) (or *S*, according to the *Quota* option).
## Bulk election (--no-bulk-elect)
When bulk election is enabled (default), all remaining candidates are declared elected in a single stage once the number of not-excluded candidates exactly equals the number of vacancies to fill. Further surplus distributions are not performed. This is typical of most STV rules.
When bulk election is disabled, surpluses continue to be distributed even once the number of not-excluded candidates exactly equals the number of vacancies to fill. Once there are no more surpluses to distribute, the candidates are declared elected, one by one, in descending order of votes. This ensures that only one candidate is ever elected in each round and the order of election is well-defined, which is required e.g. for some affirmative action rules.
## Bulk exclusion (--bulk-exclude)
When bulk exclusion is disabled (default), only one candidate is ever excluded per stage.
When bulk exclusion is enabled, as many candidates are excluded as possible at once per stage, provided that sufficient candidates remain to fill the vacancies, and the bulk exclusion could not change the order of exclusion. If 2 or more candidates are tied, either all are bulk excluded or none are. The ballot papers of all excluded candidates are considered together, and transferred according to the *Exclusion method*.
## Defer surpluses (--defer-surpluses)
When deferred surpluses is disabled (default), all surpluses must be transferred before candidates can be excluded.
When deferred surpluses is enabled, the transfer of all surpluses is deferred if doing so could not change the order of exclusion (including of a bulk exclusion, if that is enabled).
## Round quota/votes/transfer values/ballot weights to [n] d.p. (--round-quota, --round-votes, --round-tvs, --round-weights)
When rounding is enabled, the specified values are rounded to the specified number of decimal places. This enables, for example, votes to be counted only in integers, while ballot weights and transfer values are calculated to higher precision (according to the *Numbers*) option.
In relation to *Round transfer values to [n] d.p.* specifically:
* When this option is disabled (default), the numerator of the transfer value is multiplied by the applicable multiplicand before being divided by the denominator of the transfer value. For example, in the weighted inclusive Gregory method with non-transferable papers included, to determine the number of votes to transfer to a candidate, the surplus is multiplied by the number of votes for that candidate, before being divided by the total votes of the transferring candidate. This minimises rounding errors.
* When this option is enabled, the transfer value is calculated separately and rounded to the specified precision, before being multiplied by the applicable multiplicand.
## Surplus order (-s/--surplus-order)
This dropdown allows you to select in what order surpluses are distributed:
* By size (default): When multiple candidates exceed the quota, the largest surplus is transferred (even if it arose at a later stage of the count).
* By order: When multiple candidates exceed the quota, the surplus of the candidate elected first is transferred (even if it is smaller than another). Candidates are always declared elected in descending order of number of votes.
* *By size* (default): When multiple candidates exceed the quota, the largest surplus is transferred (even if it arose at a later stage of the count).
* *By order*: When multiple candidates exceed the quota, the surplus of the candidate elected first is transferred (even if it is smaller than another). Candidates are always declared elected in descending order of number of votes.
Some STV counting rules provide, for example, that ‘no surplus shall be transferred before a surplus that arose earlier in the counting whether larger or not’ (PRSA 1977). In this case, the option ‘By order’ should be selected.
Some STV counting rules provide, for example, that ‘no surplus shall be transferred before a surplus that arose earlier in the counting whether larger or not’ (PRSA 1977). In this case, the option ‘*By order*’ should be selected.
## Method (-m/--method)
This dropdown allows you to select how ballots are transferred during surplus transfers or exclusions. The recommended method is:
* Weighted inclusive Gregory: During surplus transfers, all applicable ballot papers of the transferring candidate are examined. Transfers are weighted according to the weights of the ballot papers.
* *Weighted inclusive Gregory* (default): During surplus transfers, all applicable ballot papers of the transferring candidate are examined. Transfers are weighted according to the weights of the ballot papers.
Other methods are supported, but not recommended:
* Unweighted inclusive Gregory: During surplus transfers, all applicable ballot papers of the transferring candidate are examined. Transfers are not weighted, and each ballot paper has equal value in the calculation.
* Exclusive Gregory (last bundle): During surplus transfers, only the ballot papers received in the last transfer are examined. Transfers are not weighted.
* *Unweighted inclusive Gregory*: During surplus transfers, all applicable ballot papers of the transferring candidate are examined. Transfers are not weighted, and each ballot paper has equal value in the calculation.
* *Exclusive Gregory (last bundle)*: During surplus transfers, only the ballot papers received in the last transfer are examined. Transfers are not weighted.
Other surplus transfer methods, such as non-fractional transfers (e.g. random sample) are not supported at this time.
### Papers to examine in surplus transfer (--transferable-only)
* Include non-transferable papers (default): When this option is selected, all ballot papers of the transferring candidate are examined. Non-transferable papers are always exhausted at the relevant transfer values.
* Use transferable papers only (CLI: --transferable-only): When this option is selected, only transferable papers of the transferring candidate are examined. Non-transferable papers are exhausted only if the value of the transferable papers is less than the surplus.
* *Include non-transferable papers* (default): When this option is selected, all ballot papers of the transferring candidate are examined. Non-transferable papers are always exhausted at the relevant transfer values.
* *Use transferable papers only* (CLI: --transferable-only): When this option is selected, only transferable papers of the transferring candidate are examined. Non-transferable papers are exhausted only if the value of the transferable papers is less than the surplus.
### Exclusion method (--exclusion)
* Exclude in one round (default): When excluding a candidate, transfer all their ballot papers in one round.
* Exclude by parcel (by order): When excluding a candidate, transfer their ballot papers one parcel at a time, in their order each was received. Each parcel forms a separate round, i.e. if a transfer allows another candidate to meet the quota criterion, no further papers are transferred to that candidate.
* Exclude by value: When excluding a candidate, transfer their ballot papers in descending order of accumulated transfer value. Each transfer of all ballots of a certain transfer value forms a separate round.
* Wright method (re-iterate): When a candidate is excluded, the count is reset from the beginning (minus the excluded candidate).
* *Exclude in one round* (default): When excluding candidate(s), transfer all their ballot papers in one stage.
* *Exclude by parcel (by order)*: When excluding a candidate, transfer their ballot papers one parcel at a time, in their order each was received. Each parcel forms a separate stage, i.e. if a transfer allows another candidate to meet the quota criterion, no further papers are transferred to that candidate. This option cannot be combined with bulk exclusion.
* *Exclude by value*: When excluding candidate(s), transfer their ballot papers in descending order of accumulated transfer value. Each transfer of all ballots of a certain transfer value forms a separate stage.
* *Wright method (re-iterate)*: When candidate(s) are excluded, the count is reset from the beginning (minus the excluded candidate(s)).
## Ties (-t/--ties)
This dropdown allows you to select how ties (in surplus transfer or exclusion) are broken. The options are:
* Backwards: Ties are broken according to which tied candidate had the most/fewest votes at the end of the last stage where one tied candidate had more/fewer votes than the others, if such a stage exists.
* Random: Ties are broken at random (see *Random seed*).
* Prompt: The user is prompted to break the tie.
* *Backwards*: Ties are broken according to which tied candidate had the most/fewest votes at the end of the last stage where one tied candidate had more/fewer votes than the others, if such a stage exists.
* *Random*: Ties are broken at random (see *Random seed*).
* *Prompt*: The user is prompted to break the tie.
Multiple tie breaking methods can be specified. If the first method cannot resolve the tie, the next is tried, and so on. In the web application, 2 options are available (‘Backwards then random’ and ‘Random’). On the Python command line, the `--ties` option can be specified multiple times (e.g. `--ties backwards --ties random`).
Multiple tie breaking methods can be specified. If the first method cannot resolve the tie, the next is tried, and so on. In the web application, 2 options are available (‘*Backwards then random*’ and ‘*Random*’). On the Python command line, the `--ties` option can be specified multiple times (e.g. `--ties backwards --ties random`).
## Random seed (--random-seed)