<commit_before>====================
OCDEP: Elections
====================

:Created: 2016-12-28
:Author: <NAME>, <NAME>, `California Civic Data Coalition <http://www.californiacivicdata.org/>`_
:Status: Proposed

Overview
========

Definition of data types to model elections, candidacies for public office and ballot measures.

The proposed data types are:

* ``Election``
* ``Contest``, a base class for:

    - ``BallotMeasureContest``
    - ``CandidateContest``
    - ``PartyContest``
    - ``RetentionContest``

* ``Candidacy``
* ``OfficeTerm``
* ``Party``

Supplements the "Campaign Finance Filings" proposal prepared by Abraham Epton.

Definitions
===========

Ballot Measure
    A proposition or question with two or more predetermined options put before voters in an election. These include:

    * The enactment or repeal of a statute, constitutional amendment or other form of law.
    * Approval or rejection of a new tax or additional spending of public funds.
    * The recall or retention of a previously elected public office holder.

Candidacy
    The condition of a person being a candidate. A single person may have multiple candidacies if:

    * The person competed in multiple elections, even for the same office term. This includes a candidate in an initial or "primary" election who advances to be a candidate in the "general" election.
    * The person competed to hold multiple public offices, even in the same election.
    * The person was elected to serve a term in a public office and later sought re-election to the same public office.

Candidate
    A person competing to serve a term in a public office.

Contest
    A specific decision with a set of predetermined options put before voters in an election. These contests include:

    * Selecting candidates to hold public offices.
    * Selecting options set forth in a ballot measure.
    * Selecting a preferred political party to hold power.

Election
    A collection of political contests held within a political geography that are decided in parallel through a process of compiling official ballots cast by voters and adding up the total votes for each selection in each contest.

Election Day
    The final or only date when eligible voters may cast their ballots in an election. Typically this is also the same date when results of the election's contests are first publicly reported.

Incumbent
    The candidate for a public office who also currently holds that public office. Also applies to the political party that currently holds majority power.

Office Term
    The interval in which an elected candidate is expected to retain a public office before being re-elected or replaced.

    For a variety of reasons, an office holder may vacate an elected office before serving a full term. This is known as an "unexpired term", a situation which could require an additional contest (known as a "Special Election" in U.S. politics) to fill the empty public office.

Party
    A political organization to which public office holders and candidates can be affiliated. In some electoral systems, such as `party-list proportional representation <https://en.wikipedia.org/wiki/Party-list_proportional_representation>`_, voters may also directly elect political parties to hold power in lieu of or in addition to specific candidates endorsed by the political party.

Public Office
    A position within a governmental body which is filled through an election contest.

Runoff Contest
    A contest conducted to decide a previous contest in which no single option received the required number of votes to decide the contest.

Ticket
    Two or more allied candidates competing together in the same contest where multiple related public offices are at stake. For example, in U.S. politics, candidates for President and Vice President run together on the same ticket, with the President at the top of the ticket.

    Note that candidates on the same ticket are not necessarily affiliated with the same political party.

Write-in
    A vote in a contest wherein the voter explicitly names a preferred selection for an election contest, rather than choosing from among the predetermined selections listed on the ballot.


Rationale
=========

Elections are a primary focal point of civic activity in which eligible voters cast ballots to determine the outcome of political contests, including:

* Who should hold a public office?
* Should a proposed change of law be implemented?

Modeling the potential outcomes of these contests is a service to voters who may cast their ballots in an impending election. Modeling the contests' actual outcomes legitimizes the election's results and enables historical electoral analysis.

This proposal is submitted in response to on-going discussion around a related OCDEP focused on campaign finance disclosures. Representing elections and their contests is necessary for modeling these disclosures because they reveal money raised and spent in support or opposition to specific candidates and ballot measures. However, since notions of elections and their contests run up against other domains, we've separated the definition of these types.

The goal of this proposal is to cover the use cases related to the campaign finance domain while laying the foundation for models that will include election results (to be covered in a future OCDEP).

Our use cases require unique representations of both previous elections and contests as well as pending elections and contests. While honoring these requirements, we also aim for consistency with the Voting Information Project's `XML format specification <http://vip-specification.readthedocs.io/en/vip5/xml/index.html#elements>`_ so as to support a high degree of interoperability with that existing data standard.

VIP 5, the specification's current version, incorporates elements from the `Election Results Common Data Format Specification <https://www.nist.gov/itl/voting/nist-election-results-common-data-format-specification>`_ defined by the National Institute of Standard and Technology. As such, we have borrowed eagerly from NIST's current specification also.

Differences from VIP
--------------------

The two major differences are:

1. VIP models a single election, whereas this proposal intends to model previous and pending elections. As such, certain OCD data types are independent of and linked to multiple elections and/or election contests, unlike their corresponding VIP elements. 
2. VIP models more precise details of elections, including where voters can vote and variations in the order of contests and options as they appear on ballots. These details are beyond the scope of this proposal, which is more focused on representing the distinct election contests and their potential outcomes.

Important differences between the proposed OCD data type and its corresponding VIP element, if any, are noted in each data type's "Mapping to VIP" subsection in Implementation_.

Additionally, VIP describes `<InternationalizedText> <http://vip-specification.readthedocs.io/en/release/built_rst/xml/elements/internationalized_text.html>`_ and `<LanguageString> <http://vip-specification.readthedocs.io/en/release/built_rst/xml/elements/internationalized_text.html#languagestring>`_ elements for the purposes of representing certain texts in multiple languages, e.g., the English and Spanish translations of the ``support_statement`` and ``oppose_statement`` of a ``BallotMeasureContest``. These are treated as strings in this proposal.

Implementation
==============

Election
--------

A collection of political contests set to be decided on the same date within a political geography (aka, ``Division``).<commit_msg>Removed some refs to selections, break out diffs between proposed spec and VIP<commit_after>====================
OCDEP: Elections
====================

:Created: 2016-12-28
:Author: <NAME>, <NAME>, `California Civic Data Coalition <http://www.californiacivicdata.org/>`_
:Status: Proposed

Overview
========

Definition of data types to model elections, candidacies for public office and ballot measures.

The proposed data types are:

* ``Election``
* ``Contest``, a base class for:

    - ``BallotMeasureContest``
    - ``CandidateContest``
    - ``PartyContest``
    - ``RetentionContest``

* ``Candidacy``
* ``OfficeTerm``
* ``Party``

Supplements the "Campaign Finance Filings" proposal prepared by <NAME>.

Definitions
===========

Ballot Measure
    A proposition or question with two or more predetermined options put before voters in an election. These include:

    * The enactment or repeal of a statute, constitutional amendment or other form of law.
    * Approval or rejection of a new tax or additional spending of public funds.
    * The recall or retention of a previously elected public office holder.

Candidacy
    The condition of a person being a candidate. A single person may have multiple candidacies if:

    * The person competed in multiple elections, even for the same office term. This includes a candidate in an initial or "primary" election who advances to be a candidate in the "general" election.
    * The person competed to hold multiple public offices, even in the same election.
    * The person was elected to serve a term in a public office and later sought re-election to the same public office.

Candidate
    A person competing to serve a term in a public office.

Contest
    A specific decision with a set of predetermined options put before voters in an election. These contests include:

    * Selecting candidates to hold public offices.
    * Selecting options set forth in a ballot measure.
    * Selecting a preferred political party to hold power.

Election
    A collection of political contests held within a political geography that are decided in parallel through a process of compiling official ballots cast by voters and adding up the total votes for each option in each contest.

Election Day
    The final or only date when eligible voters may cast their ballots in an election. Typically this is also the same date when results of the election's contests are first publicly reported.

Incumbent
    The candidate for a public office who also currently holds that public office. Also applies to the political party that currently holds majority power.

Office Term
    The interval in which an elected candidate is expected to retain a public office before being re-elected or replaced.

    For a variety of reasons, an office holder may vacate an elected office before serving a full term. This is known as an "unexpired term", a situation which could require an additional contest (known as a "Special Election" in U.S. politics) to fill the empty public office.

Party
    A political organization to which public office holders and candidates can be affiliated. In some electoral systems, such as `party-list proportional representation <https://en.wikipedia.org/wiki/Party-list_proportional_representation>`_, voters may also directly elect political parties to hold power in lieu of or in addition to specific candidates endorsed by the political party.

Public Office
    A position within a governmental body which is filled through an election contest.

Runoff Contest
    A contest conducted to decide a previous contest in which no single option received the required number of votes to decide the contest.

Ticket
    Two or more allied candidates competing together in the same contest where multiple related public offices are at stake. For example, in U.S. politics, candidates for President and Vice President run together on the same ticket, with the President at the top of the ticket.

    Note that candidates on the same ticket are not necessarily affiliated with the same political party.

Write-in
    A vote in a contest wherein the voter explicitly names a preferred option for an election contest, rather than choosing from among the predetermined options listed on the ballot.


Rationale
=========

Elections are a primary focal point of civic activity in which eligible voters cast ballots to determine the outcome of political contests, including:

* Who should hold a public office?
* Should a proposed change of law be implemented?

Modeling the potential outcomes of these contests is a service to voters who may cast their ballots in an impending election. Modeling the contests' actual outcomes legitimizes the election's results and enables historical electoral analysis.

This proposal is submitted in response to on-going discussion around a related OCDEP focused on campaign finance disclosures. Representing elections and their contests is necessary for modeling these disclosures because they reveal money raised and spent in support or opposition to specific candidates and ballot measures. However, since notions of elections and their contests run up against other domains, we've separated the definition of these types.

The goal of this proposal is to cover the use cases related to the campaign finance domain while laying the foundation for models that will include election results (to be covered in a future OCDEP).

Our use cases require unique representations of both previous elections and contests as well as pending elections and contests. While honoring these requirements, we also aim for consistency with the Voting Information Project's `XML format specification <http://vip-specification.readthedocs.io/en/vip5/xml/index.html#elements>`_ so as to support a high degree of interoperability with that existing data standard.

VIP 5, the specification's current version, incorporates elements from the `Election Results Common Data Format Specification <https://www.nist.gov/itl/voting/nist-election-results-common-data-format-specification>`_ defined by the National Institute of Standard and Technology. As such, we have borrowed eagerly from NIST's current specification also.

Differences from VIP
--------------------

The three major differences are:

1. VIP models a single election, whereas this proposal intends to model previous and pending elections. As such, certain OCD data types are independent of and linked to multiple elections and/or election contests, unlike their corresponding VIP elements. 
2. VIP models precise details about ballots, including the exact wording and order of the options (VIP refers to these as "selections") presented to voters in a given jurisdiction. These details are beyond the scope of this proposal.
3. VIP models details about polling locations, including their addresses and hours. These details are also beyond the scope of this proposal.

Important differences between the proposed OCD data type and its corresponding VIP element, if any, are noted in each data type's "Mapping to VIP" subsection in Implementation_.

Additionally, VIP describes `<InternationalizedText> <http://vip-specification.readthedocs.io/en/release/built_rst/xml/elements/internationalized_text.html>`_ and `<LanguageString> <http://vip-specification.readthedocs.io/en/release/built_rst/xml/elements/internationalized_text.html#languagestring>`_ elements for the purposes of representing certain texts in multiple languages, e.g., the English and Spanish translations of the ``support_statement`` and ``oppose_statement`` of a ``BallotMeasureContest``. These are treated as strings in this proposal.

Implementation
==============

Election
--------

A collection of political contests set to be decided on the same date within a political geography (aka, ``Division``).
{'fraction_non_alphanumeric': 0.05543737510475085, 'fraction_numerical': 0.0016115516018822922, 'mean_word_length': 4.550626118067979, 'pattern_counts': {'":': 0, '<': 24, '<?xml version=': 0, '>': 24, 'https://': 4, 'lorem ipsum': 0, 'www.': 4, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1053773', 'n_tokens_mistral': 3664, 'n_tokens_neox': 3358, 'n_words': 2110}