[Best-Practice-Dokumentation] Project Medieval Maritime Predation: Project Phase 01.01.2024 – 31.05.2024

DMMP Project Phase 01.01.2024 – 31.05.2024

Persons involved

Project Group: Nikolas Jaspert (ZEGK, Principal Investigator), Victòria Burguera (ZEGK, Postdoctoral Researcher), Laurin Herberich (ZEGK, Doctoral Researcher), Silvia Girona Espino (ZEGK, Research Assistant 1), Viola Herschbach (ZEGK, Research Assistant 2), Nabi Bauermeister (ZEGK, Research Assistant 3)

IT-Team: Nils Weiher (UB), Leonhard Maylein (UB)

Extended Project Group: Leonhard Maylein (UB), Nils Weiher (UB), Nikolas Jaspert (ZEGK), Victòria Burguera (ZEGK), Laurin Herberich (ZEGK), Kilian Schultes (ZEGK), Dominic Kempf (SSC), Florian Nieser (HCDH)

Timeline of the Project

January 2024

• Chronology plugin test instance finished

February 2024

• DMMP beta update 1.1
• • Chronology plugin for all document and event OTs
  • Click boxes improve querying
  • Clarification hints for most fields
• “Georef” issue
• Elasticsearch errors
• “Missing Documents” issue
• “Deep search” issue
• Concepts “Actor”, “Undetermined amounts”, and “Causation” are redefined

March 2024

• Neo4j vs. Memgraph

April 2024

• “JSON size” issue

May 2024

• Elasticsearch errors
• DMMP beta Update 1.2:
• • Standard actor and NSP templates
  • Hierarchies in the natio and authority

Knowledge and data management

In January 2024 project phase four continued with the project group entering data and expanding the DMMP model where necessary. The information contained in hitherto underutilised primary sources was a guiding hand pushing the data entry UI closer to reflecting the reality of the documentary record. Meanwhile the IT-team was getting closer to testing the next step to turn the DMMP into a more effective tool for the analysis of medieval documents. Since July 2023 they had been working on a chronology plugin, which would simplify the visualisation of historical data recorded according to different calendars. After testing said plugin in a dummy instance and adapting it to deal with the third day before the Kalendae of January especially, the chronology plugin was included in the second major update package for the DMMP beta after Update 1.0 in November 2023. Apart from introducing the chronology plugin for all document and event OTs as well as improving semantic coherency, Update 1.1 made querying easier by adding click boxes (to filter out regests, stolen and sold vessels, interreligious and intrareligious wars, or unspecified amounts in instructions) and most importantly improved the user experience by providing almost every field with clarification hints. Once live in mid-February 2024, Update 1.1 allowed for faster data entry especially by the student members of the project group.

In February, the project group and IT-team faced two minor and two major issues. The first was the “Georef” issue which had been undiscovered since Version 1.0 and caused crucial polygonal geographical references to go unsaved in the respective events, thus, necessitating their manual reintroduction. While the IT-team was able to solve this issue by updating the responsible plugin on the day of its discovery, the second minor issue proofed more persistent. Since the beginning of large-scale data entry in July 2023, members of the project group experienced the occasional “elastic search error”. Innocuous for the longest time, these errors grew more prevalent throughout January until data entry had to stop completely from 19 to 20 February. Only equally persistent counter measures by the IT-team finally stemmed the tide and while data entry continued undisturbed for the most part, on 8 May another series of “elastic search errors” had to be, and quickly was, dealt with. While the minor issues caused some delay but remained otherwise inconsequential, the two major issues had far-reaching repercussions for the whole project.

First, a familiar issue made its comeback. The “DT/EV” issue had been solved in June 2023 (cf. best practice report 01/30/2022 – 07/31/2023) by linking, say, a person object appearing in an event to a document via a connecting “Helper Object” containing event and document object, thus, displaying both event OTs and document OTs in a NSPs profile. While solved from a technical standpoint, a bug in easydb caused the issue to prevail in a limited form for document OTs, which are now displayed when conducting a general search for a person appearing in an event mentioned in the document, but are not displayed in the same person’s profile. This bug, though known to Programmfabrik, still affects every NSP (Natio, Dominion, Authority, Corporation, Type of Vessel, Goods, Currency and crucially Person) that is not part of the document head, making it more difficult to find e.g. a person’s documentary footprint.

A second, more serious challenge was posed by the so called “Deep Search” issue, as it went to the core of the easydb-system’s capabilities. Going through questions laid out at the beginning of the funding period, the project group realised that easydb could not answer questions requiring it to relate OTs (e.g. attacks) with non-OTs (e.g. predators). Thus, questions like “Who was a maritime predator?” were out of scope without sifting through every person involved in an attack, be they victim, bystander, issuer of a related document, receiver of the latter, or, indeed, predator. For “Deep Searches” to be possible, NSPs like “predator” and “victim” would have had to be introduced into the DMMP. While solving the issue on a surface level, additional NSPs describing a person would have clashed with the “person” NSP, as one individual could have appeared twice in the database, once as a “person” and once as a “predator”. The resulting exponential growth of NSP objects describing historical persons would have rendered tracking social careers of individual maritime predators near impossible and, thus, jeopardised a core aim of the DMMP as a whole.

The IT-team solved both findability issues by acknowledging the weaknesses and playing into the strengths of easydb. Instead of using it as a one-stop-solution, easydb would from now on serve as a data entry point and “backend” API and while data navigation would be relegated to more capable software, both would be tied together by a custom-made UI. Agreed upon on 22 February, this solution was successfully pursued over the remainder of phase four by the IT-team, allowing the project group to continue the already established mass data entry process in the easydb framework.

A consequence and, in fact, additional benefit brought about by mapping the DMMP model in dedicated data navigation software was the need to specify certain concepts which had remained broadly defined up to this point. Three concepts are most illustrative here. First, what constitutes an “actor” in any given event was not entirely clear in the easydb model. Attacks were sometimes linked to a perpetrating person sometimes to a perpetrating corporation. Clarification meant in this case to specify that attacks are committed either by a named person, reflected as an easydb person object, or an anonymous person, reflected in the easydb not by an object, but a set of attributes in a nested table, e.g. a corporation and an indication of perpetrator amount. Actors reflected by sets of attributes would be mapped in the data navigation software as “Anonymous”. A second concept in need of clarification was the “undetermined amount”. If a number of actors was given in a source as e.g., “several”, the project group had opted to enter the translated source term into the “amount” field. To simplify calculations with the new navigation software, this solution was redefined as meaning at least two and affected entries were marked via clickbox. Thirdly, the concept of “causation” had to be revised to be stricter. Where in easydb every event in a chain of events was linked to every event in that chain, the bird’s eye view of the new navigation tool would allow for linkage of strictly direct causational relations.

While the decision on the future data navigation tool had come down to essentially Memgraph or Neo4j by late March, by late April the IT-team had opted for the Neo4j graph database tool as the option to go forward with. To allow the project group to design query templates in the designated language Cypher, it was now crucial to finalise the DMMP model in easydb to map it fully in Neo4j. Having started right after Update 1.1 in mid-February, the project group had continued work on Update 1.2 and completed the final version of the model by the end of March. Implementation went smoothly and even when the DMMP model had outgrown the limitations imposed by Programmfabrik on permissible JSON files, support was able to offer a workaround the very same day. Update 1.2 for the DMMP beta went live on 3 May 2024 and introduced three major improvements. The large-scale implementation of repeatable fields strengthened the DMMP’s resilience to unforeseen amounts in primary sources and, thus, its flexibility. Equally proactive were the hierarchies introduced for the “natio” and “authority”-NSPs, as they promised to streamline query results in Neo4j by subsuming smaller into larger NSPs where necessary. Finally, the introduction of standard actor and NSP templates to the easydb model not only simplified future data entry, but also a great deal of the foreseeable queries in Neo4j. With the implementation of Update 1.2 the model received its third and last major update and was, thus, ready for transfer. Anticipating its completion, IT started to brief the principal investigators on the basics of the Cypher query language from 22 May on. One week later online access to the Neo4j Browser had been enabled, allowing for test queries and troubleshooting while data entry continues.

 

Collaboration/Communication within the project

The challenges faced in the phase four’s second half necessitated flexible and consistent communication. In retrospect, both project group and IT-team met especially the first requirement by meeting, when necessary, at the day an issue occurred or within a few days, if major decisions had to be made. This was less essential in January, but absolutely crucial one month later when the two findability issues demanded immediate action.

Unlike in the previous three phases, phase four was characterised by a lack of distinction between online as well as offline meetings. As issues tended not to occur at predictable intervals, but required attention and group effort nonetheless, especially Victòria Burguera, Nils Weiher, and Laurin Herberich met at times within a moment’s notice. This quick personal response was supported by extensive email exchanges between all members of project group and IT-team without which the timely implementation of smaller fixes and large updates would have been impossible. All of the design relevant communication was additionally and continuously recorded in gitlab.

With at least three meetings per month over a period of five months, with a peak in February where project group and IT-team met five times, the second half of phase four marked a return to the high frequency of meetings of phase three. Where phase one and especially two had relied on more electronic communication than the latter, phase four combined both email and personal (offline and online) communication efforts and might have been the most communicative phase yet.

 

Figure 1: Chronology Plugin

Figure 2: Clarification Hints

Figure 3: Georef Issue

Figure 4: Elasticsearch Error

Figure 5: Standard Template Perpetrator

Figure 6: Standard Template Prisoner

Figure 7: Standard Template Target

Figure 8: Standard Template Victim

Figure 9: Neo4j Dashboard Visualisation

— Deutsche Version —

 

DMMP Projektphase 01.01.2024 – 31.05.2024

Involvierte Personen

Project Group: Nikolas Jaspert (ZEGK, Principal Investigator), Victòria Burguera (ZEGK, Postdoctoral Researcher), Laurin Herberich (ZEGK, Doctoral Researcher), Silvia Girona Espino (ZEGK, Research Assistant 1), Viola Herschbach (ZEGK, Research Assistant 2), Nabi Bauermeister (ZEGK, Research Assistant 3)

IT-Team: Nils Weiher (UB), Leonhard Maylein (UB)

Extended Project Group: Leonhard Maylein (UB), Nils Weiher (UB), Nikolas Jaspert (ZEGK), Victòria Burguera (ZEGK), Laurin Herberich (ZEGK), Kilian Schultes (ZEGK), Dominic Kempf (SSC), Florian Nieser (HCDH)

Bisheriger zeitlicher Verlauf des Projekts

Januar 2024

• Testinstanz des Chronologie-Plugins fertiggestellt

Februar 2024

• DMMP Beta-Aktualisierung 1.1
• „Georef”-Problem
• Elasticsearch-Fehler
• Problem „Fehlende Dokumente”
• Problem mit der „Tiefensuche”
• Konzepte „Akteur“, „Unbestimmte Beträge“ und „Ursache“ neu definiert

März 2024

• Neo4j vs. Memgraph

April 2024

• „JSON-Größe”-Problem

Mai 2024

• Elasticsearch-Fehler
• DMMP Beta Update 1.2:
• Standardakteure und NSP-Vorlagen
• Hierarchien in der natio und authority

Wissens- und Datenmanagement

Im Januar 2024 wurde Projektphase vier fortgesetzt, wobei die Projektgruppe Daten eingab und das DMMP-Modell bei Bedarf erweiterte. Die in bisher ungenutzten Primärquellen enthaltenen Informationen dienten als leitende Hand und brachten die Daten-Erfassungs-UI näher an die Realität der dokumentarischen Aufzeichnungen. Währenddessen arbeitete das IT-Team daran, den nächsten Schritt zu testen, um die DMMP zu einem effektiveren Werkzeug für die Analyse mittelalterlicher Dokumente zu machen. Seit Juli 2023 wurde an einem Chronologie-Plugin gearbeitet, das die Visualisierung historischer Daten, die nach verschiedenen Kalendern aufgezeichnet wurden, vereinfachen sollte. Nach der Testung des Plugins in einer Dummy-Instanz und der Verfeinerung der Aufnahme auch komplizierter Daten, wie des dritten Tages vor den Kalenden des Januars, wurde das Chronologie-Plugin in das zweite große Update-Paket für die DMMP-Beta nach Update 1.0 im November 2023 aufgenommen. Neben der Einführung des Chronologie-Plugins für alle Dokument- und Ereignis-OTs sowie der Verbesserung der semantischen Kohärenz, vereinfachte Update 1.1 die Datenauslese durch das Hinzufügen von Clickboxen (zum Filtern von Regesten, gestohlenen und verkauften Schiffen, interreligiösen und intrareligiösen Kriegen oder unbestimmten Beträgen in Anweisungen) und verbesserte vor allem die Benutzerfreundlichkeit durch Bereitstellung von Klärungshinweisen für fast jedes Feld. Nach der Veröffentlichung im Februar 2024 ermöglichte Update 1.1 eine schnellere Dateneingabe, insbesondere durch die studentischen Mitglieder der Projektgruppe.

Im Februar standen Projektgruppe und IT-Team vor zwei kleineren und zwei größeren Problemen. Das erste war das „Georef“-Problem, das seit Version 1.0 unentdeckt geblieben war und dazu führte, dass wichtige polygonale geografische Referenzen in den jeweiligen Ereignissen nicht gespeichert wurden und daher manuell neu eingeführt werden mussten. Während das IT-Team dieses Problem durch ein Update des verantwortlichen Plugins am Tag seiner Entdeckung lösen konnte, erwies sich das zweite kleinere Problem als hartnäckiger. Seit Beginn der groß angelegten Dateneingabe im Juli 2023 traten bei den Mitgliedern der Projektgruppe gelegentlich „Elasticsearch-Fehler“ auf. Diese Fehler, die lange Zeit harmlos waren, nahmen im Januar zu, bis die Dateneingabe am 19. und 20. Februar vollständig gestoppt werden musste. Nur durch gleichsam hartnäckige Gegenmaßnahmen des IT-Teams konnte die Flut schließlich eingedämmt werden, und obwohl die Dateneingabe größtenteils ungestört fortgesetzt wurde, musste am 8. Mai eine weitere Serie von „Elasticsearch-Fehlern“ schnell behoben werden. Während die kleineren Probleme einige Verzögerungen verursachten, aber ansonsten unbedeutend blieben, hatten die beiden größeren Probleme weitreichende Auswirkungen auf das gesamte Projekt.

Zuerst kehrte ein bekanntes Problem zurück. Das „DT/EV“-Problem war im Juni 2023 (vgl. Best-Practice-Bericht 01/30/2022 – 07/31/2023) gelöst worden, indem ein Personenobjekt, das in einem Ereignis auftauchte, über ein verbindendes „Helfer Objekt“ mit einem Dokument verknüpft wurde, das sowohl Ereignis-OTs als auch Dokument-OTs im Profil eines NSPs anzeigte. Obwohl das Problem technisch gelöst war, führte ein Fehler in easydb dazu, dass das Problem in begrenzter Form für Dokument-OTs bestehen blieb, die nun bei einer allgemeinen Suche nach einer Person, die in einem im Dokument erwähnten Ereignis auftrat, angezeigt werden, aber nicht im Profil derselben Person. Dieser Fehler, welcher der Programmfabrik bekannt ist, betrifft weiterhin jeden NSP (Natio, Herrschaft, Behörde, Corporation, Schiffstyp, Waren, Währung und vor allem Person), der nicht Teil des Dokumentkopfs ist, was die Auffindbarkeit z.B. des dokumentarischen Fußabdrucks einer Person erschwert.

Eine zweite, schwerwiegendere Herausforderung stellte das sogenannte „Deep Search“-Problem dar, da es die Kernfähigkeiten des easydb-Systems betraf. Beim Durchgehen der zu Beginn des Förderzeitraums gestellten Fragen stellte die Projektgruppe fest, dass easydb keine Fragen beantworten konnte, die eine Beziehung zwischen OTs (z.B. Attacken) und Nicht-OTs (z.B. Seeräuber) erforderten. Fragen wie „Wer war ein Seeräuber?“ waren daher außer Reichweite, ohne jede in einen Angriff verwickelte Person zu prüfen, ob Opfer, Zuschauer, Aussteller eines verwandten Dokuments, Empfänger desselben oder eben Räuber. Um „Deep Searches“ möglich zu machen, hätten NSPs wie „Räuber“ und „Opfer“ in die DMMP eingeführt werden müssen. Damit hätte die Lösung des Problems zusätzliche NSPs zur Beschreibung einer Person bedeutet. Dies wäre allerdings mit dem „Personen“-NSP kollidiert, da eine Person zweimal in der Datenbank aufgetreten wäre, einmal als „Person“ und einmal als „Seeräuber“. Das daraus resultierende exponentielle Wachstum von NSP-Objekten zur Beschreibung historischer Personen hätte aber die Verfolgung sozialer Karrieren einzelner Seeräuber nahezu unmöglich gemacht und damit ein zentrales Ziel der ganzen DMMP gefährdet.

Das IT-Team löste beide Auffindbarkeitsprobleme, indem es die Schwächen der easydb erkannte und seine Stärken nutzte. Anstatt easydb als All-in-One-Lösung zu verwenden, sollte es nun als Datenerfassungspunkt und “Backend”-API dienen, während die Datennavigation auf leistungsfähigere Software verlagert wurde. Beide sollten durch eine maßgeschneiderte Benutzeroberfläche verbunden werden. Diese Lösung, die am 22. Februar vereinbart wurde, wurde vom IT-Team im restlichen Verlauf der Phase vier erfolgreich verfolgt, wodurch die Projektgruppe den bereits etablierten Massen-Datenerfassungsprozess im easydb-Rahmen fortsetzen konnte.

Eine Folge und in der Tat Vorteil, der durch die Abbildung des DMMP-Modells in dedizierter Daten-Navigationssoftware entstand, war die Notwendigkeit, bestimmte Konzepte, die bis zu diesem Zeitpunkt breit definiert waren, zu präzisieren. Drei Konzepte sind hier besonders illustrativ. Erstens war nicht ganz klar, was einen „Akteur“ in einem bestimmten Ereignis ausmacht. Angriffe wurden manchmal einer verantwortlichen Person und manchmal einer verantwortlichen Korporation zugeordnet. Klärung bedeutete in diesem Fall, dass Angriffe entweder von einer namentlich genannten Person begangen werden, die als easydb-Personenobjekt reflektiert wird, oder von einer anonymen Person, die in easydb nicht als Objekt, sondern als Attributsatz in einer „nested table“, z.B. eine Korporation und eine Angabe zur Täteranzahl, reflektiert wird. Akteure, die durch Attributsätze reflektiert werden, sollten in der Daten-Navigationssoftware als „Anonymi“ abgebildet werden. Ein zweites Konzept, das einer Klärung bedurfte, waren „unbestimmte Anzahlen“. Wenn eine Anzahl von Akteuren in einer Quelle z.B. als „mehrere“ angegeben wurde, hatte die Projektgruppe den übersetzten Quellenbegriff in das Feld „Anzahl“ eingegeben. Um Berechnungen mit der neuen Navigationssoftware zu vereinfachen, wurden diese „mehrere“ nun als mindestens zwei definiert und betroffene Einträge wurden über eine Clickbox markiert. Drittens musste das Konzept der „Kausalität“ strenger gefasst werden. Während in easydb jedes Ereignis in einer Ereigniskette mit jedem Ereignis in dieser Kette verknüpft war, ermöglichte die Vogelperspektive des neuen Navigationstools die Abbildung von strikt direkten kausalen Beziehungen.

Während die Entscheidung über das zukünftige Daten-Navigationstool Ende März im Wesentlichen auf Memgraph oder Neo4j hinauslief, entschied sich das IT-Team Ende April dafür das Graphdatenbank-Tool Neo4j weiterzuverfolgen. Um der Projektgruppe zu ermöglichen, Abfragevorlagen in der vorgesehenen Sprache Cypher zu erstellen, war es nun entscheidend, das DMMP-Modell in easydb vollständig abzuschließen, um es vollständig in Neo4j abzubilden. Nachdem die Arbeiten an Update 1.2 Mitte Februar begonnen hatten, setzte die Projektgruppe diese fort und schloss die endgültige Version des Modells Ende März ab. Die Implementierung verlief reibungslos und selbst als das DMMP-Modell die von Programmfabrik auferlegten Beschränkungen für zulässige JSON-Dateien überschritt, konnte der Support noch am selben Tag eine Lösung anbieten. Update 1.2 für die DMMP-Beta wurde am 3. Mai 2024 live geschaltet und führte drei wesentliche Verbesserungen ein. Die großflächige Implementierung wiederholbarer Felder stärkte die Resilienz der DMMP gegenüber unvorhergesehenen Mengen in Primärquellen und damit ihre Flexibilität. Ebenso proaktiv waren die Hierarchien, die für die „natio“- und „authority“-NSPs eingeführt wurden, da sie versprachen, Abfrageergebnisse in Neo4j zu vereinfachen, indem kleinere NSPs bei Bedarf in größere subsumiert würden. Schließlich vereinfachte die Einführung von Standardakteur- und NSP-Vorlagen in das easydb-Modell nicht nur die zukünftige Dateneingabe, sondern auch viele der vorhersehbaren Abfragen in Neo4j erheblich. Mit der Implementierung von Update 1.2 erhielt das Modell sein drittes und letztes großes Update und war damit bereit für den Transfer. In Erwartung seiner Fertigstellung begann das IT-Team am 22. Mai damit, die Hauptuntersucher in die Grundlagen der Cypher-Abfragesprache einzuführen. Eine Woche später wurde der Online-Zugriff auf den Neo4j-Browser aktiviert, was Testabfragen und Fehlerbehebung ermöglichte, während die Dateneingabe fortgesetzt wurde.

Abbildung 1: Chronologie Plugin

Abbildung 2: Erläuterungen

Abbildung 3: Georef Problem

Abbildung 4: Elasticsearch Fehler

Abbildung 5: Standardvorlage Perpetrator

Abbildung 6: Standardvorlage Prisoner

Abbildung 7: Standardvorlage Target

Abbildung 8: Standardvorlage Victim

Abbildung 9: Neo4j Dashboard Visualisierung

Zusammenarbeit/Kommunikation innerhalb des Projektes

Die Herausforderungen in der zweiten Hälfte von Phase vier erforderten flexible und konsistente Kommunikation. Rückblickend erfüllten sowohl die Projektgruppe als auch das IT-Team besonders die erste Anforderung, indem sie sich bei Bedarf am Tag des Auftretens eines Problems oder innerhalb weniger Tage trafen, wenn wichtige Entscheidungen getroffen werden mussten. Dies war im Januar weniger entscheidend, aber einen Monat später absolut notwendig, als die beiden Auffindbarkeitsprobleme sofortige Maßnahmen erforderten.

Im Gegensatz zu den vorherigen drei Phasen war Phase vier durch das Fehlen einer Unterscheidung zwischen Online- und Offline-Meetings gekennzeichnet. Da Probleme nicht in vorhersehbaren Abständen auftraten, aber dennoch Aufmerksamkeit und Gruppenarbeit erforderten, trafen sich insbesondere Victòria Burguera, Nils Weiher und Laurin Herberich relativ spontan. Diese schnelle persönliche Reaktion wurde durch umfangreiche E-Mail-Kommunikation zwischen allen Mitgliedern der Projektgruppe und des IT-Teams unterstützt, ohne welche die zeitnahe Umsetzung kleinerer Korrekturen und großer Updates unmöglich gewesen wäre. Alle designrelevanten Kommunikationsprozesse wurden zusätzlich und kontinuierlich in GitLab dokumentiert.

Mit mindestens drei Meetings pro Monat über einen Zeitraum von fünf Monaten, mit einem Höhepunkt im Februar, als sich die Projektgruppe und das IT-Team fünfmal trafen, markierte die zweite Hälfte von Phase vier eine Rückkehr zur hohen Meeting-Frequenz von Phase drei. Während Phase eins und besonders Phase zwei mehr auf elektronische Kommunikation gesetzt hatten, kombinierte Phase vier sowohl E-Mail- als auch persönliche (offline und online) Kommunikationsbemühungen und könnte die kommunikativste

---

---