
Gap.pl -repair
--------------

Es passiert hin und wieder, dass eine GAP4-Datenbank fehlerhaft wird. Eine
Meldung wie "Database is not consistent. 126 problems detected." löst
Frustrationen aus, besonders weil meist keine unmittelbare Ursache für das
Auftreten der Fehler zu erkennen ist. Die Datenstrukturen der GAP4-Datenbank
weisen in solchen Fällen unsinnige oder fehlende Einträge auf, was für den
Anwender nicht ohne Weiteres erkennbar oder einsehbar ist.

  [Für den interessierten Leser:]
  GAP4-Datenbankfehler sind in der Regel schwierig zu verstehen, weil sie
  sehr eng mit der inneren Funktionsweise der GAP4-Datenbank zusammenhängen.
  Darum ist es nützlich, die Organisationsweise einer GAP4-Datenbank zu
  kennen. Einige Kernpunkte sind hier aufgezählt.
  - alle Objekte einer GAP4-Datenbank - das sind Contigs, Reads, Annotationen,
    Templates - werden durch einen Datensatz (= "Datenknoten") dargestellt.
    Ein Datenknoten ist ein Bündel mehrerer Wertefelder, mit dem alle Eigen-
    schaften des Contigs, des Reads etc. beschrieben werden.
  - alle Datenknoten sind in Ketten angeordnet. Beispielsweise besitzt jeder
    Read-Datenknoten einen Verweis auf die erste Annotation dieses Reads. Die
    erste Annotation verweist auf die zweite Annotation usw. Ein NULL-Verweis
    beendet die Kette. Die gleiche kettenförmige Anordnung gilt für die Reads
    eines Contigs: Ein Contig-Datenknoten verweist auf den ersten Read des
    Contigs. Der erste Read verweist auf den darauffolgenden zweiten Read usw.
  - Datenknoten werden niemals aus der Datenbank gelöscht, auch wenn die
    Objekte nicht mehr existieren. Eine gelöschte Annotation wird in die
    Kette von inaktiven Annotationen eingefügt. Solche Aktionen sind relativ
    aufwändig für das GAP4-Programm: Die Datenkette erhält zunächst eine
    "Umgehungsstraße", die den Knoten, der entfernt werden soll, von der
    Datenkette isoliert. Der freie Knoten wird anschließend durch Umlenken
    der Verweise in die Kette inaktiver Annotations-Datenknoten eingefügt.
    Wenn bei dieser Aktion ein Abbruch oder Fehler auftritt, ist die GAP4-
    Datenbank meist inkonsistent. Das Löschen einer Annotation ist eine
    häufige Ursache von Datenbankinkonsistenzen.
  Hält man sich diese Datenstrukturen vor Augen, lassen sich Fehlerbeschrei-
  bungen wie "Endlosschleife in einer Verweiskette", "verlorener Daten-
  knoten" besser verstehen.

Eine Reparatur der Fehler ist immer angeraten, weil sie oftmals Folgefehler
nach sich ziehen. Oft können bestimmte GAP4-Funktionen nicht mehr ausgeführt
werden, wenn die Datenbank Fehler aufweist. Eine Fehlerkorrektur von nicht-
durchgängigen Contigs ist manchmal im Contig-Editor möglich, indem man die
Reads, die die Lücke flankieren, durch Aufdecken von "hidden data" verlängert.
Für die Einsicht und Reparatur interner GAP4-Datenbankfehler wird vom Staden-
Package die Dialogfunktion "doctor database" zur Verfügung gestellt. Sie wird
allerdings nur Anwendern empfohlen, die sehr genau wissen, was sie tun. Es
besteht die große Gefahr, dass nach einer Manipulation über "doctor database"
zusätzliche, möglicherweise gravierendere, Fehler auftreten.

Die Programmfunktion `Gap.pl -repair´ soll helfen, häufig auftretende GAP4-
Datenbankfehler zu beheben, ohne dass ein tieferes technisches Verständnis
notwendig ist. Die Funktion analysiert die Datenbank auf Konsistenz und
leitet, falls Inkonsistenzen gefunden werden, eine Fehlerkorrektur ein.
Die Fehlertypen, die durch das Programm entdeckt und behoben werden können,
sind im Einzelnen:
- Annotationen mit Positionen außerhalb des Read-/Contigbereichs
- Annotationen, die keiner Datenkette angehören ("annotation neither used nor
  free")
- Doppelverweise auf Annotationen (speziell Referenz-Loops)
- Annotationen, die nicht in der Reihenfolge ihrer Position sortiert sind
  ("annotation leftwards of ...")

COMMAND LINE SYNTAX
 Gap.pl -repair <gapdb.v>

arguments:
 gapdb.v       GAP4 database: (folder/)database.version

