Dokumentation

Inhaltsverzeichnis

1. Projektbeschreibung

2. Lösungsansatz

3. Architektur

   3.1 Server

   3.2 Datenbank

   3.3 Client

   3.4 Datenquellen

   3.5 Datenaggregation

4. Bedienungsanleitung

   4.1 Compile & Build Toolchain

   4.2 Deployment

   4.3 Hinzufügen einer Kategorie

   4.4 Hinzufügen eines Korpus

   4.5 Mapping zwischen Land und Sprache bearbeiten

5. Ergebnisse/Features

6. Einschränkungen

7. Erweiterungsmöglichkeiten

Projektbeschreibung

In Zeitungsartikeln werden Länder gegenseitig unterschiedlich häufig erwähnt. So berichtet zum Beispiel Dänemark häufiger über Deutschland als Deutschland über Dänemark. Aus einem Korpus aus internationalen Zeitungsartikeln soll nun extrahiert werden, welches Land welches andere Land wie häufig erwähnt. Wie häufig werden die Ländernamen / Hauptstädte /andere wichtige Orte / Politiker / Sportler / ... eines Landes jeweils im anderen Land erwähnt? Wir vergleichen also die relativen Häufigkeiten von dan:Berlin und deu:Kopenhagen. Vermutung: Daraus lässt sich ein "typischer Quotient", unabhängig von der Art der verwendeten Wörter ableiten.

Aufgaben

1. Indikatoren bestimmen (z.B.Städtenamen, Politiker, ...)

2. Indikatoren in Zeitungsartikeln erkennen und nach Kategorie auszählen

3. Erwähnungsquotienten für jede Kategorie bestimmen

4. Graphische Darstellung auf einer Weltkarte: Pfeile entsprechender Dicke zwischen den Ländern.

5. Anwendung für Wörter des Tages?

Lösungsansatz

Zur Bearbeitung der Problemstellung haben wir uns entschieden eine Webanwendung zu nutzen, da diese diverse Vorteile mit sich bringt. Die Anwendung kann sobald sie auf einem Server öffentlich zugänglich ist sehr komfortabel von einer Vielzahl von Nutzern ohne aufwändige Installation verwendet werden und ist so auch unabhängig vom jeweiligen Betriebssystem der Nutzer. Neue Versionen der Anwendung können auf einem Server deployed werden, ohne dass der Nutzer hierfür Updates installieren muss.

Zur Darstellung der Erwähnungen der jeweiligen Ländern nutzen wir eine Choroplethenkarte, auf der je nach Häufigkeit der Erwähnungen die Länder eingefärbt werden. Wir haben uns für diese Methode entschieden, da hierbei die Unterschiede zwischen den Ländern leichter zu erkennen sind als mit der Darstellung durch unterschiedliche Pfeildicke.

Architektur

Die Anwendung Artful besteht aus mehreren Teilen, die voneinander getrennt sind. Grundlegend gibt es vier Teile: den Server, den Client, die Datenbank und diverse Skripte zum Aggregieren der Daten. Die ersten drei werden im Folgendem näher erläutert. Auf letzteres wird in Kapitel Bedienungsanleitung eingegangen.

Server

Der Server wird durch das Spring Framework realisiert. Dieses ermöglicht es, diverse REST-Schnittstellen bereitzustellen und auf die Datenebene zuzugreifen. Es wurden folgende Schnittstellen realisiert:

HTTP-Operation	Pfad	Parameter	Erklärung
GET	/freqs	start end	Gibt alle Referenzen der Länder untereinander in den gewählten Jahren (start bis end) zurück. Antwortformat: JSON

Jede REST-Anfrage ist stateless. Es werden keine Cookies gesetzt oder Sessions gespeichert. Die Nutzung der REST-API ist "read-only", das bedeutet, dass es nicht möglich ist, über diese Daten in der Datenbank zu manipulieren.

Datenbank

Die Verknüpfung von Objekten und den konkreten Daten der relationalen Datenbank geschieht durch JPA. JPA ist eine leichtgewichtiges, auf Objekt-Orientierung basierendes Persistenz Framework, um die Datenbankimplementierung zu abstrahieren und Tabellen auf Klassen abzubilden. Hierfür wurden mehrere Klassen realisiert:

• Translation.java: enthält Informationen über ein Wort, dessen Übersetzungen und zu welchem Land dieses Wort gehört (Bsp: „Berlin" gehört zu Deutschland)

• Freq.java: umfasst die Häufigkeit eines Wortes, aus einem Korpus zu einem Jahr.

• CountryFreq.java: beinhaltet die aggregierten Referenzen der Länder untereinander.

Die resultierenden Tabellen in der Datenbank sind auf der rechten Seite dargestellt.

Durch die genannten Klassen wird der Zugriff auf die gleichnamigen Tabellen in der Datenbank realisiert. Eine Klasse für die Tabelle corpora war nicht notwendig, da diese lediglich zum Aggregieren der Daten benötigt wird.

Client

Der Oberfläche des Client besteht hauptsächlich aus einer Choroplethenkarte. Die Grundlage für diese Karte bildet das Leaflet Framework (http://leafletjs.com). Leaflet ist eine OpenSource JavaScript Bibliothek für Karten. Es eignet sich für dieses Projekt, da es nativ GeoJSON unterstützt. GeoJSON ist ein Format, um geographische Daten inklusive Metadaten zu repräsentieren. Konkret ermöglicht dieses Format es, die geographischen Daten mit den Referenzen der Länder untereinander zu verbinden und somit die Länder entsprechend der Häufigkeit ihrer Erwähnungen einzufärben (siehe Kapitel Features).

Datenquellen

Die GeoJSON Daten zum seperaten Einfärben der Länder kommen von https://geojson-maps.kyd.com.au. Die Korpora, sowie die Frequenzangaben der einzelnen Wörter sind dem Wortschatzprojekt der Universität Leipzig (http://corpora.uni-leipzig.de) entnommen. Diese beinhalten eine feste Anzahl von Sätzen, die Häufigkeit der Wörter der Sätze, sowie einige Metadaten. Diese Daten sind für nicht-kommerzielle Projekte frei verfügbar und bilden die Grundlage für diese Anwendung

Datenaggregation

Zum Aggregieren der Daten werden diverse Python und Java Skripte eingesetzt. Diese werden im Folgendem kurz erläutert:

• avgCorpusSizeCalculator.py: Berechnet die durchschnittliche Anzahl der Frequenz-Einträge pro Jahr für eine Sprache.

• countryFreqSum.py: Akkumuliert die Daten für die country_freq Tabelle. Diese beinhaltet die Anzahl der Erwähnungen eines Landes in einem Jahr. Basierend auf den Erwähnungen werden die Länder in der Oberfläche eingefärbt. Je öfter ein Land erwähnt wird, desto dunkler dessen Färbung. Diese Daten sind nur für die ungerichtete Anzeige (wenn kein Land ausgewählt ist) relevant.

• countryLangMapper.py: Erzeugt ein Mapping zwischen den Ländern und der dazugehörigen Sprachen basierend auf den Einträgen der country-code.csvDatei. Hierbei ist der erste Eintrag der Zeile in der CSV Datei der Name des Landes. Alle weiteren sind mögliche Kürzel der Sprache des Landes. Wenn mehrere Kürzel zutreffen, wird das Sprachkürzel zu dem Land zugeordnet, welches weiter hinten in der Zeile steht. Hieraus folgen zwei Listen, um das Land anhand der Sprache und die Sprache anhand des Landes nachzuschlagen. Beide werden automatisch im Client aus den Dateien country-language-mapping.js und language-country-mapping.js geladen. Dieses Mapping ist notwendig, da die Korpora des Wortschatz Projektes nur das Kürzel der Sprache beinhalten.

• countryReferences.py: Erzeugt eine Matrix bestehend aus den Erwähnungen eines Landes und der Sprache, gruppiert nach dem Jahr. Die Struktur dieser Datei ist wie folgt:

{
	"2015": {
		"Poland": [1, 2, 3],
		"Germany": [10, 20, 30]
	}
}, {
	"2014": {
		"Poland": [1, 2, 3],
		"Germany": [10, 20, 30]
	}
}, {
	"languages": ["deu", "eng-uk", "dan"]
}

Jeder Eintrag in dem Array ([1, 2, 3] für "Poland" 2015) stammt aus einem Korpus. Welche Position welchem Korpus entspricht ist in dem languages Array gespeichert. Dieses JSON-Objekt ist in der Datei country-references.js gespeichert und wird ebenfalls automatisch im Client geladen.

Da die oben genannten Daten mehrere Megabyte umfassen und dessen Akkumulation einige Zeit in Anspruch nimmt, geschieht dies nicht zur Laufzeit, sondern offline. Dies verringert die Ladezeit und Auslastung des Servers.

Bedienungsanleitung

Requirements:

• Java 8, Python 3, pip3, maven

Compile & Build Toolchain

1. Corpora Runterladen: corpora.uni-leipzig.de → Downloads

   1. Alle *-words.txt Dateien in den gleichen Ordner extrahieren

   2. Den Ordner path bei leipzigCorporaParser\config.properties:corpusPath eingeben

2. SparqlQueryTools.java: Erstellt eine .csv Datei die die Resultate der SPARQL Queries enthält. Die SPARQL Queries werden aus einer Datei ausgelesen in der mehrere Queries getrennt durch Leerzeilen stehen können. Wichtig ist, dass das SELECT Statement die richtigen Variablen enthält, also folgendermaßen aussieht:

   SELECT DISTINCT ?id ?entitylabel ?country lang(?entitylabel)

   Außerdem muss die Datei mit einer Leerzeile enden um Probleme zu vermeiden!

   cd leipzigCorporaParser
   mvn clean install
   mvn exec:java@sparql
   

   Die queriesFile muss in leipzigCorporaParser/resources/SPARQLQueries/ liegen, die output.csv wird nach leipzigCorporaParser/resources/translations/ geschrieben Es ist wichtig der .csv einen passenden Namen zu geben, da dieser später als Kategorienbezeichnung genutzt wird

3. leipzigCorporaParser/Main.java: Nimmt die aus 2. generierten .csv-Dateien, sucht die entsprechenden Frequenzen aus den Corpora heraus und speichert alle wichtigen Daten in der SQLite Datenbank

   a. ARTFUL\leipzigCorporaParser\config.properties Pfade eingeben falls: siehe Punkt 1.

   cd leipzigCorporaParser
   mvn clean install
   mvn exec:java@parser
   

   • ja/nein: Kleinere Corpora desselben typs löschen falls vorhanden

4. Benötigte Abhängigkeiten installieren:

     cd data-aggregation-tools
     sudo pip3 install -r requirements.txt
   

5. countryLangMapper: Erstellt die Mappings Country - Sprache bzw. Sprache - Country anhand der country-code.csv. Ausgabe in language-country-mapping.js und country-language-mapping.js

   8. Ausführen

6. countryFreqSum: Erstellt Tabelle country_freq. Aggregiert die References jedes Landes für jedes Jahr

   10. Ausführen

7. countryReferences: Berechnet die Erwähnungen der Länder untereinander. Ausgabe in country-references.js

   11. Ausführen

8. Webserver: Hostet die Webanwendung. Stellt relevante REST Schnittstellen zur Verfügung

   12. Siehe Deployment

Deployment

1. (Tomcat Deployment)

   ```mvn clean package```
   
   
   copy artful.war to tomcat/webapps directory
   

2. (Internal Tomcat: Server.java Ausführen)

   cd server
   mvn clean install 
   mvn spring-boot:run -Dtranslation_database=src/main/resources/translations.sqlite
   

Hinzufügen einer Kategorie

Zunächst müssen mithilfe von SparqlQueryTools.java Entitäten der neuen Kategorien aus DBpedia geholt werden. Beim Schreiben der Query bzw. Queries ist auf die Hinweise aus der Bedienungsanleitung zu achten. Wurde SparqlQueryTools.java erfolgreich ausgeführt müssen jeweils leipzigCorporaParser/Main.java, countryFreqSum.py, countryReferences.py ausgeführt werden.

Hinzufügen eines Korpus

Es ist wichtig, dass die Korpusdatei entpackt als .txt im translationPath liegt und die Form [Sprachenkürzel][Quelle][Jahr]_[Anzahl]-words.txt hat, also z.B. ara-ae_web_2015_300K-words.txt .

Danach muss lediglich wieder leipzigCorporaParser/Main.java, countryFreqSum.py und countryReferences.py ausgeführt werden.

Mapping zwischen Land und Sprache bearbeiten

Die Verknüpfung einer Sprache mit einem Land geschieht mit dem countryLangMapper.py Skript (siehe Kapitel Datenaggregation). Um eine bestehende Verknüpfung anzupassen, muss der Eintrag des Landes in der country-code.csv Datei angepasst werden. Wichtig ist hierbei, dass jede Zeile 4 Einträge hat, der erste ist der Name des Landes und alle weiteren sind mögliche Kürzel. Ein Land kann so mit 1-3 Sprachkürzeln verknüpft werden, das Kürzel muss identisch mit dem Eintrag in der Tabelle corpora sein (siehe Datenbank). Sollten mehrere Kürzel passend sein, wird der weiter hinten stehende Eintrag bevorzugt.

Sollte das Land noch nicht in der country-code.csv Datei vorhanden sein, so kann in dieser eine neue Zeile für dieses Land hinzugefügt werden.

Ergebnisse/Features

Die folgende Abbildung zeigt einen Ausschnitt der Anwendung. In der oberen rechten Ecke befindet sich ein Panel, in diesem werden die Erwähnungen des ausgewählten Landes, sowie der prozentuale Anteil der Erwähnungen des Landes, über das der Nutzer hovert. Ist "Outgoing References" (blauer Pfeil) ausgewählt, werden die Worthäufigkeiten berücksichtigt, welche die Sprache des ausgewählten Landes haben und sich in dem Land befinden, über das der Nutzer hovert. Durch einen Klick auf den Pfeil wird der Modus zu "Ingoing References" umgeschaltet und die Richtung der Beziehung der Länder umgedreht.

Sollte kein Land ausgewählt werden, so werden die Erwähnungen aller Länder angezeigt.

Neben der Selektion eines Landes hat der Nutzer die Möglichkeit, die Zeitspanne der zu berücksichtigen Daten anhand des Sliders oben rechts auszuwählen, siehe Grafik links.

Im unteren rechten Abschnitt befindet sich die Legende. Es ist möglich, die Einfärbung der Länder linear oder logarithmisch zu gestalten, siehe Grafik rechts.

Als Grundlage für die Berechnung dienen die Korpora des Wortschatz-Projektes der Universität Leipzig (siehe Datenquellen). Diese bestehen jeweils aber nur aus unterschiedlichen Größen. Ein Korpus kann so aus 10.000 bis 3.000.000 Sätzen einer Sprache bestehen. Um verlässliche Aussagen anhand der Korpora treffen zu können, werden diese auf eine einheitliche Größe normiert.

Einschränkungen

Ein Problem bei dem Umgang mit den Korpora des Wortschatz-Projektes ist, dass diese Sammlung nicht vollständig ist. Bei einigen Korpora fehlen einzelne Jahre, das Jahr 2000 fehlt beispielsweise bei allen Korpora. Ebenso sind nicht alle Sprachen vertreten.

Das Wortschatz-Projekt nutzt keine standardisierte Bezeichnungsvorschrift zur Abkürzung der Sprache des Korpus. Dieser kann hierbei aus einem oder zwei Teilen bestehen, getrennt durch einen Bindestrich. Sofern er aus einem Teil besteht, handelt es sich meist um eine Sprache, die nur in einem Land Amtssprache ist. Der italienische Korpus heißt beispielsweise „ita". Der österreichische Korpus heißt hingegen „deu-at“, bestehend aus der Sprache „deu“ für Deutsch und „at“ für Österreich.

Eine Sprache wird oftmals nicht nur in einem Land als Amtssprache gesprochen. Es ist zwar möglich einigen Korpora mit zweistelligem Sprachcode einem eindeutigen Land zuzuordnen, dies ist aber nicht bei allen der Fall. Bei einigen einstelligen Sprachcodes, z.B. „fra" für Französisch, ist dies nicht möglich, da diese in mehreren Ländern als Amtssprache fungieren. In diesem Fall muss auf diese Daten verzichtet werden, da sie keinem Land eindeutig zugeordnet werden können. Für andere Sprachen gibt es teilweise mehrere Sprachen, wie bei Chinesisch: „zho“ und „zho-trad“. Bei solchen Fällen werden die kleineren Korpora verworfen.

Die Anwendung Artful vereint Daten aus mehreren Quellen. Um Übersetzungen von Wörtern zu generieren, wurde auf die Daten von DBPedia zurückgegriffen. Die Daten von DBPedia werden von einer breiten Community gepflegt. Dies führt dazu, dass auch falsche oder veraltete Daten vorhanden sind. Unter der Kategorie „Land" werden auch nicht mehr aktuelle Einträge, wie z.B. „East Germany“ geführt. Ebenso sind falsche Einträge, wie „Hong Kong“ vorhanden, welches eine Sonderverwaltungszone und kein eigenständiges Land ist.

Erweiterungsmöglichkeiten

Das Projekt Artful kann durch verschiedene Features und Daten erweitert werden. Im Moment sind in der Anwendung zwei Kategorien vorhanden, Städte und Politiker. Um die Anwendung weitere Kategorien zu erweitern, müssen dessen Übersetzungen lediglich in die Datenbank geschrieben werden. Dies wurde im Kapitel Bedienungsanleitung näher erläutert. Es ist ebenso möglich, der Anwendung weitere Korpora hinzuzufügen. Besonders für afrikanischen Sprachen fehlen noch die Korpora mehrere Jahre und teilweise auch ganze Sprachen.

Wie im letzten Kapitel erläutert, sind eventuell nicht alle Sprachen korrekt bzw. nicht vollständig zu den Ländern verknüpft, in denen sie gesprochen werden. Dieses Mapping kann verbessert werden, indem fehlerhafte Einträge korrigiert und neue Einträge hinzugefügt werden. Dies kann getrennt von der Programmlogik des Projekts vorgenommen werden, indem die Datei data-aggregation-tools/country-code.csv dahingehend angepasst wird, siehe Kapitel Bedienungsanleitung.

Neben der Anpassung der Daten können ebenso noch weitere Features implementiert werden. Denkbar sind Statistiken, wie Wörter des Jahres: diejenigen Wörter und ihre Übersetzungen, die in einem Jahr die höchste Frequenz aufweisen. Es sollte jedoch darauf geachtet werden, dass sogenannte Stoppwörter nicht berücksichtigt werden, damit Trendbegriffe sichtbar werden.

Die Anwendung Artful zeigt nur die aggregierten Daten über die Erwähnungen der Länder untereinander an. Es ist denkbar, weitere API-Schnittstellen hinzuzufügen, um die Anzahl der Erwähnungen einzelner Wörter abzurufen.