Merge branch 'MarcusBaumgarten-main-patch-33592' into 'main'

Aktualisieren README.md

See merge request !1

README.md

 # Goldberg - Urbanonyme
 
-Skripte zur Nachnutzung und besseren Nachvollziehbarkeit des dazugehörigen Artikels in der ZfdG
-
-#Anleitung
-
-Die folgende Anleitung soll eine Benutzung des Python-Skripts und eine Interpretation der Ergebnisse ermöglichen. Der Programmcode ist kompatibel mit der Python-Version 3.6.
+Die folgende Anleitung soll eine Benutzung des Python-Skripts und eine Interpretation der Ergebnisse ermöglichen. Der Programmcode ist kompatibel mit der Python-Version 3.8.
 
 Bibliotheken:
-Damit das Programm ausgeführt werden kann sind ggf. noch weitere Bibliotheken lokal zu installieren. In den ersten Zeilen der jeweiligen Dateien sind die benutzten Bibliotheken angegeben.
+Damit das Programm ausgeführt werden kann, sind ggf. noch weitere Bibliotheken lokal zu installieren. In den ersten Zeilen der Dateien sind die benutzten Bibliotheken angegeben.
 
-Eingangsdateien: 
-Das Programm verarbeitet Ortsangaben aus GEDCOM-Dateien. Die GEDCOM-Dateien sind mit fortlaufenden Ziffern zu benennen („1.ged“, „2.ged“ etc.). Ziffern dürfen nicht doppelt genutzt werden. Diese Dateien werden in einem Unterordner „data“ platziert. Wenn andere Quellen als GEDCOM-Dateien verwendet werden sollen, ist eine Veränderung des Programms notwendig. Es ist nicht ratsam, nur eine einzige Liste von Ortsangaben zu verwenden, da das Programm darauf basiert, Ortsangaben eines Kontextes in Beziehung zu setzten. Kontext bedeutet hierbei, dass diese Ortsangaben in einer Quelle gemeinsam (also in einem Kontext) benannt werden, was eine geographische Nähe impliziert. Für alle Ortsangaben eines Kontextes sollte also eine eigene Datei erstellt und verarbeitet werden.
-Im Unterordner „data“ sind auch die Dateien des Mini-GOVs zu finden. Hier sind standardmäßig die Mini-GOVs von Deutschland, Polen, Österreich, Schweiz, Tschechien, Dänemark, Frankreich und den Niederlanden eingebunden.
-Daneben versucht das Programm die Dateien „quality.csv“, „placefinder.csv“ und „provincesdict.csv“ zu öffnen, die im selben Ordner wie die Datei „main.py“ liegen. Das sind gleichzeitig die Ausgabedatei des Programms (siehe unten). Sind diese nicht vorhanden, werden diese neu erzeugt. Sind diese vorhanden, werden die vorhandenen Daten genutzt, um die bereits verarbeiteten GEDCOM-Dateien nicht noch einmal auszuführen. Das hilft vor allen in solchen Fällen, in denen das Programm zwischendurch aufgrund einer nicht kontinuierlich vorhandenen Internetverbindung abbricht (siehe nächster Abschnitt).
-Unstetige Internetverbindung: Das Programm greift auf den GOV-Webservice zu, um Informationen zu einzelnen Ortsangaben abzufragen. Hierzu ist eine dauerhafte Internetverbindung notwendig. Da es insbesondere über einen WLAN-Zugang aber Aussetzer geben kann, bei denen das Programm abbrechen kann, ist eine Verzögerung des Programms bei Internetstörungen einprogrammiert. Diese kann manuell an- und abgeschaltet werden. Die Variable withSleeping befindet sich in der Datei „provincefinder.py“ zu Beginn der Funktion „provinceFinder()“. Wenn sie auf 1 gesetzt wird und eine Verbindung zum Webservice nicht hergestellt werden kann, pausiert das Programm für eine Sekunde. Das führt zugleich allerdings dazu, dass das Programm insgesamt eine längere Durchlaufzeit in Anspruch nimmt. Standardmäßig ist diese Funktion nicht aktiviert.
+Erstellung der Normform:
+Das Programm ist darauf ausgelegt, zwei Tabellen mit Personendaten zusammenzuführen. Dazu ist die Erstellung von Tabellen in normierter Form wichtig. Die Ausgestaltung dieser Tabellen ist im dazugehörigen Artikel erklärt. Da die zugrundeliegenden Daten sehr individuell beschaffen sein können, ist es auch die Überführung in die Normform. Hier wird für die im dazugehörigen Artikel verwendeten Leipziger Datenquellen exemplarisch die Erstellung der Normform dargestellt. In den jeweiligen Programmen („normform_KLF.py“ und „normform_KLK.py“) werden die zugrundeliegenden Daten hochgeladen, verarbeitet und als CSV-Datei wieder ausgegeben. Auf andere Datentabellen sind diese Programme nicht anwendbar. Sie bieten jedoch eine geeignete Grundlage zur Anpassung an andere Daten. 
 
-Parallelisierung:
-Die Verarbeitung von GEDCOM-Dateien läuft parallel ab, um die Geschwindigkeit zu erhöhen. Hierzu kann festgelegt werden, wie viele Rechnerkerne genutzt werden. Dazu ist in der Main der Parameter „Pool()“ jeweils zu verändern. Bleibt er leer, so werden alle verfügbare Rechenkerne genutzt. Im Skript ist die Anzahl der Kerne standardmäßig auf die Nutzung aller verfügbaren Kerne eingestellt.
-Provinzenzuordnung: Die Ortsangaben werden verschiedenen Provinzen zugeordnet. Im Standard sind in der Datei „provincefinder.py“ Provinzen vor 1871 und nach 1990 zugeordnet. Für die Zeit dazwischen ist eine provinzielle Zuordnung nicht möglich. Dieses kann aber beliebig angepasst und erweitert werden. Die Bezugszeit kann in der Main in der Funktion „parallel()“ über die Variable referencetime geändert werden. Sie ist standardmäßig auf das Jahr 1800 eingestellt.
+Eingangsdateien:
+Die aus den Normform-Programmen resultierenden CSV-Dateien müssen in „normform1.csv“ und „normform2.csv“ benannt werden. Wenn Personen aus einer Datenquelle zusammengeführt werden sollen, kann es sich um zwei Dateien mit identischem Inhalt handeln.
 
-Cluster:
-Die Clusterbildung von Orten nimmt bei deren Identifizierung eine bedeutende Rolle ein. Der Mindestabstand sowie die Mindestanzahl von Orten in einem Cluster kann dabei variiert werden. Der Mindestabstand zwischen zwei Clustern kann in der Datei „qualitychecker.py“ in der Funktion „qualityChecker()“ über die IF-Abfrage „if distance <= 50:“ geändert werden. In derselben Funktion existiert die Variable minimumClusterSize, über die die Mindestgröße eines Clusters variiert werden kann. Standardmäßig ist diese auf 6 Orte eingestellt.
+Verkürzung der Durchlaufzeit:
+Bei besonders umfangreichen Tabellen kann die Durchlaufzeit verkürzt werden, indem zu Beginn der „main.py“ die Variable sortingBySurnameGiven auf 1 gesetzt wird. Das hat zur Folge, dass die Datentabellen nach der Variable surnameGiven alphabetisch sortiert werden. Wenn „normform1.csv“ und „normform2.csv“ den identischen Inhalt aufweisen, werden in der Folge nur Personen zusammengeführt, deren Nachname (Variable surnameGiven) einen identischen ersten Buchstaben aufweist. Das bringt einen Nachteil für Fälle mit sich, in denen gleiche Personen unterschiedliche Anfangsbuchstaben in der Namensschreibweisen aufweisen (z. B. „Bauer“ und „Pauer“).
 
 Ausgabedateien:
-Das Programm produziert drei Dateien, in der die einzelnen Spalten per Tabstopp voneinander getrennt sind. Die Datei „quality.csv“ gibt Auskunft über die Beschaffenheit und Qualität der Informationen in den GEDCOM-Dateien. Pro GEDCOM-Datei existiert eine Zeile mit Angaben zum Dateinamen, der Anzahl der Ortsangaben in der Datei, dann diese Anzahl der Ortsangabe aufgeteilt in Orte ohne Treffer (noHit), Orte mit mehr als einem Treffer (moreThanOneHit) und Orte mit genau einem Treffer (definitely coordinates), den Mittelpunkt der Längen- sowie der Breitengrade, die Anzahl existierender Cluster, die Anzahl relevanter Cluster, sowie eine Liste der Koordinaten der Mittelpunkte relevanter Cluster.
-Die Datei „provincesdict.csv“ enthält vier Spalten: Die unveränderte Ortsbezeichnung einer Quelle, den Dateinamen, die GOV-ID und die zugeordnete Provinz. Sie hat den Zweck, dass doppelt vorkommende Ortsbezeichnungen in einer Datei nicht doppelt verarbeitet werden müssen.
-Die Datei „placefinder.csv“ enthält zu jeder Ortsangabe Informationen über die ID (GOV-ID), die Koordinaten, eine Information wie die Zuordnung zur GOV-ID stattgefunden hat, die bereinigte Version des Ortsnamens, den originalen Ortsnamen sowie den Namen der Datei, in der der Name vorkommt
+Als Ergebnis wird die Datei „tableResult.csv“ erzeugt. Die jeweiligen Spalten sind mit Tabstopps voneinander separiert. Die Struktur der Tabelle entspricht der Normform. Allerdings sind zusätzlich die Spalten „idSource1“ und „idSource2“ vorhanden, über die nachvollzogen werden kann, welche Einträge zusammengeführt worden sind. Die Spalte „id“ heißt in der Ergebnistabelle zudem „idGlobal“.
 
+Weitere Iterationen:
+Soll eine Datentabelle zusammengeführt werden, werden durch das Programm immer nur zwei gleiche Personen erkannt und zusammengeführt. Sind Personen jedoch mehrmals in der grundlegenden Tabelle vorhanden, kann die Ergebnistabelle wieder als „normform1.csv“ und „normform2.csv“ einer weiteren Iteration zugeführt werden. Hierbei ist jedoch zu beachten, dass aus der Ergebnistabelle die Spalten „idSource1“ und „idSource2“ gelöscht werden. Die Spalte „idGlobal“ muss zudem in „id“ umbenannt werden.
 
-Jan Michael Goldberg, 30. Juni 2022
 
+Jan Michael Goldberg, 04. Oktober 2022
 ## Getting started
 
 To make it easy for you to get started with GitLab, here's a list of recommended next steps.