.. _modules-electoral_college:

########################################
Electoral College results and calculator
########################################

The Electoral College calculator was the Map Center's first module, and it
contains the Electoral College results of all presidential elections since
1964. Users can view the results of all of those elections and make predictions
of the 2012 election.

This module lives in ``lib/map_center/modules/electoral_college.js``.


.. _modules-electoral_college-operation:

*********
Operation
*********

This module has two different but related functionalities: a list of previous
electoral results from elections since 1968 and a calculator allowing users to
predict the electoral results of the 2012 election.

Historical results
******************

The :ref:`tab <ui-tabs>` available to the user contains a dropdown list of all
election years for which we have election results; selecting any of those
options colors each state according to its electoral votes that year and shows
the total number of electoral votes won by each candidate according to the
number of electoral votes cast by each state in that year (including split
votes and `faithless electors`_ where applicable).

.. _faithless electors: http://en.wikipedia.org/wiki/Faithless_elector

.. note::
   Because of the fact that the same module runs both this functionality and
   that of the calculator described in the next section, the module determines
   which functionality to use based on the presence of :ref:`tabs <ui-tabs>`.
   If any tab exists and contains a dropdown list (such as the one used for
   past years' results), it shows historical results; otherwise, it acts as a
   calculator instead.

Calculator
**********

This allows users to predict electoral results for the 2012 election. Each
state has a click handler bound to it that lets users change the party winning
that state's electoral votes. How this works depends on the state:

* Maine and Nebraska use the `Congressional District Method`_ to allocate their
  electoral votes. In practice, then, this means at least three electoral votes
  in each of those states will go to one candidate, but any remaining electoral
  votes in that state could be assigned to any other candidate.
  
  To let users predict scenarios in which either or both of these states can
  split votes, clicking one of these states brings up a
  :ref:`dialog box <ui-dialog_boxes>` that lets users assign these votes.
  
  .. _Congressional District Method: http://en.wikipedia.org/wiki/Electoral_College_%28United_States%29#Congressional_District_Method

* All other states and the District of Columbia award all of their electoral
  votes to the winner of the statewide popular vote, so clicking one of those
  areas toggles the winner in the following order: Republican, Democratic,
  tossup, no votes.

Changing any state's vote updates the vote totals in the sidebar, including
marking one candidate or the other as winning if that candidate has obtained
a majority of electoral votes.


.. _modules-electoral_college-architecture:

************
Architecture
************

This module has a lot of moving parts, so they've been integrated into a small
`publish/subscribe`_ system.

.. _publish/subscribe: http://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern

The pub/sub system lives in the ``ecMap`` object in the module source. That
object has the following methods:

* ``on`` binds subscriber functions to published events. It takes the same
  arguments as `jQuery.bind`_.
  
  .. _jQuery.bind: http://api.jquery.com/bind/
  
  The only event type is ``change``, which fires whenever the map's status is
  changed. To subscribe to this event:
  
  .. code-block:: javascript
     
     ecMap.on("change", function(event, status) {
         // Handler body goes here. status is a status object, described below.
     });

* ``off`` unbinds subscriber functions. It takes the same arguments as
  `jQuery.unbind`_.
  
  .. _jQuery.unbind: http://api.jquery.com/unbind/

* ``set`` takes one argument: a new status object (described below) with which
  to replace the map's entire internal status object.

* ``reset`` takes no arguments and removes all currently set electoral votes.

* ``get`` takes no arguments and returns a copy of the map's current status
  object.

* ``modifyVotes`` takes one argument: an object of changes to state electoral
  votes in order to modify totals without having to know the map's entire
  current state.
  
  For example, if you just wanted to add five Democratic electoral votes for
  Nebraska:
  
  .. code-block:: javascript
     
     ecMap.modifyVotes({
         "Nebraska": {
             dem: 5,
             rep: 0,
             toss: 0
         }
     });

The status objects that are ultimately used all throughout this system have the
following properties:

* ``stateVotes`` is an object that contains the state-by-state electoral vote
  breakdown. The keys are full state names, and the values are objects with
  the keys ``dem``, ``rep`` and ``toss`` and integer values with the electoral
  votes received by each political party in that state.

* ``totals`` is simply an object with the keys ``dem``, ``rep`` and ``toss``
  and integer values with the total electoral votes received by each political
  party.


.. _modules-electoral_college-data_structure:

**************
Data structure
**************

The data for this module is stored in two objects toward the top of the module
source:

* ``electoralVotes`` is an object with election years as keys and objects as
  values. The object for each year contains:
  
  * ``states`` is an object with the number of electoral votes each state had
    in that election. The keys are full state names, and the values are numbers
    of votes.
  
  * ``republican``, ``democratic`` and ``tossup`` are arrays containing the
    names of states whose full electoral votes went to each of those respective
    parties in that election.
    
    .. note::
       Throughout this module, ``tossup`` is used to refer both to predictions
       that keep states in play for either party and to third-party candidates
       receiving Electoral College votes such as `George Wallace in 1968`_.
       
       .. _George Wallace in 1968: http://en.wikipedia.org/wiki/United_States_presidential_election,_1968#George_Wallace_and_The_American_Independent_Party
  
  * States that did not award their full electoral votes to any party in that
    election are not listed in the ``republican``, ``democratic`` and
    ``tossup`` arrays; instead, they have their own objects in the election
    data (using their full state names as keys) containing their electoral vote
    breakdowns by party. For example, since Nebraska `split its vote`_ in 2008:
    
    .. _split its vote: http://en.wikipedia.org/wiki/Nebraska%27s_2nd_congressional_district#Electoral_vote.3B_2008_presidential_race
    
    .. code-block:: javascript
       
       electoralVotes["2008"]["Nebraska"] = {
           "republican": 4,
           "democratic": 1,
           "tossup": 0
       }
    
    Instances of `faithless electors`_ are also represented this way. For
    example, since an elector from the District of Columbia
    `left her 2000 ballot blank`_ in protest:
    
    .. _faithless electors: http://en.wikipedia.org/wiki/Faithless_elector
    .. _left her 2000 ballot blank: http://www.nytimes.com/2000/12/19/us/43rd-president-electoral-college-electors-vote-surprises-are-few.html
    
    .. code-block:: javascript
       
       electoralVotes["2000"]["District of Columbia"] = {
           "republican": 0,
           "democratic": 2,
           "tossup": 0
       }

* ``candidateNames`` is an object with election years as keys and objects as
  values. The object for each year contains the names of the parties'
  candidates participating in that election, using the same ``democratic``,
  ``republican`` and ``tossup`` (where applicable) key names as before and
  string values with each candidate's last name. For example, for the 2012
  election:
  
  .. code-block:: javascript
     
     candidateNames["2012"] = {
         "democratic": "Obama",
         "republican": "Romney"
     }