12.1.1. Electoral data: administrative breakdown, political breakdown

The administrative breakdown is a well-known issue. In France, there are five levels: [communes], [circonscriptions], [departement], [region] and [France].

The inclusion relation is transitive, which is easy to handle, but does not exist between communes and circonscriptions: a few large communes are split between several circonscriptions, alone, or together with other smaller communes.

In the same way, political affinities may make it so that some candidates declare several “labels”. The dimension “affiliation” compounds have two levels: label and group.

The non-functional nature of such breakdowns is the source of some issues. For instance, the cumulation of votes by department (or a higher level) can lead to a total lower than the total of the votes, if we cumulate by “first label” (some missing), or to a superior total if we cumulate by “group” (some duplicates). The cross between the two dimensions is at the level: Candidat ↔ Circonscription.

Therefore, the two basic objects are as follows:

• – the “candidat” (candidate), which determines a unique “circonscription” (hence a “department”) and which owns a list of political labels;
• – the “circonscription” (constituency), which maintains the list of its candidats and where votes, spread over the “communes”, must be cumulated.

There are some other objects as follows:

• – the departement, which is a list of one or more circonscriptions: cumulating votes by party label is sometimes an issue (see later);
• – regions and full France: same counting issues;
• – groups: observed from ahead of vote declarations and on election day.

The sources of data concern the election of the member of the French Assemblée nationale during the 2017 election (“législatives”).

 {"Ain*1e_circo*M*MALLET Laurent 15/06/1972 MODEM"}
 {dep:"Ain",c:1,s:"M",n:"MALLET",p:"Laurent",dob:"15/06/1972",g:"MODEM"}

12.1.2. Aggregating data along the spatial dimension: votes by circonscription

In a relational database, this operation could have been done “à la SQL”, with the aggregator sum and the operator GroupBy:

SELECT SUM(votes), Candidat
FROM Communes
WHERE Departement = "D" AND Circonscription = "C"
GROUP BY Candidat;

Here is the JavaScript code for aggregating data from each commune of each circonscription of each departement, resulting in an array indexed by departement:

function processRdata(json){
// @json: {'data':[line1, line2, …]}
// line = {dn, dl, c, cn, cl, i, v, b, n, can:[{s,n,p,g,v},…]}
   const dept = []; // will be updated every makeNewDepartement
   let curDep = null, curCir = null;
   function processRline(line, i){ // code pour chaque ligne
     let ldn = line.dn.toString(), lci = line.c;
     if(curDep && curDep.num === ldn){ // dep exists and is ok
       if(lci === curDep.circos.length){ curCir.update(line);
       }else{
         curCir = makeNewCirconscription(line); // new circo in dep
         curDep.addCirco(curCir);
       }
     }else{
       curDep = makeNewDepartement(line,dept); // new dep
       curCir = makeNewCirconscription(line); // new circo
       curDep.addCirco(curCir); // add to dep
     }
   }
   json.data.forEach(processRline); // loop on lines
   return dept;
 }

NOTE.– The code makes the assumption that data are sequentially listed by circonscription and by department, not randomly. It simplifies the test using the current number curCir or curDep (linear rather than exponential search).

Here are the functions for creating a departement and a circonscription:

function makeNewDepartement(dat, depts){
   let num = dat.dn.toString(), nom = dat.dl;
   let rank = department.length, circos = [];
   let dept = Object.assign(Object.create(depProto),
                               {num, nom, rank, circos});
   depts.push(dept);
   return dept;
 }
function makeNewCirconscription(dat){
   let circ = null;
   delete dat.cn; delete dat.cl;        // unused properties
   dat.can = dat.can.map(function(x){ // can update
     x.dn = this.dn.toString(); x.c = this.c; // see: NOTE below
     x.partis = [x.g];
     return Object.assign(Object.create(canProto), x);
   },dat);
   circ = Object.assign(Object.create(cirProto), dat);
   return circ;
 }
const depProto = Departement.prototype,
       cirProto = Circonscription.prototype,
       canProto = Candidat.prototype;

In that code, the same line of data dat is used for the creation of both the departement and the circonscription. Using the method map avoids using a loop. Also, we are using the assign/create pattern that allows the creation of an object benefiting from the methods of depProto and the properties {num, nom, rank, circos} adapted from dat. The creation of the departement also fills in the array provided by the calling function processRline.

The same assign/create pattern is used for creating a circonscription, this time using cirProto as prototype. Regarding the creation of each candidat in the list of candidates of that circonscription, note that it is done once, using canProto, for the first commune of the circonscription. The next lines of the same circonscription will only update the number of votes. The line of data can be used directly (no adaptation) in the assign method, but we can delete some useless properties (name and number of each commune)

   delete dat.cn; delete dat.cl;     // unused properties

NOTE.– The assign/create pattern uses the flexibility of the prototypal approach and is efficient in lines of code, as it simply reuses fragments of the JSON data.

We may notice the use of the method map, with its optional second parameter, which allows us to bind the value of the pronoun this:

dat.can = dat.can.map(function(x){
   x.dn = this.dn.toString(); x.c = this.c;
   x.partis = [x.g];
   return Object.assign(Object.create(canProto), x);
 }, dat);    // option: binds 'this' to dat

The reason is that we need dat.dn and dat.c inside the callback of a map method applied on the array can: the solution of binding this is very convenient.

12.1.3. Aggregating data along the affiliations dimension: labels by candidate

In order to get the multiple affiliations (at least one) of a candidate, we require a kind of auto-join with a concatenation aggregator somewhat similar to:

SELECT DISTINCT d1.Candidat, CONCAT(d1.Parti, d2.Parti)
FROM Depots AS d1
WHERE d1.Departement = "D" AND d1.Circonscription = "C"
    LEFT OUTER JOIN Depots AS d2
                ON d1.Departement = "D" AND d1.Circonscription = "C"
                        AND d2.Candidat = d1.Candidat
GOUP BY Candidat
HAVING d1.Parti <> d2.Parti

The JavaScript code is a bit more complex than processRdata:

function processDdata(json){
// @json: {'data':[line1, line2, …]}
// line = {string} to be transformed in {dep, c, s, n, p, dob, g}
   const declared = [], multiaff = [];
   let curCan = null;
   const processDline = function (line, i){/*see below*/};
   json.data.forEach(processDline);
   return {declared, multiaff};
 }

It returns an object made up of two arrays: the full list of “declared” candidates, and the list of candidates having filled in more than one affiliation. The code for the per line function is:

function processDline(line, i){
   let can = makeCandidatFromD(line); // pre-process, see below
   if(!can.dob){return false;} // no declaration yet in circo
   if(curCan){
     if(curCan.isSame(can)){ // groupBy -> aggegate parties
       curCan.aggregate(can); // same name expected to follow
       if(!multiple.some(x => x.isSame(curCan))){
             multiple.push(curCan); // if not a duplicate, keep it
       }
       return false; // proceed with groupBy
     }else { // else: this is a new candidat
       declared.push(curCan); // store previous aggregated cand.
     }
   } // now set or reset curCan
   curCan =
Object.assign(Object.create(canProto),can,{partis:[can.g]});
   return this;
 }

NOTE.– The code is simplified under the assumption that multiple declarations of a same candidate are in sequence (which is the case), which eases to reduce them into one single array entry. The assign/create pattern is used again with canProto and a direct copy of can. One more property partis is added directly within the assign method call.

The function makeCandidatFromD uses features described in Chapter 3:

function makeCandidatFromD(original){
   const spl = original.split("*"); // separator * > array 2+ items
   const foundDate = str => str.match(/ dd.dd.dddd /);
   let dep = spl[0], c = parseInt(spl[1]);     // tr.: "1e_circo" -> 1
   if(spl.length>3){
     const ok = foundDate(spl[3]);
     if(ok){          // ok = a date has been found
       const newx = spl[3].split(ok); // split before/after date
       const name = newx[0];
       const spn = name.split(" ");
       const s = spl[2];
       const n = spn.reduce((n,s,i) => n + (s.toUpperCase()===s?
                                             (i>0?" ":"")+s:"") );
       const p = unAccentize(name.slice(n.length+1, name.length));
       const dob = ok[0].substring(1, 11); // separator is the date
       const g = unAccentize(newx[1]);
         return {dep, c, s, n, p, dob, g};
     }
   }
   return {dep, c}; // just a dummy candidat (should have one)
 }

12.2.1. Advantage of the flexibility brought by the prototypal approach

The flexibility that we may expect when processing a join can take advantage of the flexibility of the assign/create pattern. One prototype can be shared by several objects that only own a subset of common properties. The polymorphism of the processing, according to the number of sources actually used, without an a priori knowledge of how many would be available, is another advantage of the prototypal approach.

Here is an example with the D-data (declarations), which allows us to build a candidat with the properties {sex, lastname, first, dob, aff: [p1,p2..]}, and with the R-data (official results), which allows us to build an actual candidat, with properties: {sex, lastname, first, party, votes}.

The prototypal approach cares only about the existing properties, and we can give the same prototype to an R-based candidat and to a D-based candidat, provided that enough properties are set. For instance, the test if(can.dob && !can.v) informs us about the status of can: if true, it means that can has been initialized from D-data, and has not yet been updated with additional R-data.

12.2.2. Coding the join on the electoral application

The basic object to join is the candidat, however, the data are hierarchized from departement, to circonscription, then finally to candidat. Therefore, we need to make a joinability test to each three levels. Here is the code for the method isSame in each of the prototypes:

• – departement: it is encoded differently in R-data or D-data, the name of the already processed department is this.nom, and the name of the not yet processed one (in dat) can be dat.dep or dat.dl, depending on the second source. Here is the polyfill using the acceptString function detailed below:

  Departement.prototype.isSame = function(dat){ // polyfill
     const str = ("dep" in dat)? dat.dep: (("dl" in dat)?dat.dl:dat);
     return acceptString(this.nom, str);
   };

• – circonscription: just check the number (same encoding)

  Circonscription.prototype.isSame = function(dat){return this.c === dat.c;};

• – candidat:

  Candidat.prototype.isSame = function(dat){
     return acceptString(this.n,dat.n) && acceptString(this.p,dat.p);
   };

The function acceptString compares two strings and accepts strings without caring about uppercase versus lowercase, or accentuated versus non-accentuated letters, also ignoring hyphen versus whitespace (“Côte-d’Or” accepted as “Cote dʼor”).

Here is the code for the join (R-data are updated with D-data):

function join(dept,decla){
//@dept: list of departments built by processRdata
//@decla: list of declared candidates, built by processDdata
   let lenR = dept.length, lenD = declares.length,
       curNDep = 0, curNCir = 0;
   const joinDtoRdata = function(can){ // merges D-data to R-data
     // @can = one aggregated "D-based" candidat
     let dep = dept[curNDep], cir;
     while(!dep.isSame(can)){ // seeks for the right dep
       curNDep++; dep = dept[curNDep]; curNCir = 0;
     }
     if(dep) cir = dep.circos[curNCir];
     else throw new Error("join: no Dept for "+can.dep+""+can.c);
     while(cir && !cir.isSame(can)){
       curNCir++; cir = dep.circos[curNCir];
     }
     if(cir) cir.crossUpdate(can);
     else throw new Error("join: no Circo for "+can.dep+""+can.c);
   };
   if(lenD > 0){declares.forEach(joinDtoRdata);}
   return {dept:dept, declares:decla};
 }

Here is the code for the method crossUpdate (circonscription and candidat levels):

Circonscription.prototype.crossUpdate = function(dat){
   let dd = this.can.find(function(x){return x.isSame(dat);});
   if(dd){dd.crossUpdate(dat);}
   else{disparus.push(dat);} // if we want to keep track of them
 };
Candidat.prototype.crossUpdate = function(dat){// update R from D
   this.partis = this.partis.concat(dat.partis);
   this.dob = dat.dob;
   return this;
 };

NOTE.– A circonscription may count more than 100 communes and there may be up to 25 candidats in some circonscriptions. France counts 577 circonscriptions. Such a volume of data imposes a careful coding, aware of performance issues (memory and speed). We will see how to chain the whole processing in order not to hamper the display of the results.

12.3.1. Analyzing the affiliations

The partisan affiliations are not necessarily the names of usual political parties, but groups that accept to share the management of financial contributions. On election day, the authorities (the French Ministère de l’Interieur) give their own label for candidates. There are many “undecided” candidates, with the label “DIV” (“diverse”), sometimes “DVG” or “DVD”, meaning a “diverse” leaning left or right.

In order to better know what these affiliation groups are, we take an example:

const text = "CAISSE CLAIRE";
const crit = function(p){return p.includes(text);};
let gp = [];                 // expected: an array of candidat
depts.forEach(function(d){           // departement d
   d.circos.forEach(function(c){      // circonscription c
     gp = gp.concat(c.can.filter(
         function(x){         // candidat x
                      return x.partis.some(crit);
                }            // apply crit on x.partis
     ));                     // filter candidats then concat
   });                       // by circonscription
 });                         // by departement

The arrow syntax is more readable:

depts.forEach(function(d){
   d.circos.forEach(function(c){
     gp = gp.concat(c.can.filter((x)=> x.partis.some(crit)));
   });
 });

The result is the concatenation for each circonscription of each departement of the list of the candidats affiliated to the given group. For instance, “CAISSE CLAIRE” has 105 candidates, of which 76 are labeled as DIV by the authorities, 15 as DVG (leaning left), six as DVD (leaning right), seven as ECO (ecologist) and one as REG (regionalist). They are very diverse and got 50,972 votes nationwide.

12.4.1. Performance considerations with the electoral application

Within each of the six steps, the code is framed between two calls to a function giving the real elapsed time in milliseconds:

function printLogAndStatus(message){ // t0 a control variable
   t0 = (window.performance.now() - t0);
   console.log(message +". In "+t0.toFixed(0)+" ms.");
 }