Get unlimited public & private packages + team-based management with npm Teams.Learn more »

group

1.0.2 • Public • Published

Group

npm status build status dependency status coverage status

A simple pooling algorithm for group stages, ffa style tournaments or anything else that benefits from having seeds/weighted numbers split into fair groups.

Usage

Simply give it the number of players and an approximate group size (this may be reduced if all groups can't be filled), and it will return the fairest groups.

var group = require('group');
group(16, 4);
[ [ 1, 5, 12, 16 ],
  [ 2, 6, 11, 15 ],
  [ 3, 7, 10, 14 ],
  [ 4, 8, 9, 13 ] ]
 
group(25, 5);
[ [ 1, 6, 11, 20, 25 ],
  [ 2, 7, 12, 19, 24 ],
  [ 3, 8, 13, 18, 23 ],
  [ 4, 9, 14 17, 22 ],
  [ 5, 10, 15, 16, 21 ] ]

Fairness properties

Best when two properties are satisfied:

  • numPlayers === groupSize*numGroups
  • groupSize % 2 === 0

You should always strive to satisfy the first condition.

If the groupSize is not even, then we cannot match up weighted pairs and the sum of seeds per group will differ by up to numGroups.

If the groupSize is even, then the sum of seeds per groups are equal across all groups.

Minimal group size

You can check what your minimal group size will be by passing in the number of groups you want to split the players over:

group.minimalGroupSize(16, 4); // 4
group.minimalGroupSize(25, 5); // 5
group.minimalGroupSize(8, 5); // 4
group.minimalGroupSize(numPlayers, groupSize); // general

Partitioning Helper

If you have a pre-sorted array of seeded players, this can be passed to group.fromArray:

group.fromArray(['a','b','c','d','e','f','g','h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p'], 4)
[ [ 'a', 'e', 'l', 'p' ],
  [ 'b', 'f', 'k', 'o' ],
  [ 'c', 'g', 'j', 'n' ],
  [ 'd', 'h', 'i', 'm' ] ]

License

MIT-Licensed. See LICENSE file for details.

Install

npm i group

DownloadsWeekly Downloads

49

Version

1.0.2

License

MIT

Last publish

Collaborators

  • avatar