Eine README-Datei ist ein zentraler Bestandteil des Replication Packages. Viele führende wirtschaftswissenschaftliche Fachzeitschriften, darunter die Journals der American Economic Association (AEA), verlangen sie bereits heute bei jeder Einreichung. Mit den richtigen Templates und einer klaren Struktur lässt sich die Datei in überschaubarem Aufwand erstellen. In diesem Beitrag erklären wir, wie man dabei am besten vorgeht.
Eine README-Datei dient als Leitfaden des Replication Packages – der Sammlung aller Materialien, die notwendig sind, um die Ergebnisse eines empirischen Forschungsartikels unabhängig nachvollziehen zu können. Sie erläutert dessen Inhalt und erklärt, wie die vorliegenden Forschungsergebnisse reproduziert werden können. Ohne diese Datei verlieren selbst vollständig geteilte Daten und Code einen Großteil ihres Wertes. Was eine README-Datei genau ist, erläutern wir ausführlich an anderer Stelle. Im Folgenden soll es nun um die praktische Umsetzung gehen: Wir geben zunächst grundsätzliche Tipps und erklären dann, worauf Sie bei den einzelnen Bestandteilen achten sollten. Dieser Beitrag orientiert sich dabei inhaltlich stark an der Präsentation von Lars Vilhuber, dem Data Editor der AEA.
- Schreiben Sie eine vollständige README-Datei – auch bei unvollständigen Daten
Eine README-Datei ist nicht nur dann nötig, wenn alle verwendeten Daten im Replication Package enthalten sind. Auch wenn Daten vertraulich oder proprietär sind und deshalb nicht beigefügt werden können, ist sie essenziell: Denn die Datei beschreibt in einem solchen Fall, woher die Daten stammen und wie man Zugang zu ihnen erhält.
- Starten Sie so früh wie möglich
Legen Sie die README-Datei direkt zu Beginn Ihres Forschungsprojektes an und ergänzen Sie sie laufend. Denn eine Notiz ist schnell hinzugefügt, während es oft zeitaufwändig (und lästig) ist, Informationen später zu rekonstruieren.
- Nutzen Sie ein Template
Eine Reihe von Templates erleichtert Ihnen das Erstellen der README-Datei. Das Template der Social Science Data Editors gilt in den Wirtschaftswissenschaften als De-facto-Standard und wird von führenden Fachzeitschriften wie den Journals der AEA oder dem Review of Economic Studies empfohlen. Das statische Template ist in den Formaten HTML, Markdown, Word, LaTeX und PDF verfügbar. Wer das Template lieber interaktiv ausfüllen möchte, nutzt den Online-Generator templatereadme.org. Eine noch kompaktere Variante bietet das World Bank README Template. Passen Sie das Template an Ihr Package an und prüfen Sie die Data-Policy-Seite des Journals, in dem Sie veröffentlichen möchten. Manche Fachzeitschriften stellen dafür eigene Checklisten oder Formatvorgaben bereit.
- Testen Sie Ihre README-Datei
Eine gute Empfehlung ist es, Ihre eigenen Ergebnisse vor Einreichung des Beitrags allein auf Basis der README-Datei zu reproduzieren – idealerweise in einem leeren Ordner oder auf einem anderen Rechner. Dies ist der zuverlässigste Weg, um Lücken in Ihrer Beweisführung zu identifizieren.
Worauf es bei den Bestandteilen einer README-Datei ankommt
- Überblick
Beginnen Sie mit einer knappen Beschreibung der verwendeten Materialien und einer kurzen Anleitung, wie die Vorgehensweise bei einer Reproduktion der Forschungsergebnisse von Anfang bis Ende aussieht: Welche Ordner befinden sich im Replication Package? Welche Dateien sind darin enthalten? Wie und wofür lassen sie sich nutzen und mit welcher Software?
! Stellen Sie sich dabei vor, Sie würden Ihr Projekt selbst zum ersten Mal sehen.
- Data and Code Availability Statement (DCAS)
Legen Sie die Herkunft aller verwendeten Daten sowie den Quellcode, der sich bei den meisten wirtschaftswissenschaftlichen Journals im selben Paket befindet, lückenlos offen. Wenn diese Informationen bereits ausführlich im Anhang zu finden sind, verweisen Sie an dieser Stelle darauf. Anders als eine Datenzitierung – die lediglich angibt, wo Daten zu finden sind – beschreibt das DCAS, was konkret zu tun ist, um Zugriff auf die Daten zu erhalten. Zu diesem Zweck enthält es etwa auch Angaben zu nötigen Registrierungen und Mitgliedschaften oder zu den Kosten. Es sollten sowohl die Bedingungen beschrieben werden, unter denen Sie als Autor:in auf die Daten zugreifen konnten, als auch die Voraussetzungen, unter denen Dritte künftig darauf zugreifen können.
! Dies gilt auch für Daten, die nicht im Paket enthalten sind.
! Bei selbst erhobenen Daten beschreiben Sie den Erhebungsprozess, also zum Beispiel Instruktionen, Fragebogen und Auswahlkriterien der Teilnehmenden.
- Statement about Rights
Bestätigen Sie ausdrücklich, dass Sie (1) auf die Daten zugreifen und diese rechtmäßig verwenden durften und (2) berechtigt sind, die im Paket enthaltenen Daten weiterzugeben.
! Nutzungsrechte sind nicht automatisch Verbreitungsrechte. Auch, wenn Daten öffentlich heruntergeladen werden können, bedeutet das nicht automatisch, dass sie auch uneingeschränkt weitergegeben werden dürfen. Entscheidend sind hier die Nutzungsbedingungen oder die jeweilige Lizenz.
- Systemanforderungen
In diesem Abschnitt geben Sie an: die verwendete Software und Zusatzpakete, einschließlich der genutzten Versionen und deren Abhängigkeiten (zum Beispiel „Paket A benötigt Paket B in Version X“); die technischen Daten der verwendeten Hardware (Prozessor, Arbeitsspeicher, Speicherplatz, Betriebssystem) und die voraussichtliche Laufzeit.
! Wenn rechtlich möglich, liefern Sie Softwarepakete direkt mit – insbesondere, wenn sie aus unversionierten Quellen wie GitHub-Repositorien oder persönlichen Webseiten stammen, die sich ändern oder verschwinden können.
! Am besten nutzen Sie Environments, die die gesamte Softwareumgebung fixieren und so Reproduzierbarkeit sicherstellen (etwa pip in Python, renv in R oder Conda). Für komplexere Anforderungen eignen sich auch Container-basierte Ausführungsumgebungen.
Schreiben Sie eine klare, chronologische Schritt-für-Schritt-Anleitung, wie die Reproduktion Ihrer Forschungsarbeit durchgeführt werden kann.
- Anleitung für die Reproduktion
! Verwenden Sie hier eine einfache, nummerierte Liste, keinen Fließtext.
! Wenn es mehr als vier bis fünf manuelle Schritte gibt, empfiehlt sich ein Master-Skript (zum Beispiel ein Makefile), das alle Schritte automatisch in der richtigen Reihenfolge ausführt.
- Verzeichnis der Tabellen und Programme
Erstellen Sie eine Tabelle, die zeigt, welches Skript – und möglichst welche Code-Zeile – welche Tabelle, Abbildung oder Zahl im Text erzeugt. Wenn nicht alle Ergebnisse reproduzierbar sind, muss das explizit ausgewiesen werden.
- Beschreibung der Programmdateien/des Codes
Geben Sie einen Überblick über die Programmdateien und deren Zweck: Was macht welches Skript? In welcher Reihenfolge sollten sie betrachtet werden?
! Entfernen Sie redundante oder veraltete Dateien aus dem Replication Package.
! Wählen Sie aktiv eine Lizenz für Ihren Code und dokumentieren Sie diese in einer separaten LICENSE.txt-Datei (ggf. zusammen mit der Datenlizenz).
- Referenzen
Zitieren Sie alle Daten, Pakete und sonstigen Quellen, auf die Sie sich in der README-Datei beziehen, idealerweise im Zitierstil Ihres ausgewählten Journals.
Tipp: Nicht alle Daten können offen geteilt werden. FAIR sollten sie aber trotzdem sein. Was das bedeutet und wie es gelingt, erklärt dieser Eintrag im Open Economics Guide.