A README file is a central component of every replication package. Many leading economics journals, including those of the American Economic Association (AEA), and a growing number of business journals require one with every submission. With the right templates and a clear structure, the file can be created without excessive effort. In this post, we explain how best to go about it.
A README file serves as a guide to the replication package – the collection of all materials needed to independently follow, reproduce, and replicate the results of an empirical research article. It explains the contents of the package and sets out, step by step, how the results can be reproduced. Without this file, even fully shared data and code lose much of their value. We explain in detail what a README file is elsewhere. This post focuses on practical implementation: we begin with some general tips and then explain what to look out for in each component. This post draws heavily on a presentation by Lars Vilhuber, Data Editor of the AEA.
- Write a Complete README File – Even When Data Are Incomplete
A README file is not only necessary when all the data used are included in the replication package. Even when data are confidential or proprietary and therefore cannot be attached, the file remains essential: in such cases, it describes the origin of the data and how access can be obtained.
- Start as Early as Possible
Create the README file at the very beginning of your research project and keep it up to date throughout the project.. Adding a note takes only a moment, whereas reconstructing information later is often time-consuming and tedious.
- Use a Template
A range of templates can make creating the README file easier. The Social Science Data Editors template is the de facto standard in economics and is recommended by leading journals such as those of the AEA and the Review of Economic Studies. The static template is available in HTML, Markdown, Word, LaTeX, and PDF formats. Those who prefer to fill in the template interactively can use the online generator templatereadme.org. A more compact variant is offered by the World Bank README Template.
Adapt the template to your package and check the data policy page of the journal in which you wish to publish. Some journals provide their own checklists or formatting requirements.
- Test Your README File
Before submitting your paper, try to reproduce your own results using only the README file – ideally in an empty folder or on a different computer. This is the most reliable way to identify gaps in your documentation.
Key Elements of a README File
- Overview
Begin with a concise description of the materials contained in the package and a brief guide on how to proceed from start to finish when reproducing the research results: Which folders are in the replication package? Which files does each contain? How can they be used and with which software?
! Imagine seeing your project for the very first time.
- Data and Code Availability Statement (DCAS)
Fully disclose the origin of all data used and the source code, which in most economics journals is included in the same package. If this information is already covered in detail in the appendix of the article, you may refer to it here. Unlike a data citation – which merely states where data can be found – the DCAS describes what needs to be done to gain access to the data. To this end, it also includes details such as required registrations, memberships, or costs. Both the conditions under which you as an author accessed the data and the requirements under which third parties may access it in future should be described.
! This also applies to data that are not included in the package.
! For data collected by the authors themselves (experiments, surveys), describe the data collection process – for example, instructions, questionnaires, and participant selection criteria.
- Statement about Rights
Confirm explicitly that you (1) were permitted to access and lawfully use the data, and (2) are entitled to share the data included in the package.
! Usage rights are not automatically distribution rights. Even if data can be downloaded publicly, this does not automatically mean they may be shared without restriction. What matters are the terms of use or the applicable licence.
- System Requirements
In this section, specify: the software and additional packages used, including the versions and their dependencies (for example, 'Package A requires Package B in version X'); the technical specifications of the hardware used (processor, memory, storage, operating system); and the estimated runtime.
! Where legally possible, include software packages directly in the package – particularly if they come from unversioned sources such as GitHub repositories or personal websites that may change or disappear.
! It is best to use environments that lock the entire software environment and thus ensure reproducibility (such as Conda in Python or renv in R). For more complex requirements, containers are also an option.
! If your estimation procedures involve random components, specify a fixed seed for the pseudo-random number generator and set it once in a central configuration script.
- Instructions for Reproduction
Write a clear, step-by-step guide on how to reproduce your research.
! Use a simple numbered list here, not continuous prose. ! If there are more than four or five manual steps, consider using a master script (for example, a Makefile) that runs all steps automatically in the correct order.
- List of Tables and Scripts
Create a table showing which script – and ideally which line of code – produces which table, figure, or number in the text. If not all results can be reproduced, this must be stated explicitly.
- Description of Programme Files / Code
Provide an overview of the programme files and their purpose: what does each script do, and in what order should they be executed?
! Remove redundant or outdated files from the replication package.
! Actively choose a licence for your code and document it in a separate LICENSE.txt file (together with the data licence if applicable).
- References
Cite all data, packages, and other sources referenced in the README file, ideally following the citation style of your chosen journal.
Tip: Not all data can be shared openly – but they should still be FAIR. What this means and how to achieve it is explained in this article on making data FAIR in the Open Economics Guide.