What's Schulze.js

Schulze.js is an open source ^{MIT License} JS implementation of the electoral system Schulze method, which is one of the Condorcet election method that elects the candidate that would win a majority of the vote in all of the head-to-head elections against each of the other candidates, whenever there is such a candidate.

Install

Schulze.js is available both for browser or Node.js.

Browser

Simply download schulze.js or schulze.min.js from github and include it in your html:

Node.js

First install this module:

npm install --save zbryikt/schulze.js

Then, require it in your script:

require("schulze.js")

Usage

Say you have a form of scores for candidates provided by different judges looking like this:

And it's stored in either CSV format or a 2D Array:

CSV

"Candidates", "John", "Joe", "David", "Mary"
"Cand 1", 90, 60, 80, 70
"Cand 2", 80, 50, 70, 60
"Cand 3", 70, 40, 60, 50
"Cand 4", 60, '', 50, 40
"Cand 5", 50, 20, '', 30

Array

[ ["Candidates", "John", "Joe", "David", "Mary"],
  ["Cand 1", 90, 60, 80, 70],
  ["Cand 2", 80, 50, 70, 60],
  ["Cand 3", 70, 40, 60, 50],
  ["Cand 4", 60, '', 50, 40],
  ["Cand 5", 50, 20, '', 30] ]

You can calculate the rank with Schulze method by passing the data into following functions:

ret = schulze.fromCsv(data, config);    /* from CSV */
ret = schulze.fromArray(data, config);  /* from Array */

the returned value is an object with two members rank and detail:

rank

list of objects for each candidates. Each object contains following fields

idx - original index in data
count - count of winning vote against others
rank - rank in all candidates
name - name of candidate

[
  { idx: 0, count: 4, rank: 1, name: "Candidate 1" },
  { idx: 1, count: 3, rank: 2, name: "Candidate 2" },
  { idx: 2, count: 2, rank: 3, name: "Candidate 3" },
  { idx: 3, count: 1, rank: 4, name: "Candidate 4" },
  { idx: 4, count: 0, rank: 5, name: "Candidate 5" }
]

detail

count of winning votes for every candidate against other candidates.

1st value - candidate rank
2nd value - candidate name
other values - winning vote count against others.

[
  [ 1, "Candidate 1", 0, 4, 4, 4, 4 ],
  [ 2, "Candidate 2", 0, 0, 4, 4, 4 ],
  [ 3, "Candidate 3", 0, 0, 0, 4, 4 ],
  [ 4, "Candidate 4", 0, 0, 0, 0, 3 ],
  [ 5, "Candidate 5", 0, 0, 0, 1, 0 ]
]

Output

Schulze.js provides a handy toCsv function for you to generate result in CSV:

schulze.toCsv(rank, config);

where rank is the rank member of returned object generated by fromCsv or fromArray function calls.

Configuration

Schulze.js provides some additional configurations so you can tweak its behavior based on your input and desired output.

Input Options

Input options are available in fromCsv and fromArray.

isRowBased - see next section. default true
isRank - is input data actually ranking order. default false
higherIsBetter - is higher input value means better in score. default true

Output Options

Output options are available in toCsv function.

sort - sort result based on ranking. default false.

Use in Google Sheet

While not yet available, it's possible to use Schulze.js as a google sheet function once you install it after the extension get approved by Google team. To use it, call the function "schulze" with following parameters:

input - Range of the above data, such as "A1:E7"
isRowBased - default true. only set it to false if you got your data transposed.
isRank - set to true if the values are rank instead of score, otherwise false.
higherIsBetter - set to true if higher score means better, otherwise false.

here is an example of the usage and corresponding result:

`=schulze(B2:E8,true,false,true)`

If you don't know how to use spreadsheet function, you can still compute the schulze rank by

selecting the overall data ranges including judges and candidates
in the menu bar, click Add-ons → Condorcet → Condorcet / Schulze Mtehod
the result will be append after the last column of the selected range.

License

This library is open sourced under MIT License. Source code can be found in its Github Repository. For bug reports, pull requests or feature suggestions, please also firing issues / pull requests in the repository.