Rename parcels_by_value to by_value and update documentation

docs/options.md

@@ -84,6 +84,7 @@ Other surplus transfer methods, such as non-fractional transfers (e.g. random sa
 
 * 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.
 
 ## Ties (-t/--ties)
 

html/index.html

@@ -119,7 +119,8 @@
 				<select id="selExclusion">
 					<option value="one_round" selected>Exclude in one round</option>
 					<option value="parcels_by_order">Exclude by parcel (by order)</option>
-					<option value="parcels_by_value">Exclude by parcel (by value)</option>
+					<!--<option value="parcels_by_value">Exclude by parcel (by value)</option>-->
+					<option value="by_value">Exclude by value</option>
 				</select>
 			</label>
 			<br>

html/index.js

@@ -63,7 +63,7 @@ function changePreset() {
 		document.getElementById('selSurplus').value = 'order';
 		document.getElementById('selTransfers').value = 'uig';
 		document.getElementById('selPapers').value = 'both';
-		document.getElementById('selExclusion').value = 'parcels_by_value';
+		document.getElementById('selExclusion').value = 'by_value';
 		document.getElementById('selTies').value = 'backwards_random';
 	} else if (document.getElementById('selPreset').value === 'wright') {
 		document.getElementById('selQuotaCriterion').value = 'geq';

pyRCV2/cli/stv.py

@@ -37,7 +37,7 @@ def add_parser(subparsers):
 	parser.add_argument('--surplus-order', '-s', choices=['size', 'order'], default='size', help='whether to distribute surpluses by size or by order of election (default: size)')
 	parser.add_argument('--method', '-m', choices=['wig', 'uig', 'eg', 'wright'], default='wig', help='method of surpluses and exclusions (default: wig - weighted inclusive Gregory)')
 	parser.add_argument('--transferable-only', action='store_true', help='examine only transferable papers during surplus distributions')
-	parser.add_argument('--exclusion', choices=['one_round', 'parcels_by_order', 'parcels_by_value'], default='one_round', help='whether to perform exclusions in one round or parcel by parcel (default: one_round)')
+	parser.add_argument('--exclusion', choices=['one_round', 'parcels_by_order', 'by_value'], default='one_round', help='whether to perform exclusions in one round or parcel by parcel (default: one_round)')
 	parser.add_argument('--ties', '-t', action='append', choices=['backwards', 'prompt', 'random'], default=None, help='how to resolve ties (default: backwards then random)')
 	parser.add_argument('--random-seed', default=None, help='arbitrary string used to seed the RNG for random tie breaking')
 

pyRCV2/method/base_stv.py

@@ -43,7 +43,7 @@ class BaseSTVCounter:
 			'quota_criterion': 'geq', # 'geq' or 'gt'
 			'surplus_order': 'size',  # 'size' or 'order'
 			'papers': 'both',         # 'both' or 'transferable'
-			'exclusion': 'one_round', # 'one_round', 'parcels_by_order' or 'parcels_by_value'
+			'exclusion': 'one_round', # 'one_round', 'parcels_by_order' or 'by_value'
 			'ties': []
 		}
 		
@@ -548,8 +548,8 @@ class WIGSTVCounter(BaseSTVCounter):
 				# TODO: Skip this entirely if this is the case
 				parcel = []
 			count_card.parcels.remove(parcel)
-		elif self.options['exclusion'] == 'parcels_by_value':
+		elif self.options['exclusion'] == 'by_value':
-			# Sort the parcels by value
+			# Sort the ballots by value
 			ballots = [(b, bv) for p in count_card.parcels for b, bv in p]
 			__pragma__('opov')
 			ballots.sort(key=lambda x: x[1] / x[0].value.to_rational(), reverse=True)

tests/test_aec.py

@@ -42,7 +42,7 @@ def test_aec_tas19():
 	
 	counter = UIGSTVCounter(election, {
 		'surplus_order': 'order',
-		'exclusion': 'parcels_by_value'
+		'exclusion': 'by_value'
 	})
 	result = counter.reset()