reference.h File Reference

The reference header file provides facilities to load election data in the reference formats. More...

#include "star/star_base_export.h"
#include "star/election.h"
#include "star/expectedelectionresult.h"
#include "star/calculator.h"

Include dependency graph for reference.h:

Go to the source code of this file.

Classes
struct	Star::ReferenceError
	The ReferenceError struct is used to report errors while parsing election/results data in their reference formats. More...

Namespaces
namespace	Star
	The Star namespace is the main namespace through which all functionality of the STAR++ library is accessed.

Enumerations
enum class	Star::ReferenceErrorType {   Star::NoError ,   Star::CategoryConfig ,   Star::BallotBox ,   Star::ExpectedResult ,   CalcOptions }

Functions
ReferenceError	Star::calculatorOptionsFromReferenceInput (Star::Calculator::Options &returnBuffer, const QString &calcOptionsPath)
ReferenceError	Star::electionsFromReferenceInput (QList< Election > &returnBuffer, const QString &categoryConfigPath, const QString &ballotBoxPath)
ReferenceError	Star::expectedResultsFromReferenceInput (QList< ExpectedElectionResult > &returnBuffer, const QString &resultSetPath)

Detailed Description

Reference Elections

A list of prepared elections can be generated by providing paths to election data in the input reference format to electionsFromReferenceInput().

The reference input format consists of a CSV that contains the ballots of one or more categories (elections) and an INI file that describes how many categories are present,which votes belong to which category, and how many seats need to be filled.

The CSV should consist of a header row, followed by one row per ballot. The first two fields of the header row don't matter, but the following fields should consist of the candidates for each category. The first field of a ballot row does not matter, while the second should contain the candidates name (for now it is unconditionally obfuscated), and finally the remainder should contain a score (0-5) that corresponds to the candidate in the above header row.

Example:

N/A,Voters,CatACan1,CatACan2,CatACan3,CatBCan1,CatBCan2
X,Jim,0,3,5,4,2
X,Sarah,5,2,2,1,4
X,Ted,3,0,0,5,0

The INI file should start with the section "Categories" and then list each category name as a key in the same order they are listed in the CSV. The value of each of those keys should be the number of candidates in those categories. Additionally, a value for the singular key "Seats" must be specified under the section "General" in order to specify how many candidates are to be elected (Bloc voting). Simply use "1" for a typical election with a single winner.

Example:

[Categories]
Category A = 3
Category B = 2
 
[General]
Seats = 2

Reference Expected Results

A list of expected election results can be generated by providing the path to results data in the expected results reference format to expectedResultsFromReferenceInput().

The reference expected results format consists of a single JSON file that encapsulates an array of arrays containing filled seat data. Essentially, the data is the JSON format equivalent of QList<QList<Seat>>. The inner arrays detail seat information for each category (election), while the outer array covers all categories. For example, a data set concerning 5 categories, each with 3 seats to fill, will contain an outer JSON array with 5 elements that are each themselves JSON arrays with 3 elements. The elements of the inner arrays are JSON objects that are similar to a Seat object.

Example (2 categories, 2 seats each):

[
  [
    {
      "winner": "Sixth film",
      "qualifier": {
        "firstAdv": ["Sixth film", "Eighth film"],
        "secondAdv": []       
      }
    },
    {
      "winner": "Seventh film",
      "qualifier": {
        "firstAdv": ["Eighth film"],
        "secondAdv": ["Seventh film"]       
      }
    }
  ],
  [
    {
      "winner": "Fourth Director",
      "qualifier": {
        "firstAdv": ["Fourth Director"],
        "secondAdv": ["Fifth Director"]       
      }
    },
    {
      "winner": "Fifth Director",
      "qualifier": {
        "firstAdv": ["Fifth Director"],
        "secondAdv": ["Second Director"]       
      }
    }
  ]
]

The firstAdv and secondAdv portions of the JSON object are equivalent to the constructor Qualifier(const QSet<QString>&, const QSet<QString>&).

Reference Calculator Options

A set of Calculator::Options can be generated by providing the path to a list of options in the calculator options reference format to calculatorOptionsFromReferenceInput().

The reference calculator options format is simply a text file (generally with the extension 'opt) that contains one enum value from Calculator::Option as a string per line. Blank lines are ignored and an entirely empty file will result in an options set with only the flag Calculator::Option::NoOptions set.

Example:

AllowTrueTies
CondorcetProtocol

See also

ExpectedElectionResult.