Daten in die Corpus Workbench importieren

Hier wird beschrieben, wie ein Korpus in die Corpus Workbench und danach ins Web-Interface zur Corpus Workbench, CQPweb, importiert werden kann. Es ist möglich, den Import des Korpus direkt über CQPweb zu erledigen. Allerdings können dann Metadaten nicht direkt aus der XML-Datei des Korpus ausgelesen werden, sondern müssen in einer separaten Datei zu den einzelnen Texten erfasst werden. Alternativ kann man ein bereits in die CWB importiertes Korpus in CQPweb indizieren, so dass es dann auch über CQPweb verfügbar ist. Dieser Weg wird hier empfohlen und beschrieben; er unterteilt sich in folgende Schritte:

1. Vorbereitung der Daten
2. Import in die CWB
3. Importieren/aktivieren in CQPweb

Natürlich erklärt die offizielle Dokumentation, das Corpus Encoding Tutorial, ebenfalls alle Schritte im Detail und bietet noch weitere Informationen.

Vorbereitung der Daten

Für den Import in die CWB müssen die Daten folgendes Format aufweisen und die Dateiendung .vrt tragen (siehe Kapitel "Daten aufbereiten: XML" für Hilfestellungen, XML-Dateien zu erstellen und Kapitel "POS-Tagging" zur Wortarten-Annotation):

Es können beliebig viele <text>-Blöcke in einer Datei zusammengefasst sein. Das <text>-Element darf auch noch weitere Attribute für weitere Metadaten umfassen, z.B. author, year, date, url, source etc.

Der eigentliche Text muss im vertikalisierten Format vorliegen, also in Form von Spalten, die durch Tabulator-Zeichen getrennt sind. In der ersten Spalte muss zwingend die Wortform stehen. In den weiteren Spalten können (müssen aber nicht) beliebige weitere sog. positionale Attribute, also Informationen, die sich auf das jeweilige Token beziehen, stehen. Überlicherweise stehen in der zweiten Spalte die Wortart und in der dritten das Lemma (die Grundform). Dieses Format liefert z.B. der TreeTagger. Weitere Spalten, z.B. für Named Entity-Klassen sind natürlich möglich.

Zudem sind weitere strukturale Attribute möglich, also weitere XML-Elemente unterhalb des <text>-Elements. Üblich ist beispielsweise die Markierung von Sätzen mit <s>-Elementen o.ä.

Wichtig:

• Zwingend ist für CQPweb das Element <text> und das Attribut id, wobei id alphanumerisch ohne Sonderzeichen und max. 20 Zeichen lang sein darf. Eine Möglichkeit ist, die id einfach als fortlaufende Zahl anzulegen.
• Bei den weiteren Attributen muss zwischen kategorialen und nicht-kategorialen Metadaten unterschieden werden. Wenn nachher in CQPweb gewünscht ist, dass man die Treffermenge nach dem Metadatum gliedern kann, also z.B. sich die Distribution der Treffer über dieses Metadatum anzeigen lassen will, dann muss man das Metdatum als kategorial vorsehen. Wenn das Metadatum aber nur für den Quellennachweis dient, muss das Metadatum nicht kategorial angelegt werden.
  
  Diese Unterscheidung ist wichtig, da kategoriale Metadaten nicht beliebige Zeichen enthalten dürfen. CQPweb (nicht aber die CWB) verlangt, dass kategoriale Metadaten nur alphanumerische Zeichen (und keine Sonderzeichen) enthalten dürfen und maximal 20 Zeichen lang sind.

Empfehlungen:

• Attribut date nach folgenden Muster formatieren: YYYY-MM-DD (z.B. 2015-01-21). Das erleichert nachher in CQPweb die chronologische Darstellung von Treffern.
• Neben date empfiehlt es sich, zusätzlich die Attribute yearmonth und year vorzusehen (YYYY-MM und YYYY). In CQPweb wird es dadurch möglich, die Treffer auch nach groberen Kriterien als nur nach date anzuzeigen.

Wenn die Daten so vorbereitet sind, können sie in die CWB importiert werden.

Import in die CWB

Voraussetzung dafür ist eine korrekt installierte Corpus Workbench. Die Anleitung wurde an den CWB-Versionen 3.0 und 3.1 getestet.

Für den Import sind zwei Verzeichnisse bedeutend, die festgelegt werden müssen:

• Verzeichnis, in dem die importierten Korpusdaten liegen (hier /usr/local/cwb/datafiles/).
• Verzeichnis der "Registries", der Dateien, die den Namen des Korpus und den Speicherort festhält (hier /usr/local/cwb/registry/).

Weiter gehen wir davon aus, dass die zu importierenden Daten, also die .vrt-Dateien, im Verzeichnis korpus/ in unserem aktuellen Arbeitsverzeichnis liegen.

Zuerst müssen wir für das Korpus im Korpusverzeichnis datafiles/ ein neues Verzeichnis für das neue Korpus anlegen. Das geschieht mit:

mkdir /usr/local/cwb/datafiles/korpusname

Wichtig: Erscheint beim Auslösen eines Befehls die Meldung Permission denied, reichen die Benutzerrechte nicht aus, an diesem Ort (oben in /usr/local/cwb/datafiles) Dateien zu erstellen. Das muss auch so sein, da man normalerweise als Benutzer/in im System angemeldet ist und keine Administrationsrechte hat. Man kann sich temporär Administrationsrechte geben, indem man jedem Befehl sudo voranstellt. Dann wird vor dem Auslösen des Befehls erst nach dem persönlichen Passwort gefragt; nachdem man es eingetippt hat, wird der Befehl ausgeführt. Natürlich ist es möglich, die CWB im eigenen Benutzer/innen-Verzeichnis anzulegen, wo man immer volle Rechte hat. Dann erübrigt sich das Problem.

Für den Import in die CWB verwenden wir zunächst den Befehl cwb-encode. Der grundlegende Aufruf lautet:

cwb-encode -d /usr/local/cwb/datafiles/korpusname -F korpus/ -R /usr/local/cwb/registry/korpusname -P pos -P lemma -S corpus -S text:0+id

Schauen wir uns die Argumente genauer an (eine Hilfe zum Befehl erhält man übrigens durch die Eingabe von man cwb-encode oder cwb-encode -h):

• -d /usr/local/cwb/datafiles/korpusname: Mit -d wird das Verzeichnis angegeben, in dem das Korpus für die CWB abgelegt werden soll.
• -F korpus: Damit wird das Verzeichnis angegeben, in dem die .vrt-Dateien liegen. Wenn man nur eine Datei importieren will, kann man auch -f korpusdatei.vrt angeben.
• -R /usr/local/cwb/registry/korpusname: Damit wird angegeben, wie die registry-Datei heißen soll, die im registry-Verzeichnis abgelegt wird. Es empfiehlt sich, für das Datenverzeichnis (-d) und die registry-Datei die gleiche Benennung zu nutzen – zwingend ist das allerdings nicht.
• -P pos -P lemma: Mit -P können beliebig viele positionale Attribute angegeben werden, also Spalten hinter dem Token mit Informationen wie Wortart (POS), Lemma etc. Die erste Spalte des Tokens muss nicht angegeben werden. Hier wird deklariert, dass die zweite Spalte "pos" und die dritte "lemma" genannt werden soll.
• -S corpus: Mit -S werden strukturale Attribute, also XML-Elemente, angegeben. Hier wird deklariert, dass es ein XML-Element <corpus> gibt.
• -S text:0+id: Hier wird ein weiteres strukturales Attribut deklariert, nämlich <text>. Im Unterschied zu oben weist dieses ein Attribut id auf, was wir ebenfalls mit +id deklarieren. Wir wollen aber auch, dass das XML-Element selber auch deklariert wird, deswegen wird 0 angegeben. Wenn weitere Attribute des XML-Elements vorhanden sind, werden diese einfach mit +[Attributname] angegeben.

Der Befehl cwb-encode erlaubt noch viele weitere Optionen. Empfehlenswert sind neben den oben beschriebenen die folgenden:

• -s: Leere Zeilen in der Korpusdatei sollen ignoriert werden.
• -c utf8: Hiermit wird das Encoding der Korpusdatei angegeben. Wenn es sich um UTF-8 handelt (was generell empfehlenswert ist), muss dies hier zwingend angegeben werden.
• -x: Damit werden XML-Elemente in der Korpusdatei erwartet.
• -v: Verboser Modus; gibt Statusmeldungen beim Encodieren aus.

Der vollständige Befehl mit diesen Optionen lautet dann:

cwb-encode -s -c utf8 -x -v -d /usr/local/cwb/datafiles/korpusname -F korpus/ -R /usr/local/cwb/registry/korpusname -P pos -P lemma -S corpus -S text:0+id

Nach dem Encodieren werden für das Korpus mit cwb-makeall verschiedene Indizes erstellt:

cwb-makeall -r /usr/local/cwb/registry korpusname

Nötig ist die Angabe des registry-Verzeichnisses mit -r und danach (Achtung: Mit Abstand getrennt!) der Name des Korpus (bzw. der registry-Datei des Korpus.

Damit steht das Korpus für Recherchen in der CWB bereit. Bei großen Korpora lohnt es sich, zusätzlich zwei Befehle auszuführen, die die Korpusdaten komprimieren. Die beiden Befehle lauten:

cwb-huffcode -r /usr/local/cwb/registry korpusname
cwb-compress-rdx -r /usr/local/cwb/registry korpusname

Beim Ausführen der Befehle informieren beide bei Erfolg darüber, dass jeweils gewisse Dateien im Korpusverzeichnis gelöscht werden können. Das ist natürlich sinnvoll zu tun, um tatsächlich Speicherplatz einzusparen. Das Löschen funktioniert mit dem Befehl:

rm [Dateiname]

Achtung: Löscht man so eine Datei, ist sie unwiederbringlich weg! Also immer gut überlegen, was man tut, wenn man rm auslöst!

Nun kann getestet werden, ob das Korpus korrekt in der CWB installiert worden ist. Dazu starten wir die CWB:

cqp -r /usr/local/cwb/registry/

Die CWB meldet sich mit [no corpus]> und wartet nun auf Befehle. Mit show; werden die bereits indizierten Korpora aufgelistet. Man wählt sich das gewünschte Korpus, indem man seinen Namen eintippt, z.B. KORPUSNAME. Nicht wundern: Hier sind alle Korpusbezeichnungen groß geschrieben!

Nun können beliebige CQP-Befehle ausgeführt werden, z.B. eine Suche nach dem Lemma "Demokratie" mit [lemma="Demokratie"];.

Importieren/aktivieren in CQPweb

Nachdem das Korpus in der CWB inidiziert worden ist, kann es nun auch in CQPweb importiert werden. Dazu muss die Administrator-Oberfläche von CQPweb geöffnet und die folgenden Schritte ausgeführt werden:

1. Auf der Administrator-Oberfläche öffnen wir links im Menü den Befehl "Install new corpus".
2. Da wir das Korpus bereits in der CWB indiziert haben, benutzen wir ganz oben den Link "Click here to install a corpus you have already indexed in CWB."
3. Nun müssen die drei Felder "MySQL name", "full name" und "CWB name" ausgefüllt werden; es handelt sich um den oben gewählten KORPUSNAMEN. Bei "full name" kann auch ein beliebiger aussagekräftigerer Name verwendet werden.
4. Alle anderen Optionen können in der Standardeinstellung gelassen werden. Anschließend klicken wir auf "Install corpus with settings above".
5. Nach der Meldung "Your corpus has been successfully installed!" kann man über den Link "Design and insert a text-metadata table for the corpus" die Metadaten indizieren. Auf der nun folgenden Seite "Admin tools for managing corpus metadata" scrollt man ganz nach unten und wählt den Link "Click here to install metadata from within-corpus XML annotation." Damit nutzen wir die als XML-Tags erfassten Metadaten.
6. Jetzt werden alle verfügbaren Metadaten auf Textebene dargestellt. Die gewünschten Metadaten können nun ausgewählt werden, wobei bei jedem Feld entschieden werden muss, ob der Typus eine "Classification" (also kategorial) oder "Free Text" ist. Die Regeln für "Classification" sind streng (keine Sonderzeichen erlaubt, nicht länger als 20 Zeichen) und sollten nur für Kategorien wie m/w (männlich/weiblich), Datums-, Jahresangaben, Textsorten oder dergleichen verwendet werden. Allerdings kann die Distribution über Treffermengen in CQPweb nur für kategoriale Daten angezeigt werden, daher ist es schon sinnvoll, die wichtigen Metadaten so zu erfassen.
7. Bei großen Textmengen (über 1000 Texte) sollte die Voreinstellung zum "frequency list setup" auf "No thanks" eingestellt werden, andernfalls bei "Yes please". Ein Klick auf "Create metadata table form XML using the settings above" erstellt die Metadatentabelle.
   Wichtig: Hier kann es zu einer Fehlermeldung kommen. Meiner Erfahrung nach können folgende Gründe für den Fehler verantwortlich sein:
   • Kategoriale Metadaten (also wenn "Classification" ausgewählt war) enthalten nicht erlaubte Zeichen – die Fehlermeldung dazu ist eindeutig.
   • Die Fehlermeldung, dass Zeilen außerhalb von <text> gefunden worden seien, ist etwas verwirrend. Meist erscheint der Fehler, weil die XML-Korpusdatei nicht wohlgeformt ist (Wohlgeformtheit kann mit xmllint --noout Dateiname.vrt überprüft werden). Weiter könnte eine Text-ID nicht eindeutig sein, z.B., weil CQPweb die IDs automatisch auf 20 Zeichen kürzt.
8. Fall wir auf der Seite davor "No thanks" angeklickt haben, müssen nun auf der folgenden Seite die Schaltflächen "Generate CWB text-position records", "Populate word and file counts", "Create CWB frequency table" und "Create frequency tables" unter "other metadata controls" angeklickt werden. Das kann bei großen Korpora teilweise lang gehen oder gar nicht funktionieren. Bei sehr großen Korpora können diese Befehle über die Kommandozeile direkt auf dem Server ausgelöst werden (vgl. Hinweise zum Script "../lib/offline-freqlists.php" in der Dokumentation von CQPweb unter "Installing a corpus").
9. Nun muss im Menü links unter "Admin tools" noch die Seite "Manage annotation" gewählt werden: Hier sollten zuerst unten unter "Annotation metadata" für die Handles "lemma" und "pos" zumindest unter Description eine sprechende Bezeichnung gegeben, z.B. "Lemma" und "POS" und jeweils in der Spalte "Update?" mit "Go" gespeichert werden. Dann muss oben unter "Annotation setup for CEQL queries..." unter "Primary annotation" den eben so benannten Eintrag "POS" und unter "Secondary annotation" den Eintrag "Lemma" ausgewählt und auf "Update annotation settings" geklickt werden. Wenn in den Korpusdaten weitere positionale Attribute vorhanden sind, müssen diese hier entsprechend deklariert werden.
10. Wir testen dann im Menü links unter "Standard query" den erfolgreichen Import mit einer Abfrage. Hilfe dazu findet sich im CWB-Kapitel.