Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cjerdonek/quick-sampler

Browser implementation of Ronald L. Rivest's sampling algorithm using AngularJS
https://github.com/cjerdonek/quick-sampler

Last synced: about 21 hours ago
JSON representation

Browser implementation of Ronald L. Rivest's sampling algorithm using AngularJS

Awesome Lists containing this project

README 

        
Quick Sampler

=============



[![Build Status](https://travis-ci.org/cjerdonek/quick-sampler.svg?branch=master)](https://travis-ci.org/cjerdonek/quick-sampler)



This repository contains the source code for an open-source web application

called "Quick Sampler" for transparently and efficiently choosing items

at random from a collection.  Quick Sampler can be used for things like

selecting precincts at random for a post-election manual audit.



The application does this by running the [SHA-256][sha-256] pseudo-random

sampling algorithm described publicly by [Ronald L. Rivest][rivest] in 2011.

You provide the number of items in the collection and a random seed,

and the algorithm picks the items.  The items picked depend only on

this information.



The repository is hosted on GitHub [here][quick-sampler-repo].

To try the latest release, go [here][quick-sampler-app].  For bug reports

and feature requests, visit the [issue tracker][issue-tracker].



Application Features

--------------------



Some application highlights are as follows:



* Implemented using only client-side Javascript,

* Designed for use in both desktop and mobile devices,

* Tested in the latest Chrome and Firefox and in IE 10,

* Developed using [Bootstrap][bootstrap] and [AngularJS][angularjs],

* Tested with automated unit tests and end-to-end tests, and

* Source code available via a permissive open source license

  ([BSD 3-clause](LICENSE)).



Since the application uses only client-side Javascript (i.e. there is no

server-side logic), the application can be deployed using only static

HTML files, etc.  This makes installing much easier if you would like

to host the application on your own servers.  Guidance for installing

locally can be found in the [Installing Locally](#installing-locally)

section.



The tests cover both the algorithm itself and the user interface.  The

algorithm itself (i.e. the output of the algorithm independent of the user

interface) is tested against the publicly available test cases in the

[`rivest-sampler-tests`][sampler-tests] repository.  All tests are set up

to run automatically using [Travis CI][travis-ci].  Different browser

versions are tested automatically from Travis using [Selenium][selenium]

on [Sauce Labs][sauce-labs].



About the Algorithm

-------------------



The Rivest sampling algorithm provides an efficient way to choose items

at random from a collection.



The user must supply a random seed.  The random seed can be any string

of characters (e.g. letters and numbers).  For example, the random seed

can be a string of digits generated by rolling dice several times.



Since the output of the algorithm depends only on the random seed,

independent observers can check the result if they know the seed.

Moreover, because the algorithm is described publicly and is relatively

easy to implement, observers can check the result against other

implementations of the algorithm or even their own.



The reference implementation of the algorithm (written in Python), along

with a description by Rivest can be found [here][rivest-impl]

on Rivest's web site.  Another browser implementation developed by

[Philip B. Stark][stark] can be found [here][stark-app].



### Algorithm Description



This section describes the algorithm using an illustration.



Say you would like to choose from a collection of 1000 items given

the random seed `abc123`.  In actual practice, Rivest recommends using

a random seed having at least 24 digits if the seed is a decimal number

(i.e. a number using the digits 0 through 9).



To find the first number, join the seed with a comma and the number one

to get the following string:



    abc123,1



Encode this string into bytes using UTF-8 and then hash it with SHA-256

to get the following 64-digit hexadecimal integer:



    e4d62e1e48f7a7aa0e59c528bddfd96b4ff06fbff7620d7ae77e0d7e044cbf2e



Compute this integer modulo 1000 to give you an integer between 0 and 999,

which in this case is 454.  Add one to get 455.  This means that the

455th element in the collection of 1000 items is the first item.



To get the second item, apply the same process but with the number

two in place of one:



    abc123,2



In general, concatenate the random seed with the decimal representation

of the sequence number of the item you would like to pick.



If you would like to pick items without repetition and you get a repeat

of a previously picked item, apply the operation again until you get

a new item (as many times as is necessary).



Installing Locally

------------------



If you would like to host Quick Sampler on your own servers, the project's

[Releases][quick-sampler-releases] page contains pre-built releases.

Each release is a self-contained gzip file containing the directory

of files to host.  The directory contains concatenated, minified Javascript

files, all necessary third-party Javascript libraries, etc.



Known Issues

------------



Currently, the application does not support random seed strings that

contain [non-BMP Unicode characters](http://en.wikipedia.org/wiki/Plane_(Unicode))

(i.e. characters whose Unicode code point is higher than 65,536).

This is because of [this issue](https://github.com/Caligatio/jsSHA/issues/21)

in the [jsSHA](https://github.com/Caligatio/jsSHA) Javascript library

that the application uses.



Development

-----------



See the [Development][development] page for information on developing

locally, including how to build the project from source and for other

information on the source code.  This page also contains information

for project maintainers.



License

-------



This project is licensed under the BSD 3-clause license.  See the

[`LICENSE`](LICENSE) file for details.



Author

------



Chris Jerdonek ()



Acknowledgments

---------------



This project was inspired by the browser implementation [here][stark-app]

developed by [Philip B. Stark][stark].



[angularjs]: https://angularjs.org/

[bootstrap]: http://getbootstrap.com/

[development]: docs/development.md

[issue-tracker]: https://github.com/cjerdonek/quick-sampler/issues

[quick-sampler-app]: http://cjerdonek.github.io/quick-sampler/

[quick-sampler-releases]: https://github.com/cjerdonek/quick-sampler/releases

[quick-sampler-repo]: https://github.com/cjerdonek/quick-sampler

[rivest]: http://people.csail.mit.edu/rivest/

[rivest-impl]: http://people.csail.mit.edu/rivest/sampler.py

[sampler-tests]: https://github.com/cjerdonek/rivest-sampler-tests

[sauce-labs]: https://saucelabs.com/account

[selenium]: http://www.seleniumhq.org/

[sha-256]: http://en.wikipedia.org/wiki/SHA-2

[stark]: http://www.stat.berkeley.edu/~stark/

[stark-app]: http://www.stat.berkeley.edu/~stark/Java/Html/sha256Rand.htm

[travis-ci]: https://travis-ci.org/