Updated readme for algorithm changes and to link to the ElectoWiki page
1 files changed, 38 insertions(+), 57 deletions(-)

M README.md
M README.md +38 -57
@@ 1,15 1,18 @@ 
-score-better-balance
-====================
+MARS (Mixed Absolute Relative Score)
+====================================
 
-[![SBB build status](https://builds.sr.ht/~ser/score-better-balance.svg)](https://builds.sr.ht/~ser/score-better-balance?)
+[![MARS build status](https://builds.sr.ht/~ser/MARS.svg)](https://builds.sr.ht/~ser/MARS?)
 
 This is a simple implementation of a post on r/EndTPTP. The poposal suggested
-a modification of STAR to address some percieved deficiences.
+a modification of STAR to address some percieved deficiences. The proposal is
+described in detail on the [MARS voting ElectoWiki page](https://electowiki.org/wiki/MARS_voting).
 
 In this repository is an implementation of the proposal, plus two sets of
 input data to test it with.
 
-Binaries are available from https://downloads.ser1.net/software/ (note the trailing slash).  Binaries are signed with my public key, 7ABD6668FDD1 (which is available from public keyservers).
+Binaries are available from https://downloads.ser1.net/software/ (note
+the trailing slash).  Binaries are signed with my public key, 7ABD6668FDD1
+(which is available from public keyservers).
 
 Example
 -------

          
@@ 53,31 56,46 @@ Totals
 Highest combined total: C with 44
 ```
 
+Other data sets can be downloaded from the repository; they're
+simple CSV files. The first line is the list of candidates,
+e.g. "Zippy,Zaphod,Mr. Toad,Y. Cornelius", and following lines are score
+votes for each candidate (one vote per line). Min/max score values are taken
+from the scores (max is the max score seen in the file; min is the smallest;
+the range is max-min).
+
+
 Running
 -------
 
-You need [go](https://golang.org) installed.  You can either `go get` to build a binary or
-`go run` the project.
+Binaries are available from https://downloads.ser1.net/software/ (note 
+the trailing slash), or you can review the code and build (and run it)
+yourself. The entire program is one file with no external dependencies and
+327 lines of code.
+
+To build (or run the source) you need [go](https://golang.org).  You can
+either `go get` to build a binary or `go run` the project.
 
 ```
-go get hg.sr.ht/~ser/score-better-balance
+go get hg.sr.ht/~ser/MARS
 ```
 
-You'll get a program called `sbb` in your `$GOPATH/bin`, usually
+You'll get a program called `MARS` in your `$GOPATH/bin`, usually
 `~/go/bin`. Alternatively, check out the repository and run it on the
 command line:
 
 ```
-hg clone https://hg.sr.ht/~ser/score-better-balance
-cd score-better-balance
+hg clone https://hg.sr.ht/~ser/MARS
+cd MARS
 go run . < input-1.csv
 ```
 
-There are no arguments. It reads data from the command line, and the data
-it expects is CSV with one vote per line and no header.  For example, two
-people voting between three candidates would have two lines:
+The program takes no arguments and reads data from the command line.
+The data file is described above and sample data sets can be downloaded
+from the repository. For example, two people voting between three candidates
+would have three lines:
 
 ```
+Candidate A,Candidate B,Candidate C
 5,4,0
 4,1,5
 ```

          
@@ 85,8 103,9 @@ 4,1,5
 Voter 1 scores candidate A 5, candidate B 4, and candidate C 0. Voter 2
 scored A 4, B 1, and C 5.
 
-Two data files are included, both examples from the comments. `input-1.csv`
-is the base case; `input-2.csv` differs only in a single vote.
+In the repository data sets, `input-X.csv` is a base set; `input-X.Y.csv`
+is a mutation of the data set, usually by a single vote, to demonstrate how
+a vote change affects the outcomes.
 
 
 Proposal

          
@@ 94,44 113,6 @@ Proposal
 
 The original post was made by [u/jan_kasimir on 2020-02-13](https://www.reddit.com/r/EndFPTP/comments/lil4zz/scorebetterbalance_a_proposal_to_fix_some/).
 
-> On top of score, STAR voting adds an incentive to differentiate between
-> candidates, so that it does not reduce to approval voting. However in
-> doing so it adds two problems.
-> 
-> 1. The runoff part is not clone proof. If the score winner runs a clone
->    candidate, then all of STARs incentive falls apart. It can also lead to
->    some strange cases where one could vote tactically to get your second
->    favorite into the runoff (instead of your favorite) because they are more
->    likely to beat the other candidate you like less.
-> 
-> 2. The runoff step is purely majoritarian. One great thing about score is
->    that it can find a candidate that most voters are okay with, outside of
->    two conflicting camps.
-> 
-> ...
-> 
-> Still I think it's only slightly more complicated than STAR and still
-> with only one recount of the ballots. In a way, it does the runoff step
-> backwards. The working name is **score-better-balance**, after the three
-> steps it uses.
-> 
-> 1. Step one: **score** each candidate on a scale 0 to 5. Pick the candidate
->    with the highest score (in the following called "A").
-> 2. Recount the ballots. Give one point to each candidate that's rated
->    **better** than A. This gives a list of candidates that would beat A in
->    a head to head runoff ("B").
-> 3. To determine the winner use a combination of score and preference. For
->    each Bn calculate the difference in votes (V) of A and B and subtract the
->    difference in score > (S) to A, divided by maximum score (r). V(BA)-V(AB)
->    - (S(A)-S(B))/r. If any of B has a positive **balance**, the biggest
->    balance wins, otherwise A wins.
-
-u/Drachefly offered a [simplified description](https://www.reddit.com/r/EndFPTP/comments/lil4zz/scorebetterbalance_a_proposal_to_fix_some/gnbm240?utm_source=share&utm_medium=web2x&context=3).
-
-> I think the easier way to understand the formula is to multiply by r (the range). Then the method turns into:
-> 
-> 1. get the score leader
-> 2. alter every ballot to give everyone above the score leader +r points
->    and everyone below the score leader -r points (allowing going out of
->    normal range)
-> 3. new high score wins.
+As the system has evolved, I'm removing the history from this README; see
+either the Reddit discussion or the
+[ElectoWiki](https://electowiki.org/wiki/MARS_voting) page for details.