sitemap.md

Was ist wo? Die Sitemap für das Projekt

(Stand: 9.9.2023)

Programme

...liegen im Ordner "R":

• main.R: Hauptprogramm, das alle Funktionen aufruft: Lies die Konfigurationsdateien ein. Schaue nach neuen Daten, lade sie herunter, verarbeite sie, gibt sie aus, versendet Teams-Messages, loggt jede Aktion in der Datei "obwahl.log"" mit. Die anderen R-Dateien sind über die "source()"-Funktion eingebunden - als Includes.
• main_oneshot.R Version des Hauptprogramms, das nur einmal durchläuft, alles aktualisiert und sich dann verabschiedet
  • **lies_konfiguration.R ** liest die Konfiguration für das Programm (Start der Wahl, Daten über Wahlberechtigte, Datawrapper-IDs) und liest die Index-Dateien ein: Kandidaten, Stadtteile, Wahllokale, Kommunalwahl-Ergebnisse.
  • lies_aktuellen_stand.R: Funktionen, um auf neue Daten zu überprüfen, sie herunterzuladen und zu archivieren.
  • aktualisiere_karten.R: Funktionen, um die Datawrapper-Karten zu aktualisieren.
  • messaging.R: Funktionen, die über Teams Status- und Fehlermeldungen ausgeben.
• its_alive.R: Programm, das über einen CRON-Job alle zwei Minuten aufgerufen wird - und nachschaut, wann das letzte mal etwas in die Logdatei "obwahl.log" geschrieben wurde. Wenn das länger als zwei Minuten her ist, ist das Skript vermutlich stehen geblieben - und das Skript versendet einen Alarm über Teams.

Im Ordner "R" gibt es einen Unterordner "Vorbereitung", der diese Skripte enthält:

• generiere_testdaten.R - erstelle fiktive Daten einer fortschreitenden Auszählung, um die Programme testen zu können.
• teste-curl-polling.R - Testskript, um veränderte Daten über einen CURL-Aufruf so schnell wie möglich zu erkennen (sekundengenau)

Wie das Programm arbeitet

main.R wird einmal aufgerufen und arbeitet dann, bis die Wahl vorbei ist oder ein Fehler auftritt:

• Lies zunächst die Konfigurationsdatei ein und hole Index-Dateien (mehr zu denen unten)
• Starte eine Schleife, solange nicht alle Stimmbezirke ausgezählt sind
  • Checke, ob sich der Zeitstempel der Daten verändert hat (check_timestamp())
  • Lies sie ein (lies_stimmbezirke()), archiviere sie und rechne sie in die benötigten Tabellen um (```berechne_kand_tabelle, aggregiere_stadtteildaten, berechne_ergänzt, berechne_hochburgen)
  • Gib dann die ersten drei Grafiken aus: die Top-5-Grafik, die Balkengrafik mit allen Kandidierenden und die Tabelle mit den Stadtteil-Ergebnissen
  • Nutze die Stadtteil-Ergebnis-Tabelle, um eine Teams-Meldung mit dem aktuellen Stand und dem Ergebnis evtl. ausgezählter Stadtteile zu versenden
  • Aktualisiere dann die Karten: eine Sieger-Karte und die Choropleth-Karten für alle Kandiderenden.
  • Falls keine aktuellen Daten da sind: touchiere einmal kurz die Datei "obwahl.log" (die ja von der its_alive.R überwacht wird, wenn ein entsprechender Cronjob läuft) und beginne dann von vorn

Es gibt eine Version namens main_oneshot.R, die nur einmal durchläuft, ohne auf ein neues Datum zu prüfen. Die ist gut dafür, nachzuaktualisieren.

Wo man welche Funktionen findet (und was sie tun)

messaging.R

• teams_meldung()
• teams_error()
• teams_warnung()

geben über Teams Meldungen aus, z.B. wenn eine neue Auszählung vorliegt.

lies_aktuellen_stand.R

• archiviere(dir) - Hilfsfunktion, schreibt geholte Stimmbezirks-Daten auf die Festplatte

• hole_letztes_df(dir) - Hilfsfunktion, holt die zuletzt geschriebene Stimmbezirks-Datei aus dem Verzeichnis zurück (derzeit nicht benötigt)

• vergleiche_stand(alt_df,neu_df) - berechnet Spaltensummen und vergleicht die Daten

• check_for_timestamp(url) - liest das Änderungsdatum der Datei unter der URL aus

• lies_stimmbezirke(url) - liest aus der Datei unter der URL die Stimmbezirke

• aggregiere_stadtteildaten(stimmbezirke_df) - aggregiert auf Ortsteil-Ebene

• berechne_ergänzt(url) - ergänzt die Stadtteildaten mit den Namen der Kandidierenden, Prozentwerten - und Spalten für die führenden n Kandidierenden (diese Tabelle braucht man für die Choropleth- und Sieger-Karten, die im Mouseover-Tooltipp genau diese Informationen darstellen)

• berechne_kand_tabelle() - die Stimmen- und Prozente-Tabelle mit allen Kandidaten, für die Top-Säulen und Alle-Balkengrafik

• berechne_hochburgen() - eine Tabelle mit den jeweils drei stärksten und drei schwächsten Stadtteilen

• hole_wahldaten() - Sammel-Aufruf. Berechnet alle Tabellen und aktualisiert alle Grafiken, und setzt eine Teams-Meldung ab, wenn es ein Update gab

aktualisiere_karten.R

Hilfsfunktionen:

• generiere_auszählungsbalken() gibt einen HTML-String zurück, der den Fortschrittsbalken enthält: wie viele der Stimmbezirke sind gezählt?

• generiere_auszählung_nurtext() - nur die Ziffern, kein Balken

• font_colour() - eine Hilfsfunktion, die einen RGB-Hex-Farbwert (#12a7bc o.ä.) nimmt und eine Textfarbe zurückgibt, die man darauf lesen kann - weiß oder schwarz. Wird für den Switcher benutzt.

• aufhellen() - gibt eine aufgehellte Farbe zurück; für die Choropleth-Karten

• link_text() produziert einen HTML-String mit einem Button und dem Link zu einer Karte.

• generiere_switcher() baut aus all dem den HTML-String für die Karten - mit den Buttons mit Links.

• karten_body_html() generiert den HTML-Code für das Tooltip-Mouseover (mit den kleinen Balkengrafiken für die ersten (top) Kandidierenden im Stadtteil)

• vorbereitung_alle_karten() setzt für (existierende!) Karten die Metadaten: Farbskala für die Choroplethen bzw. Farbwerte für die Sieger-Karte; Switcher-Buttons im Intro-Absatz, Tooltip mit den Balkengrafiken.

• generiere_socialmedia() exportiert zwei Karten als PNG - wenn der Code auf dem Server läuft, werden sie in ein übers Netz zugängliches Google-Bucket kopiert und der Link auf die PNGs in einen String gepackt, der dann in die Teams-Update-Meldung kommt.

• aktualisiere_top() - aktualisiere und publiziere die Säulen-Grafik der top (top) Kandidaten

• aktualisiere_tabelle_alle() - aktualisiere, vermetadate und publiziere die Balkengrafik mit allen Stimmen für alle Kandidaten

• aktualisiere_karten() - Die Sieger- und die Choropleth-Karten aktualisieren und publizieren

• aktualisiere_hochburgen() - Die Tabelle mit den Hochburgen nach Kandidat

• aktualisiere_ergebnistabelle() - Baut und publiziert die vielen kleinen HTML-Strings mit den Ergebnissen für die gesamte Stadt und jeden Stadtteil als Text. Gibt die Tabelle zurück; die wird auch für die Teams-Nachricht genutzt.