Format Specification Elections
==============================

As file formats, CSV, XLS or XLSX files are accepted, which are generated by the electoral programs "elections (SESAM)" and "Wabsti elections and votes (VRSG)", or by the web application itself. If a table is to be created by hand, then the format of the web application is the easiest.

"Municipality" might refer to a district, ward, etc.

## Content

1. [OneGov](#1-onegov)
2. [SESAM Majorz](#2-sesam-majorz)
3. [SESAM Proporz](#3-sesam-proporz)
4. [Wabsti Majorz](#4-wabsti-majorz)
5. [Wabsti Proporz](#5-wabsti-proporz)
6. [WabstiCExport Majorz](#6-wabsticexport-majorz)
7. [WabstiCExport Proporz](#7-wabsticexport-proporz)
8. [Party results](#8-party-results)


1 Onegov
--------

The format, which will be used by the web application for the export, consists of a single file per election. There is a row for each municipality and candidate.

### Columns

The following columns will be evaluated and should exist:

Name|Description
---|---
`election_absolute_majority`|Absolute majority of the election, only if Majorz election.
`election_status`|`unknown`, `interim` or `final`.
`election_counted_entities`|Number of counted municipalities. If `election_counted_entities = election_total_entities`, then the election is considered completely counted.
`election_total_entities`|Total number of municipalities. If no definite information about the status of the election is possible (because the election was imported by Wabsti), then this value is `0`.
`entity_id`|BFS number of the municipality. A value of `0` can be used for expats.
`entity_name`|The name of the municipality.
`entity_elegible_voters`|Number of persons entitled to vote in municipality.
`entity_received_ballots`|Number of submitted ballots in municipality.
`entity_blank_ballots`|Number empty ballots in municipality.
`entity_invalid_ballots`|Number invalid ballots in municipality.
`entity_blank_votes`|Number empty votes in municipality.
`entity_invalid_votes`|Number invalid votes in municipality. Zero if Proporz election.
`list_name`|Name of list of candidate. Only with Proporz elections.
`list_id`|ID of the list of the candidate. Only with Proporz elections.
`list_number_of_mandates`|Total number of mandates of the list. Only with Proporz elections.
`list_votes`|Total number if list votes. Only with Proporz elections.
`list_connection`|ID of the list connection. Only with Proporz elections.
`list_connection_parent`|ID of the superordinate list connection. Only with Proporz elections and if it is a sub-list connection.
`candidate_family_name`|Surname of the candidate.
`candidate_first_name`|First name of the candidate.
`candidate_elected`|True, if the candidate was elected.
`candidate_votes`|Number of candidate votes in municipality.

#### Panachage results

The results may contain panachage results by adding one column per list:

Name|Description
---|---
`panachage_votes_from_list_{XX}`|The number of votes the list got from the list with `list_id = XX`. A `list_id` with the value `999` marks the votes from the blank list.

### Temporary results

Not yet completely counted municipalities are not included in the files.

If the status is
- `interim`, the whole election is considered not yet completed
- `final`, the whole election is considered completed
- `unknown`, the whole vote is considered completed, if `election_counted_entities` and `election_total_entities` match


### Template

- [election_onegov_majorz.csv](https://raw.githubusercontent.com/OneGov/onegov.election_day/master/docs/templates/election_onegov_majorz.csv)
- [election_onegov_proporz.csv](https://raw.githubusercontent.com/OneGov/onegov.election_day/master/docs/templates/election_onegov_proporz.csv)

2 SESAM Majorz
--------------

The SESAM export format directly contains all the required data. There is one line per candidate and municipality.

### Columns

The following columns will be evaluated and should exist at the least:

Name|Description
---|---
`Anzahl Sitze`|Number seats
`Wahlkreis-Nr`|Electoral district number
`Wahlkreisbezeichnung`|Electoral district name
`Anzahl Gemeinden`|Number municipalities
`Stimmberechtigte`|Entitled to vote
`Wahlzettel`|Ballots
`Ungültige Wahlzettel`|Invalid ballots
`Leere Wahlzettel`|Empty ballots
`Leere Stimmen`|Empty votes
`Ungueltige Stimmen`|Invalid votes
`Kandidaten-Nr`|Candidate number
`Gewaehlt`|Elected
`Name`|Name
`Vorname`|First name
`Stimmen`|Votes

### Temporary results

The election is considered not counted if the amount of counted municipalities in `Anzahl Gemeinden` (number seats) does not match total number of municipalities. Municipalities that are not yet counted are not included in the data.

### Template

- [election_sesam_majorz.csv](https://raw.githubusercontent.com/OneGov/onegov.election_day/master/docs/templates/election_sesam_majorz.csv)


3 SESAM Proporz
---------------

The SESAM export format directly contains all the required data. There is one line per candidate and municipality.

### Columns

The following columns will be evaluated and should exist at the least:

Name|Description
---|---
`Anzahl Sitze`|Number seats
`Wahlkreis-Nr`|Electoral district number
`Wahlkreisbezeichnung`|Electoral district name
`Stimmberechtigte`|Entitled to vote
`Wahlzettel`|Ballots
`Ungültige Wahlzettel`|Invalid ballots
`Leere Wahlzettel`|Empty ballots
`Leere Stimmen`|Empty votes
`Listen-Nr`|List number
`Parteibezeichnung`|Party description
`HLV-Nr`|
`ULV-Nr`|
`Anzahl Sitze Liste`|Number seats list
`Kandidatenstimmen unveränderte Wahlzettel`|Candidate votes unchanged ballot, part of list vote
`Zusatzstimmen unveränderte Wahlzettel`|Additional votes unchanged ballot, part of list vote
`Kandidatenstimmen veränderte Wahlzettel`|Candidate vote changed ballot, part of list vote
`Zusatzstimmen veränderte Wahlzettel`|Additional votes changed ballot, part of list vote
`Kandidaten-Nr`|Candidate number
`Gewählt`|Elected
`Name`|Name
`Vorname`|First name
`Stimmen Total aus Wahlzettel`|Vote total from ballot
`Anzahl Gemeinden`|Number municipalities

#### Panachage results

The results may contain panachage results by adding one column per list:

Name|Description
---|---
``{List number} {List name}`|The number of votes the list got from the list with the given `Listen-Nr`. A `Listen-Nr` with the value `00` (`00 OHNE`) marks the votes from the blank list.

### Temporary results

The election is considered not counted if the amount of counted municipalities in `Anzahl Gemeinden` (number seats) does not match total number of municipalities. Municipalities that are not yet counted are not included in the data.

### Template

- [election_sesam_proporz.csv](https://raw.githubusercontent.com/OneGov/onegov.election_day/master/docs/templates/election_sesam_proporz.csv)

4 Wabsti Majorz
---------------

The file format needs two individual charts: the data export and the list of elected candidates.

### Columns data export

In the data export, there is a row for each municipality, candidates are arranged in columns. The following columns will be evaluated and should exist:

Name|Description
---|---
`AnzMandate`|
`BFS`|The municipality number (BFS number) at the time of the election. A value of `0` can be used for expats.
`EinheitBez`|
`StimmBer`|
`StimmAbgegeben`|
`StimmLeer`|
`StimmUngueltig`|
`StimmGueltig`|

As well as for each candidate:

Name|Description
---|---
`KandID_{XX}`|
`KandName_{XX}`|
`KandVorname_{XX}`|
`Stimmen_{XX}`|

Additionally the empty and invalid votes as well as candidates will be captured by the following candidate names:

- `KandName_{XX} = 'Leere Zeilen'**` (Empty votes)
- `KandName_{XX} = 'Ungültige Stimmen'**` (Invalid votes)

### Columns candidate results

Because the file format does not supply any information on the elected candidate, those must be included in a second column. Each row consists of one elected candidate with the following columns:

Name|Description
---|---
`ID`|ID of the candidate (`KandID_{XX}`).
`Name`|The surname of the candidate.
`Vorname`|The first name of the candidate.

### Temporary results

The file format does not contain any clear information on whether the overall election is completely counted. This information must be given directly on the form for the data upload.

The file format also does not contain any information on whether an individual municipality is completely counted. Therefore, as long as the entire election is not completed, no progress notification will be shown for Wabsti. If municipalities are missing entirely in the results, they are considered not yet counted.

### Templates

- [election_wabsti_majorz_results.csv](https://raw.githubusercontent.com/OneGov/onegov.election_day/master/docs/templates/election_wabsti_majorz_results.csv)
- [election_wabsti_majorz_candidates.csv](https://raw.githubusercontent.com/OneGov/onegov.election_day/master/docs/templates/election_wabsti_majorz_candidates.csv)

5 Wabsti Proporz
----------------

The file format needs four individual charts: the data export of the results, the data export of the statistics, the list connections and the list elected candidates.

### Columns data export of the results

There is a line per candidate and municipality in the data export. The following columns will be evaluated and should exist:

Name|Description
---|---
`Einheit_BFS`|The municipality number (BFS number) at the time of the election. A value of `0` can be used for expats.
`Einheit_Name`|
`Kand_Nachname`|
`Kand_Vorname`|
`Liste_KandID`|
`Liste_ID`|
`Liste_Code`|
`Kand_StimmenTotal`|
`Liste_ParteistimmenTotal`|

#### Panachage results

The results may contain panachage results by adding one column per list:

Name|Description
---|---
`{List ID}.{List code}`|The number of votes the list got from the list with the given `Liste_ID`. A `Liste_ID` with the value `99` (`99.WoP`) marks the votes from the blank list.

### Columns data export of the statistic

The file with the statistics of the individual municipalities should contain the following columns:

Name|Description
---|---
`Einheit_BFS`|
`Einheit_Name`|
`StimBerTotal`|
`WZEingegangen`|
`WZLeer`|
`WZUngueltig`|
`StmWZVeraendertLeerAmtlLeer`|

### Columns list connections

The file with list connections should contain the following columns:

Name|Description
---|---
`Liste`|
`LV`|
`LUV`|

### Columns candidate results

Because the file format does not supply any information on the elected candidate, those must be included in a second column. Each row consists of one elected candidate with the following columns:

Name|Description
---|---
`ID`|ID of the candidate (`Liste_KandID`).
`Name`|The surname of the candidate.
`Vorname`|The first name of the candidate.

### Temporary results

The file format does not contain any clear information on whether the overall election is completely counted. This information must be given directly on the form for the data upload.

The file format also does not contain any information on whether an individual municipality is completely counted. Therefore, as long as the entire election is not completed, no progress notification will be shown for Wabsti. If municipalities are missing entirely in the results, they are considered not yet counted.

### Templates

- [election_wabsti_proporz_results.csv](https://raw.githubusercontent.com/OneGov/onegov.election_day/master/docs/templates/election_wabsti_proporz_results.
- [election_wabsti_proporz_statistics.csv](https://raw.githubusercontent.com/OneGov/onegov.election_day/master/docs/templates/election_wabsti_proporz_statistics.
- [election_wabsti_proporz_list_connections.csv](https://raw.githubusercontent.com/OneGov/onegov.election_day/master/docs/templates/election_wabsti_proporz_list_connections.
- [election_wabsti_proporz_candidates.csv](https://raw.githubusercontent.com/OneGov/onegov.election_day/master/docs/templates/election_wabsti_proporz_candidates.csv)


6 WabstiCExport Majorz
----------------------

Version `2.2` is supported, please refer to the documentation provided by the exporter program for more information about the columns of the different files.


7 WabstiCExport Proporz
-----------------------

Version `2.2` is supported, please refer to the documentation provided by the exporter program for more information about the columns of the different files.


8 Party results
---------------

Each (proporz) election may contain party results. These results are independent of the other results and typically contain the already aggregated results of the different lists of a party.

The following columns will be evaluated and should exist:

Name|Description
---|---
`Partei`|The name of the party.
`Stimmen`|The number of votes.
`Sitze`|The number of mandates.

### Template

- [election_party_results.csv](https://raw.githubusercontent.com/OneGov/onegov.election_day/master/docs/templates/election_party_results.csv)
