(If you read this on GitHub, you can access a table of contents via the ⋮☰ button in the top-left corner of this panel)
Note that some concepts are named differently in the GUI than in the code for reasons of accessibility. Such pairs of terms are mutually linked in this list.)
When a voter's effective ratings for all options are zero, that voter abstains and thereby does not control any portion of the share. An abstaining voter is treated completely equivalent to a person who does not participate in the poll at all and does not specify any ratings.
At each point in time after a poll has started, each voter either approves or does oppose (=not approve) each option. Whether she approves an option depends on her current effective rating and on every other non-abstaining voter's effective rating. If her effective rating is r, she approves the option if and only if strictly less than r percent of all non-abstaining voters oppose the option.
Note that this is a recursive definition of "approval" which needs to be solved by a suitable algorithm. That algorithm is rather simple: Given all non-abstaining voters and their effective ratings of the option, we find the smallest value r such that strictly less than r percent of these ratings are smaller than r. This number r is called the approval threshold of the option. Everyone with an effective rating at least r then approves, the others don't oppose. This procedure is visualized on the app's ExplainApproval page.
We make sure that every non-abstaining voter approves at least one option, see effective rating.
Based on everyone's approvals (in combination with the current ranking), the shares of all options are calculated during tallying.
Note on language: We say a voter "approves an option" and not that she "approves of an option" to make clear that this is a formal act rather than an expression of opinion.
The approval threshold of an option is the smallest effective rating at which the voters approve the option. It is determined during tallying by finding the smallest number r between 0 and 100 for which the percentage of non-abstaining voters who have an effective rating strictly below r is strictly smaller than r. All voters with an effective rating at least r then approve the option, the others oppose the option.
At each point in time, each option has an approval score between 0 (=0%) and 1 (=100%) which equals the percentage of non-abstaining voters who currently approve the option. The approval scores are used to determine the ranking and thereby influence the shares.
Instead of a traditional ballot on which a voter makes some choices once and then submits it, vodle uses an interactive voting interface.
When a voter has delegated to another voter, we say she is the client in this relationship, while the other voter is the (direct) delegate. Only the delegate will know the identity of the client, as soon as the client sends her the delegation request.
When a poll reaches its due date, it is closed. No-one can change any ratings or delegations from that point on, and a final tally is performed to determine the final shares. For polls of type "winner", also the winner of the poll is then drawn on the basis of these shares. See also results. (In the GUI, we use the phrase "the poll ends" instead of "the poll is closed".)
We control access to user data, poll data and voter data in the user database and poll databases by defining several technical database usernames in the respective CouchDB servers.
- The username
vodleis used to create the other database usernames and to write poll data. - Usernames of the form
vodle.user.UUU, whereUUUis the hash of the combination of user email address and user password, are used to write user data. - Usernames of the form
vodle.voter.VVV, whereVVVis a voter ID, are used to write voter data.
(See comments in DataService for details)
If a voter acts as a delegate for another voter, some or all of her (proxy) ratings are also used as the proxy ratings of the other voter.
If D is a delegate for A then D is either A's direct delegate (if A has sent a delegation request to D that D has accepted), or is an indirect delegate for A (if there is a sequence of direct delegations from A to D via some intermediate delegates).
Instead of choosing ratings herself, a voter can also ask another voter who participates (or is authorized to participate) in the same poll to act as her delegate via a delegation request. If the prospective delegate accepts the request, the first voter becomes the client and the second voter the direct delegate in this relationship. As a consequence, some or all of the delegate's proxy ratings will automatically be used as the client's proxy ratings as well, instead of the client's own ratings. This is as long as the client's request is not withdrawn and the delegate's acceptance is not revoked. During that time, the client can also switch the delegation on and off for individual option via delegation toggles and thus control the proxy ratings of certain options herself via her own ratings.
The delegate can also delegate her own and her client's ratings further to some third voter. This way, a complex delegation network can emerge in which some voters effectively rate on behalf of a smaller or larger number of other voters. Those voters, who have not themselves delegated, are the effective delegates.
We make sure that the delegation network has no cycles by preventing that a voter agrees to a delegation request that would create a cycle. Also, vodle currently enforces a limit to the number of other voters a voter may have as direct or indirect clients. This limit is currently set at 9.
In a future release, a voter may herself set a limit on how many steps her ratings may be delegated further, and how many (indirect or direct) clients her effective delegate may have. Also, in a future release a voter may delegate her rating of different options to different delegates. To prepare for this, the code already now manages all delegations on the level of individual options.
When a voter requests delegation to another voter, vodle asks her to sent a delegation request containing a delegation request link to the other voter either by email, by her smartphone's share capabilities, or by copying the delegation request link and sending it to the other voter in any other way.
When the prospective delegate opens the delegation request link, she is asked to either accept or decline the request. She can change her choice at any time later via her voting interface.
In principle, the delegate can learn the client's voter ID from the delegation request and thus learn about her ratings even without accepting the request, and the client can learn the delegate's voter ID as soon as the delegate answers the request. In practise, the app will however not show either of the two this information. Still, as soon as the delegate accepts the request, both will know each other's proxy ratings because the delegate control both and the client it shown the resulting ratings in her own voting interface.
Each delegation request has a unique Delegation request ID (did).
When a voter has delegated to another voter, her voting interface shows a toggle behind each option's rating slider which she can use to determine whether for this particular option, either her own rating or the (proxy) rating of her delegate shall be used as he proxy rating.
A did is the unique ID of a delegation request.
If a voter A has asked via a delegation request another voter D to act as her delegate, and if D has accepted the request, then D is A's direct delegate and A is D's client.
When a poll is started, the settings made by the poll's creator determine the exact point in time at which the poll will close, which is called the due date (and time) in the code. In the app, we use the formulation "the poll closes on ..." and "closing date" instead.
If a voter A has delegated to some other voter, one can follow the sequence of delegations from A forward through all of A's direct and indirect delegates and will arrive at a voter who has not delegated herself to any other voter. That voter voter is A's effective delegate. The ratings of A's effective delegate are used as A's proxy ratings instead of the ratings that A might have selected herself before delegating.
A voter's effective rating of an option is an auxiliary form of rating used to make sure that every non-abstaining voter approves at least one option. It is calculated from her proxy rating of this option and her proxy ratings of all other options in the following way: If her proxy ratings of all options are all zero, then her effective ratings of all options are also zero and she abstains. If her proxy rating of at least one option is 100, then her effective ratings of all options equal her proxy ratings of those options. Only if her largest proxy rating is properly between 0 and 100, the effective ratings differ from her proxy ratings: In that case, the effective rating(s) of those option(s) that received her highest proxy rating are set to 100 to make sure she approves her highest-rated option(s); the effective ratings of all other options equal their proxy ratings also in this case.
In other words: A voter's effective ratings equal her proxy ratings, only if the largest rating is larger than zero but smaller than 100, the corresponding effective rating is moved up to 100.
The effective ratings are then used to determine who approves what.
This is the GUI's term for what is called closing in the code.
If a voter A has delegated to some other voter B who in turn has delegated to another voter C and so on, then all of B, C, etc. are indirect delegates of A. The final voter in this delegation sequence is A's effective delegate.
While A knows the identity of her direct delegate B, she won't know the identity of her indirect delegates or her effective delegate.
In a later release, voters may restrict how long this delegation sequence may get.
Each user data item, poll data item, or voter data item in a user database or poll database) is stored in the form of a separate JSON document with the general form
{
_id: "~DATABASE_USERNAME:KEY",
value: "ENCRYPTED VALUE",
due: "DUE_DATE"
}
The due date is included only for data items that may not be modified after the poll has closed, to allow the CouchDB server to verify this.
A news item is a small message notifying the user about some relevant event. In contrast to other notifications that may occurr immediately as a consequence of the user's actions, such as the notification that a link was copied, news items notify the user about events triggered by other users' actions, such as new options being added to a poll, delegation requests being answered, etc.
News items appear at the top of the My polls page and the voting interface as cards that can be dismissed.
Each news item has a unique ID.
The globally unique ID of a news item.
The ID of an option, unique in the poll's scope.
The opposite of approval.
Options are the entities that voters in a poll collectively decide about.
If the poll type is "winner", the options represents mutually exclusive alternatives of which the group must collectively select exactly one. In other words, in a "winner" poll, the question the group faces can be formulated as "either option A or option B or option C ...".
If the poll type is "share", the options represent possible targets, activities, recipients, etc., between which the group must collectively divide some given budget or resource. So in a "share" poll, the question the group faces can be formulated as "how much for A, how much for B, how much for C ...".
Each option has a unique option ID.
A voter's own rating of an option is the rating she herself gives by adjusting the rating slider of that option. It is only relevant if she has not delegated her rating of that option to another voter. If she hasn't, her own rating also becomes her proxy rating of the option. Otherwise, her own rating is ignored and her delegate's proxy rating of the option also becomes her proxy rating of the option.
This is the term we use in the GUI for what is called a "voter" in the code.
The globally unique ID of a poll.
A poll is the central object type in vodle. A poll represents a single decision problem for some group of users. In each poll, there are two or more options.
There are several poll types. The poll type determines whether, as the final result of the poll, one option will be declared the winner of the poll, or whether option will be assigned some share of a certain resource or budget, etc.
During its lifetime, a poll lives through three successive states: draft, running, and closed.
As soon as a user starts drafting a poll, the poll is "born" in state draft. Once the user has finished creating the poll and starts it, is becomes running. While it is running, users who get invited to participate in the poll can take the role of a voter in the poll and use the voting interface to see and influence the intermediate results of the poll by rating and/or delegating, and to add further options. Once the due date of the poll is reached, the poll gets closed and the final results are determined.
Each poll has a unique poll ID.
The contents of each poll database, i.e., the poll's poll data items and voter data items, are mirrored for performance reasons as key-value pairs in a simple hash table (a typescript object of type Record) called a poll cache.
For each poll, there are three types of relevant data:
- data that is only relevant for one voter (e.g., a personal note),
- data that is relevant for all voters of the poll but is owned by one voter (e.g., a rating), and
- data that is common to all voters of the poll (e.g., the poll's title).
The first type of data is stored as user data items in the voter's user database to allow roaming.
The other two types of data are stored in the form of voter data items (2.) and poll data items (3.). Both these types are exchanged between the voters via the poll's poll database, which is some CouchDB database that all voters have access to, by means of JSON documents. Several polls might use the same CouchDB database as their poll database without any interference between the different polls. Indeed, by default all polls use the same CouchDB database called "vodle central".
A poll data item is a data item that is related to a particular poll and is common to all voters in that poll (rather than owned by a single voter, compare voter data item).
It is stored as a key-value pair in the poll database and the poll cache.
Most poll data items are also implemented as properties of the class Poll.
Examples of poll data items are the poll's type, title, description, "read-more"-URL, due date, and state, and all option's names, descriptions, and "read-more"-URLs.
A poll data item can be created by any voter in a poll, can be decrypted and thus read by all voters in the same poll by using the poll password, but can usually neither be updated nor deleted. (Only the poll state can be updated according to certain rules.)
After a poll has been started, its creator is asked to invite participants by sending them a poll invitation containing a poll invitation link either by email, by her smartphone's share capabilities, or by copying the poll invidation link and sending it to the prospective participants in any other way.
When a prospective participant opens the poll invitation link, vodle fetches the poll data from the poll's database and registers the participant as a voter in this poll with a randomly generated voter ID.
In the current version, poll invitations are not personalized, so every participant receives the same link, and everyone who gets access to the link can participate, in principle several times as different voters if she uses vodle on several devices with different email addresses.
In a future release, poll invitations will optionally be personalized with the help of a key distribution server (see Architecture).
(not to be confused with user password)
All the poll data and voter data of a poll that is stored in its poll database is encrypted with a poll password that is only known by the poll's voters, or, more precisely, by everyone how has access to the poll invitation link.
So poll passwords are used to restrict who can read a poll's data, but not who has write access to it. Instead, write access is controlled by document validation functions in the CouchDB server.
Each poll is first in state draft, then running, then closed. See poll for details.
Each poll is of either of the following types:
- In a poll of type "winner", marked by a "trophy" icon in the UI, the group must collectively pick exactly one of several mutually exclusive options (or "alternatives").
- In a poll of type "share", marked by a "scissors" icon in the UI, the group must collectively divide a certain budget or resource (money, time, space, etc.) among several options (targets, recipients, projects, activities, etc.)
In a future release, there might be further types, such as a "fixed number of winners" type in which the group collectively picks a predetermined number (e.g., three) of the options.
The type determines what kind of results the poll has and how these are determined in the tallying procedure and presented in the voting interface.
A voter's proxy rating of a certain option is an intermediate form of rating used in tallying. It is the form of rating that is shown by the ratings sliders in thevoting interface.
If the voter has not delegated her rating of that option, her proxy rating equals her own rating of that option. If she has delegated, her proxy rating equals the own rating of her effective delegate. It then also equals the proxy rating of her direct delegate.
(not to be confused with rating)
At any time, the options in a poll are ranked (=sorted) from top to bottom of the voting interface in order of descending [approval score](#approval score). Options that have the same approval score are ranked by descending total ratings score. So, 'higher-ranked' means having a higher approval score or equal approval score and higher total ratings score.
The ranking determines to which of a voter's approved options that voter's share goes: it goes to the highest-ranked option among those options she approves.
(Note that while an option may be rated differently by every voter, the options' ranking is common to all voters because it is computed from all ratings. This is in contrast to some other voting systems (like IRV, STV, the "Alternative Vote", or most "Condorcet" methods) in which voters do not rate the options but instead each voter directly submits her own ranking of all options.)
(not to be confused with ranking)
Ratings (possibly in combination with delegation) are the basic way in which voters influence the results of a poll. Basically, each voter rates each option between 0 and 100. The rating of an option X by some voter represents a conditional commitment of that voter to approve X if enough other voters also approve X, or, equivalently, if not too many voters oppose (=don't approve) X. More precisely, by giving X a rating of r, the voter commits to approve X if and only if strictly less than r per cent of all non-abstaining voters oppose X. See approval for more details on this.
Because of the possibility of delegation, we distinguish between a voter's own rating of an option and a voter's proxy rating of that option. Because we want to make sure that no non-abstaining voter's share is lost, we also distinguish between a voter's proxy rating and her effective rating of an option (but most of the time these are the same). It is the latter that determines who approves what and eventually whose share goes where.
The procedure that determines the results from all ratings is called tallying.
(In the GUI, we use the invented term "wap" instead of "rating" because "rating" would suggests certain wrong assumptions about how the tallying proceeds.)
In a voter's voting interface, each option has a rating slider attached which shows the voter's proxy rating of that option. If the voter has not delegated any rating, the proxy rating equals the voter's own rating of that option, and the voter can use the slider to adjust this rating. If the voter has delegated some ratings but not this one (because she used the delegation toggle to regain control), the slider also shows her own rating and, in addition, a dashed line above it shows the proxy rating of her delegate for comparison. If she has delegated her rating of this option, the slider only shows the proxy rating of her delegate (which is then also her own proxy rating) and cannot be adjusted (which is indicated by a smaller knob).
What kind of results a poll has depends on its type.
-
For a poll of type "share", the main result is an allocation of shares to options, reported in per cent of the budget or resource in question. In other words, each option gets a share between 0% and 100%, and all these shares add up to 100%. So if the result says 70% X and 30% Y, then option X shall get 70% of the budget or resource in question and option Y shall get 30%. For this poll type, there is no randomization involved, the formula that turns everyone's effective ratings into option shares is totally deterministic.
-
For a poll of type "winner", the intermediate results that are shown while the poll is still running are the same as for a poll of type "share". But the reported shares are now representing winning probabilities rather than as parts of a budget or resource. After a poll of type "winner" has closed, the final result of the poll is a single option as the "winner" of the poll.
This option is either the option that received a share of 100%, if such an option exists, or it is determined by drawing from the probability distribution defined by the shares. In other words, the probability that option X wins equals X's share. vodle performs this draw only once as soon as the poll is closed. Although there is no central server that does this draw but the draw is performed by each voter's vodle app, we have made sure that all voters see the same winner. This is achieved by using a pseudo-random number generator that is based on the poll database's revision number of the poll's "state" data item, which is the same for all voters and cannot be predicted before the poll's state is changed from running to closed.
In addition to the shares, vodle also shows the voter
- for each option the sorted list of effective ratings of this option (on the "explain-approval" page),
- all options' resulting approval scores,
- which options she herself approves, and
- which option "her" share goes to.
This is one of the three successive states of a poll. Once started, a poll is running until its due date is reached.
While the poll is running, voters can rate, delegate, add options, and immediately see the effect of their and other voters' actions on the intermediate results, which are continuously updated by the tallying algorithm. This interactive process will ideally make the voters' ratings converge to a combination in which a single option receives all or almost all of the share, or in which the shares are distributed in some other way that is desirable or at least acceptable for all voters.
As the main part of the intermediate and final results of a poll, each option gets assigned a share between 0% and 100%. All options' shares add up to 100%. What the share of an option means depends on the [poll type](#poll type):
- For a poll of type "winner", the share of an option states how likely the option will be drawn as the winner of the poll when the poll closes.
- For a poll of type "share", the share of an option states what part of the budget or resource in question this option gets allocated. For example, if the resource is 40 hours of time and the option's final share is 30%, then 12 hours are allocated to the option.
An option's share equals the percentage of non-abstaining voters who approve this option but don't approve any higher-ranked option. One can interpret this by saying that each non-abstaining voter "controls" an equal share of 100%/N, where N is the number of non-abstaining voters. Therefore we also say that a "voter's share" goes to a certain option. On the level of the code (but not in the UI), we also call this share the voter's "vote" and say that she "votes for" a certain option.
Whenever a voter changes her own rating of some option and whenever some delegation relationship changes, the intermediate results of the poll are updated or calculated freshly. This process is called tallying.
During the tallying process, the following things are updated or calculated freshly in this order:
- For each voter and option:
- if the voter has delegated for this option, find the effective delegate of that voter for that option.
- calculate the proxy rating of that voter for that option, based on her or her effective delegate's own rating, and show it in the rating slider.
- For each voter:
- set all her effective ratings based on all her proxy ratings.
- using them, check whether she abstains.
- For each option: find its approval threshold, based on the effective ratings of the non-abstaining voters. The voter can see this in the "explain" page.
- For each option and non-abstaining voter: check whether she approves the option, based on the option's approval threshold and her effective rating of the option.
- For each option:
- calculate its approval score on the basis of all non-abstaining voters' approval of the option.
- calculate its total ratings score on the basis of all non-abstaining voters' effective ratings of the option.
- Determine the options' ranking based on their approval and total ratings scores.
- For each non-abstaining voter: determine which option that "voter's share" goes to, based on the voter's approvals and the options' ranking. In the code, this option is called the voter's "vote".
- Finally, for each option: calculate its share based on the voters' votes. The voter can see this in the "explain" page.
(see also this Figure)
The details of this algorithm have been very carefully designed to guarantee a number of things such as fairness, neutrality, proportionality, low manipulability, consistent sensitivity to changes, etc. For more details on this, please see the scientific article on the underlying decision method.
The total ratings score of an option equals the sum of all effective ratings the option received from all voters.
(not to be confused with voter)
A user is a person who uses vodle on one or more devices to initiate or participate in one or more polls. A user is identified across devices and sessions by the cryptographic hash value of the combination of her email address and user password. This way, no-one except the user herself can infer anyone's email address.
In each poll the user participates in, she has a poll-specific voter identity that no-one can link to her user identity or to the voter identities she has in other polls.
The contents of the user database are mirrored for performance reasons as key-value pairs in a simple hash table (a typescript object of type Record) called the user cache.
The user database is a CouchDB database that the user has access to. It is used to store user data items across sessions and devices (roaming), in the form of JSON documents. Many users might use the same CouchDB database as their user database, which might also be used as several polls' poll database, without any interference between them. Indeed, by default all users use the same CouchDB database called "vodle central".
A user data item is a data item of a particular user. It is stored as a key-value pair in the user's user database and her user cache.
A user data item might be related to a particular poll and represent private data of the user's voter identity in that poll(e.g., a personal note on the poll or some option) or data needed to get access to the poll database (e.g., its URL).
Examples of user data items are the user's preferred language and notification settings, unpublished poll drafts, poll ID, URLs and passwords of polls, private notes on polls and options, outgoing delegation requests and responses to incoming ones, and the news items for the user.
User data items in the user database are encrypted with the user password.
A few user data items are only stored on the local device of the user, in particular those that are needed to access the user database, such as the user's email address and user password and the user database's URL.
The password the user specifies together with her email address to be able to access her user database from different devices (roaming). Not to be confused with a poll password.
The unique ID of a voter in a poll.
Unlike in many other group decision methods, the term "vote" is not officially used in the vodle UI, neither as a verb nor as a noun because it might be ambiguous. In the code, we use the noun "vote" as a shorthand for "which option a voter's share of 100%/N goes to". In the UI, we rather use language such as "your share goes to ...", "... including your share", etc.
On the code level, a voter is a user in her role as participant in a certain poll. In each poll she participates, a user has a different unique voter ID.
(Note that, to avoid the association of majority voting, we do not (or very rarely) use the term "voter" in the vodle GUI but rather use the term "participant" there.)
A voter data item is a data item that is related to a particular poll and is owned by a particular voter in that poll (rather than being common to all voters, compare poll data item). It is stored as a key-value pair in the poll database and the poll cache. Examples of voter data items are the voter's ratings of all options, and the voter's delegation requests or responses to others' delegation requests. A voter data item can be decrypted and thus read by all voters in the same poll by using the poll password, but can be created, updated or deleted at only by the voter owning the data item. Additional restrictions prevent a voter from changing her ratings or delegations after a poll has closed.
Instead of a fixed "ballot", voters use a dynamic user interface to influence a poll's results. This voting interface allows the voter to
- see the poll's metadata (title, description, URL, due date, option names, descriptions, URLs), some statistics (degree of agreement, no. of non-abstaining voters)
- manage her outcoming and incoming delegations for this poll
- switch delegation on an off for individual options via delegation toggles,
- change her own ratings of all options via ratings sliders,
- add further options,
- see all options' approval score as a light bar coming in from the right, and their shares as a pie chart piece on the left,
- see which options she approves and which option "her" share goes, and
- access explanatory animations for approval scores and shares.
This is the invented word used in the GUI instead of "rating". It abbreviates "willingness to approve".
When a poll of type "winner" closes, a unique option is declared the "winner" as the final result of the poll.
(Polls of type "share" do not have winners, their result is simply an allocation of shares).
Note that the term "winner" refers to an option, not a user or voter.
For a poll of type "winner", the winning probability of an option equals that option's final share. So the share determines with what probability the option will finally be declared the winner.