From 29a1b31bb41deea7fed12803fa0ec4f469e94eb5 Mon Sep 17 00:00:00 2001
From: untergeekDE <jan@eggers-elektronik.de>
Date: Sat, 11 Mar 2023 20:33:19 +0100
Subject: [PATCH] =?UTF-8?q?Dokumentation=20erg=C3=A4nzt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 R/aktualisiere_karten.R |  2 ++
 R/main.R                |  6 ++--
 README.md               |  9 ++----
 sitemap.md              | 68 ++++++++++++++++++++++++++++++++---------
 4 files changed, 61 insertions(+), 24 deletions(-)

diff --git a/R/aktualisiere_karten.R b/R/aktualisiere_karten.R
index 406c3bb..9fa8491 100644
--- a/R/aktualisiere_karten.R
+++ b/R/aktualisiere_karten.R
@@ -294,6 +294,8 @@ aktualisiere_top <- function(kand_tabelle_df,top=5) {
 }
 
 aktualisiere_tabelle_alle <- function(kand_tabelle_df) {
+  # Daten und Metadaten hochladen, für die Balkengrafik mit allen 
+  # Stimmen für alle Kandidaten
   dw_data_to_chart(kand_tabelle_df, chart_id = tabelle_alle_id)
   balken_text <- generiere_auszählung_nurtext(gezaehlt,stimmbezirke_n,ts)
   # Metadaten anpassen: Farbcodes für Parteien
diff --git a/R/main.R b/R/main.R
index 6ddc7f1..695ed73 100644
--- a/R/main.R
+++ b/R/main.R
@@ -15,7 +15,7 @@ p_load(R.utils)
 
 rm(list=ls())
 
-TEST = TRUE
+TEST = FALSE
 DO_PREPARE_MAPS = TRUE
 
 
@@ -95,10 +95,10 @@ while (gezaehlt < stimmbezirke_n) {
     ts <- ts_daten
     hole_wahldaten()
   } else {
-    # Logfile erneuern und 15 Sekunden schlafen
+    # Logfile erneuern und 10 Sekunden schlafen
     system("touch obwahl.log")
     if (TEST) cat("Warte...\n")
-    Sys.sleep(15)
+    Sys.sleep(10)
   }
 }
 # Titel der Grafik "top" umswitchen
diff --git a/README.md b/README.md
index f74ad16..f424cf0 100644
--- a/README.md
+++ b/README.md
@@ -44,14 +44,9 @@ Aggregation auf Stadtebene
 (siehe ["Sitemap"](./sitemap.md) für den Code)
 
 
-# TODO
+## Nice-To-Have 
 
-
-- Upload aufs Repository
-
-## NTH
-
-- Umschalten Top5-Titel Ergebnis
+- Vergleich letzte Kommunalwahl
 - Zusatzfeature: Briefwahlprognostik - wieviele Stimmen fehlen vermutlich noch?
 - Shapefiles KS, DA verbessern
 - Datensparsamere Alternativ-CURL-Poll-Datei (zB mit dem Gesamtergebnis)
diff --git a/sitemap.md b/sitemap.md
index 316479b..8c56057 100644
--- a/sitemap.md
+++ b/sitemap.md
@@ -3,7 +3,8 @@
 ## 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, gewissermaßen.
+* **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. 
@@ -12,30 +13,69 @@
   
 Im Ordner "R" gibt es einen Unterordner "Vorbereitung", der diese Skripte enthält:
 
-* generiere_testdaten.R
-* teste-curl-polling.R - Testskript, um veränderte Daten über einen CURL-Aufruf so schnell wie möglich zu erkennen (sekundengenau)
-* prepare.R - generiert die Datawrapper-Skripte und -karten und Indexdaten. 
+* 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  
+- 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_führende
-
+- 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
-## Wie das Programm arbeitet
 
-```main.R``` wird einmal aufgerufen und arbeitet dann, bis die Wahl vorbei ist
-oder ein Fehler auftritt: 
+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.
+
+  
 
-- Lies zunächst die Konfigurationsdatei ein und hole Index-Dateien
-- 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_gebiet()```)
 
-- 
GitLab