Replication Package README Template (DCAS, AEA)

Replication Package README: [Paper title]

README for the data and code package that accompanies an accepted empirical paper in economics or finance. It is built on the Data and Code Availability Standard (DCAS) version 1.0 (2022-12-15; M. Koren, M. Connolly, J. Lull and L. Vilhuber; Zenodo record licensed CC BY 4.0) and covers the elements the American Economic Association Data and Code Availability Policy (February 2026 version) requires in a README: data availability statements, package contents, computational requirements, run instructions, the mapping from programs to exhibits, data citations and declared omissions. Notes for the Journal of Finance and the Journal of Financial Economics were checked on their official pages in October 2026. Replace every [bracketed] value and every row marked Example. This is a document format, not legal advice on data licences or data protection.

Document control

Approvals

Revision history

Contents

1. Overview
2. Data availability and provenance statements
3. Dataset list
4. Computational requirements
5. Code and directory structure
6. Run instructions
7. Program-to-exhibit mapping
8. Data citations
9. Licences for code and data
10. Omissions, contact and acknowledgements
11. Compliance matrix (DCAS v1.0 and journal policy)
12. Pre-submission checklist
13. Glossary and references
14. Standard and licence note

1. Overview

[Summarise the package in four to six sentences. Example: The code in this package constructs the analysis data from four sources (CRSP, Compustat, I/B/E/S and a hand-collected file of broker closures) and produces all tables and figures in the paper and the Internet Appendix. The code is written in Python 3.12 and Stata 18. Three data sources are licensed and must be obtained by the replicator through a WRDS subscription; the hand-collected file is included. The master script runs in about 4 hours 10 minutes on a 2024 laptop with 16 GB of memory. The package also contains a pseudo dataset that lets the code run end to end without licensed data.]

2. Data availability and provenance statements

2.1 Rights to use and share the data

• The authors confirm that they obtained every dataset lawfully and were permitted to use it for this research.
• The authors hold written permission, kept on file, to publish each dataset that is placed in this package.

2.2 Availability at a glance

• Every dataset can be obtained by any member of the public.
• At least one dataset is licensed or restricted (list it in section 2.4 and section 10.1).
• None of the data can be published; only code and pseudo data are deposited.

2.3 Source-by-source access

For each licensed dataset write a short paragraph a replicator can act on: the product names, the exact tables or files, the date range, the date you downloaded the data and the query you used. Record the download date because vendors revise historical data.

Example: Data on stock returns come from the CRSP daily stock file (DS-001), accessed through WRDS on YYYY-MM-DD. The data are licensed and cannot be redistributed. Researchers with a WRDS subscription can run code/01_download_crsp.py with their own credentials to recreate the extract; the script lists every variable and filter.

2.4 Restricted, confidential and personal data

[If any data are confidential, describe who controls access, the application process, the expected time to approval, and whether a data editor or third-party replicator can be given access to verify results. State how long you will preserve the data and code, and where. Never place confidential or personal data in the deposit, including in log files or intermediate outputs.]

Journals handle restricted data differently: the Journal of Finance and the Journal of Financial Economics ask for pseudo data that let the code run when real data cannot be shared, and the AEA asks authors to explain access in the data availability statement and not to upload non-public data to the draft deposit. If you want to keep hand-collected data confidential for a period, tell the journal at first submission: the Journal of Finance asks for notice at initial submission, and the Journal of Financial Economics allows hand-collected data or code to be held back for up to two years if the editor is told at submission (the data still go to the editorial office). Check the current policy of your journal.

3. Dataset list

Describe variables and codebooks for every included dataset in docs/codebook.pdf or in a metadata file next to the data, with units, missing value codes and the meaning of identifiers.

4. Computational requirements

4.1 Software

Pin every package version in a lock file (requirements.txt, renv.lock, environment.yml) or bundle the packages in the deposit. If you provide a container, give the image name and digest.

4.2 Randomness

[State every random process (bootstrap, simulation, matching tie-breaks, train and test splits) and where the seed is set. Example: The seed is set to 20261025 in code/config.py; all scripts import it.]

4.3 Hardware and runtime

Check the total: 75 + 40 + 25 + 90 + 20 = 250 minutes, which is 4 hours 10 minutes.

5. Code and directory structure

replication-package/
  README.pdf                 # this document, exported
  LICENSE.txt                # code and data licences (section 9)
  run_all.sh                 # master script: runs every step in order
  code/
    config.py                # root path, seed, sample period
    00_setup.do              # installs Stata packages into code/ado
    00_make_pseudo.py        # creates the pseudo dataset
    01_download_crsp.py      # licensed data download (WRDS credentials)
    02_download_compustat.py
    03_download_ibes.py
    10_build_panel.py        # cleaning, merging, sample filters
    20_main.do               # Tables 2 to 5, Figure 1 estimates, text numbers
    30_robustness.do         # Tables 6 and 7, IA.1 to IA.8
    40_figures.py            # Figure 1
  data/
    raw/                     # inputs (licensed files not included)
    pseudo/                  # pseudo versions of licensed inputs
    analysis/                # created by code
  output/
    tables/                  # .tex and .csv tables
    figures/                 # .pdf figures
    logs/                    # one log per script
  docs/
    codebook.pdf

[Describe any program that is not obvious from its name. State that programs that transform raw data into analysis data are included, as well as programs that produce the exhibits; data editors check both.]

6. Run instructions

1. Obtain access to the licensed data listed in section 2.3 and place your WRDS user name in code/config.py (the password is requested at run time and never stored).
2. Edit the one root path in code/config.py.
3. Install the software in section 4.1: run setup.sh for Python and code/00_setup.do for Stata.
4. Run run_all.sh from the package root. It runs every script in section 5 in order and writes a log for each to output/logs/.
5. To test the code without licensed data, run run_all.sh --pseudo. Results will differ from the paper but every script should complete.
6. Compare output/tables/ and output/figures/ with the exhibits listed in section 7.

[State any manual step (for example a figure edited by hand, or a table assembled from two outputs) and why it cannot be automated.]

7. Program-to-exhibit mapping

8. Data citations

[List each dataset as a formal reference: provider, title, version or download date, distributor and persistent identifier or URL. Example: Center for Research in Security Prices. CRSP Daily Stock File. Accessed via Wharton Research Data Services on YYYY-MM-DD.]

[Cite the hand-collected dataset with its own DOI once the deposit is published, so that others can cite it separately from the paper.]

Cite software that the analysis depends on, with versions, where your journal encourages it.

9. Licences for code and data

Some repositories apply a default licence (the AEA's repository does, and Mendeley Data lets authors choose). Record the licence that actually applies to the published deposit.

10. Omissions, contact and acknowledgements

10.1 Omissions

10.2 Contact

[Name and email of the person who maintains the package. State that the authors are not obliged to provide support but will correct errors that are reported.]

10.3 Acknowledgements

[Thank research assistants who tested the package and any data provider that granted permission to share.]

11. Compliance matrix (DCAS v1.0 and journal policy)

Journal-specific notes, summarised in our own words from the official pages in October 2026 (check the current versions before deposit):

12. Pre-submission checklist

• A person outside the author team ran run_all.sh on a clean machine and reproduced every exhibit.
• Every exhibit and every number quoted in the text appears in section 7.
• Every dataset has a row in sections 2.3 and 3 and a citation in section 8.
• All package versions are pinned; the random seed is set once and documented.
• No absolute paths outside code/config.py.
• No credentials, personal data or licensed data in the deposit, including logs.
• Pseudo data run end to end where licensed data are omitted.
• Licences stated for code and shareable data.
• Omissions declared with reasons.
• README exported to PDF and placed in the top-level directory, if the journal asks for it.
• Deposit uploaded unzipped, if the repository requires it.
• General reproducibility checks done with the Reproducibility Checklist (science/reproducibility-checklist).

How to run the clean-machine test: copy the package exactly as it will be deposited to a computer or container that has never held the project, with only the software listed in section 4 installed. Give the tester the README and nothing else; do not answer questions by message, but note every question they ask, because each one marks a gap in the README. Have them run the master script, then compare every output with the paper using the program-to-exhibit map in section 7, digit by digit for tables and visually for figures. Record the date, the machine and any differences, and fix the README or the code before deposit. Common failures are a package installed globally on the author's machine but missing from the setup script, a path that only exists on the author's computer, a script that depends on a file created interactively, and outputs that differ in the last digit because a seed was set in one script but not in another.

13. Glossary and references

13.1 Glossary

13.2 References

• Koren, Miklós; Connolly, Marie; Lull, Joan; Vilhuber, Lars (2022). Data and Code Availability Standard (DCAS), version 1.0, 2022-12-15, DOI 10.5281/zenodo.7436134, datacodestandard.org (Zenodo record licensed CC BY 4.0; GitHub repository licensed CC0 1.0).
• American Economic Association, Data and Code Availability Policy, February 2026 version, aeaweb.org.
• American Finance Association, Journal of Finance, Data and Code Sharing Policy, 1 April 2024, afajof.org.
• Journal of Financial Economics, data and code sharing policy, jfinec.com.
• See also: the Social Science Data Editors' template README (GitHub, social-science-data-editors), which several journals recommend. It is licensed CC BY-NC 4.0, so this template does not reproduce or adapt its text; consult it directly.

Related templates: Empirical Finance Paper (academic/empirical-finance-paper), Event Study (academic/event-study), Pre-Analysis Plan (academic/pre-analysis-plan), Data Management Plan (science/data-management-plan) for planning data handling at the start of a project, and Reproducibility Checklist (science/reproducibility-checklist).

14. Standard and licence note

Based on the Data and Code Availability Standard (DCAS) version 1.0 (2022-12-15) by M. Koren, M. Connolly, J. Lull and L. Vilhuber, licensed CC BY 4.0 (Zenodo, DOI 10.5281/zenodo.7436134), whose 16 rules are listed by number and name in section 11 (the rule summaries are ours), and on the README elements listed in the American Economic Association Data and Code Availability Policy (February 2026). Journal of Finance and Journal of Financial Economics requirements are summarised in original words from their official policy pages as checked in October 2026. The Social Science Data Editors' template README (CC BY-NC 4.0) was not adapted. All text and the fictional example package are original; check the current version of the standard and of your journal's policy before deposit. Template licence: MIT.