Update readme

README.md

@@ -9,6 +9,7 @@ De functie `create_csv_files` in `main.py` is het ingangspunt voor de code. Para
 - `path_to_xml`: het pad naar het `.eml.xml` bestand waarover je de controle uit wilt voeren. Dit is dus een EML tellingsbestand (`id=510[a-dqrs]`)
 - `dest_a`, `dest_b`, `dest_c`: paden waar respectievelijk controlebestanden `a`, `b` en `c` weggeschreven moeten worden. De precieze inhoud van deze bestanden wordt hieronder beschreven
 - `path_to_odt`: optionele parameter, pad naar een proces verbaal in `.odt` formaat. Geldige bestanden zijn `Model_Na31-1.odt` voor een decentrale- en `Model_Na31-2.odt` voor een centrale stemopneming.
+- `path_to_neighbourhood_data`: optionele parameter, pad naar wijkdata in `.parquet` of `.csv` formaat. In `data/` staat het het meest recente beschikbare bestand. (CBS update deze eens in de zoveel tijd, dus deze zal niet altijd 100% up-to-date zijn).
 
 ## Lijst met controles
 Hieronder een korte beschrijving van de controles die onderdeel zijn van HCP. Deze zijn geïmplementeerd in `protocol_checks.py` en worden aangeroepen in `EML::run_protocol` in `eml.py`.
@@ -19,8 +20,9 @@ Hieronder een korte beschrijving van de controles die onderdeel zijn van HCP. De
 | `check_inexplicable_difference` | Geeft de waarde terug die ingevuld is onder 'geen verklaring' in de EML | In `a.csv` een waarde in de kolom "Aantal geen verklaring voor verschil" bij stembureaus *mits deze ongelijk is aan 0* |
 | `check_explanation_sum_difference` | Geeft het verschil tussen (het totaal aantal stemmen en het aantal toegelaten kiezers) en de som van de ingevulde verklaringen. Dus bij 6 stemmen, 5 toegelaten kiezers en een som van verklaringen van 0 is deze waarde 1 (`(6-5) - 0`) | In `a.csv` het aantal dat uit deze verschilberekening komt in de kolom "Aantal ontbrekende verklaringen voor verschil" *mits deze ongelijk is aan 0*
 | `check_too_many_rejected_votes` | Controleert of het *percentage* blanco of ongeldige stemmen ten opzichte van het totaal aantal *uitgebrachte* stemmen groter of gelijk is aan een in te stellen percentage. | In `b.csv` een "ja (`{percentage}`%)" in de bijbehorende kolom bij stembureaus waar dit het geval is
-| `check_too_many_explained_differences` | Controleert of de som van *verklaarde* verschillen ten opzichte van het totaal aantal *uitgebrachte* stemmen groter of gelijk is aan een in te stellen percentage. | In `b.csv` een "ja (`{percentage}`%)" in de bijbehorende kolom bij stembureaus waar dit het geval is
+| `check_too_many_differences` | Controleert of het absolute verschil tussen toegelaten kiezers ten het totaal aantal uitgebrachte stemmen groter of gelijk is aan een in te stellen percentage *of* absoluuut aantal. | In `b.csv` een "ja (`{percentage}`%)" of "ja (`{aantal}`)" in de bijbehorende kolom bij stembureaus waar dit het geval is
 | `check_parties_with_large_percentage_difference` | Controleert of er partijen zijn die bij een stembureau een percentage stemmen heeft behaald dat ten minste een in te stellen aantal percentagepunten verschilt van het gemiddelde in die *gemeente*. Voor de berekening van het gemiddelde in die gemeente wordt het betreffende stembureau niet meegenomen | In `b.csv` de namen van de partijen waarvoor dit het geval is, gescheiden door een komma bij de stembureaus waar dit het geval is
+| `check_potentially_switched_candidates` | Controleert of voorkeursstemmen tussen twee kandidaten op dezelfde lijst mogelijk verwisseld zijn. Dat wil zeggen dat een van de kandidaten veel meer (in te stellen hoeveel) stemmen heeft gekregen dan verwacht terwijl een ander veel minder gekregen heeft dan verwacht. | In `b.csv` de paren kandidaten waarvoor dit het geval is, gescheiden door een nieuwe regel (`\n`) in het formaat: *"Mogelijke verwisseling op lijst `i` (`lijstnaam`). Kandidaat `j` had `v_j` stemmen maar verwachting was `e_j`. Kandidaat `k` had `v_k` stemmen maar verwachting was `e_k`"*
 
 ## .odt verwerking
 Naast de checks die hierboven beschreven zijn, kan ook het proces-verbaal dat bij een telbestand meegeleverd wordt geparsed worden. Het doel hiervan is om stembureau's te identificeren die al een hertelling uitgevoerd hebben. Als dit het geval is, dan wordt in `a.csv` de waarde "x of ja" toegevoegd aan de kolom "Al hergeteld". In alle gevallen moet zowel het nummer als de naam van het stembureau genoteerd staan om zeker te weten dat we deze koppelen aan het juiste stembureau in de EML. Is deze koppeling om welke reden dan ook niet mogelijk, dan gaan we er van uit dat er **niet** herteld is.

src/csv_write.py

@@ -90,7 +90,7 @@ def write_csv_a(
             + [
                 "Aantal geen verklaring voor verschil",
                 "Aantal ontbrekende verklaringen voor verschil",
-                "Al hergeteld",
+                "Al herteld",
             ]
         )
 
@@ -118,7 +118,12 @@ def write_csv_b(
         _write_header(
             writer,
             eml_metadata,
-            f"Spreadsheet afwijkende percentages blanco en ongeldige stemmen, stembureaus met nul stemmen en afwijkingen van het lijstgemiddelde >={int(EML.PARTY_DIFFERENCE_THRESHOLD_PCT)}%",
+            (
+                f"Spreadsheet afwijkende percentages blanco en ongeldige stemmen, "
+                "stembureaus met nul stemmen, "
+                f"afwijkingen van het lijstgemiddelde >={int(EML.PARTY_DIFFERENCE_THRESHOLD_PCT)}% "
+                "en mogelijk verwisselde kandidaten"
+            ),
         )
 
         writer.writerow(
@@ -127,10 +132,13 @@ def write_csv_b(
                 "Stembureau met nul stemmen",
                 f"Stembureau >={int(EML.INVALID_VOTE_THRESHOLD_PCT)}% ongeldig",
                 f"Stembureau >={int(EML.BLANK_VOTE_THRESHOLD_PCT)}% blanco",
-                f"Stembureau >={EML.DIFF_VOTE_THRESHOLD} of >={int(EML.DIFF_VOTE_THRESHOLD_PCT)}% verklaarde verschillen",
+                (
+                    f"Stembureau >={EML.DIFF_VOTE_THRESHOLD} of >={int(EML.DIFF_VOTE_THRESHOLD_PCT)}% verschil "
+                    "tussen toegelaten kiezers en uitgebrachte stemmen"
+                ),
                 f"Stembureau met lijst >={int(EML.PARTY_DIFFERENCE_THRESHOLD_PCT)}% afwijking",
                 "Mogelijk verwisselde kandidaten",
-                "Al hergeteld",
+                "Al herteld",
             ]
         )
 

test/test_e2e.py

@@ -35,7 +35,7 @@ def test_create_csv_files_a():
             "Kieskringnummer;14\n"
             "Gemeentenummer;0505\n"
             "\n"
-            "Kieskringnummer;Gemeentenummer;Gemeentenaam;Stembureaunummer;Stembureaunaam;Aantal geen verklaring voor verschil;Aantal ontbrekende verklaringen voor verschil;Al hergeteld\n"
+            "Kieskringnummer;Gemeentenummer;Gemeentenaam;Stembureaunummer;Stembureaunaam;Aantal geen verklaring voor verschil;Aantal ontbrekende verklaringen voor verschil;Al herteld\n"
             "14;0505;Dordrecht;1;Stembureau Binnenstad (postcode: 3331 DA);2;;ja\n"
         )
         assert content == expected