Create a Research Package Journals Love

Your Paper Is Just the Advertisement

You’ve spent months, maybe years, on your research. The analysis is done, the narrative is polished, and the figures look sharp. You submit your manuscript to a top journal, feeling a sense of accomplishment. Then, the editor’s email arrives. It’s not a rejection, but it’s a demand: “Please provide a complete, reproducible research package for review.”

This request is no longer a niche suggestion from open-science advocates; it’s rapidly becoming a non-negotiable requirement for publication. An article about a computational result is just advertising. The real scholarship is the full software environment, code, and data that produced the result.

Many researchers treat this as a final, annoying chore. They zip up a messy folder of scripts with names like analysis_final_v3.R and figure_2_new.py, hoping it’s good enough. This is a mistake. A well-organized, truly reproducible research package doesn’t just get you past the editor; it builds trust with reviewers, increases the impact and citation of your work, and saves your future self from a massive headache.

This guide breaks down how to build a professional reproducible research package (often called a research compendium) that journals and reviewers will love.

What Exactly Is a Research Compendium?

A research compendium is more than a folder of files. It’s a logical, self-contained collection of every digital artifact needed to reproduce your work. Think of it as a complete lab notebook for your computational analysis. While formats can vary, every effective compendium separates three key components: data, code (methods), and output.

Here are the non-negotiable contents:

• Data: Both the raw, untouched data and the clean, processed data used in the analysis.
• Code: All scripts required to go from the raw data to the final figures and tables in your manuscript.
• Manuscript: The source file for your paper (e.g., a Markdown or LaTeX file).
• Environment Specification: A file that lists all software dependencies and their exact versions (requirements.txt, environment.yml, or a Dockerfile).
• Documentation: A README file that serves as the entry point, explaining what the project is and how to run the analysis.

The goal is simple: someone with a fresh computer should be able to download your package, follow a few simple instructions, and regenerate every number, table, and figure in your paper. Exactly.

The Anatomy of a Perfect Research Package

Stop thinking in terms of loose files and start thinking in terms of a structured project directory. A logical folder structure is the single most important element of a reproducible workflow. It’s instantly familiar to other researchers and makes your project easy to navigate.

Here is a battle-tested directory structure you can adapt for any project:

my-awesome-project/
├── .gitignore
├── README.md
├── LICENSE
├── environment.yml
│
├── manuscript/
│   ├── manuscript.Rmd
│   └── references.bib
│
├── data/
│   ├── raw/
│   │   └── raw_survey_data.csv
│   └── processed/
│       └── cleaned_data.csv
│
├── code/
│   ├── 01_clean_data.R
│   ├── 02_run_analysis.R
│   └── 03_generate_figures.py
│
└── output/
    ├── figures/
    │   ├── figure_1_scatterplot.png
    │   └── figure_2_histogram.png
    └── tables/
        └── table_1_summary.csv

Key Components Explained

• README.md: Your project’s front door. It should briefly explain the research question, list the contents of the package, and provide step-by-step instructions on how to reproduce the analysis. Crucially, it must state the order in which to run the scripts.
• LICENSE: Don’t forget this. A license clarifies how others can (and cannot) use your code and data. The MIT license is a great, permissive choice for code, while a Creative Commons license (like CC-BY) works well for data.
• environment.yml or Dockerfile: This is the recipe for your computational environment. An environment.yml file (for Conda) or a requirements.txt file (for Python’s pip) lists your software dependencies. A Dockerfile goes a step further by packaging the entire operating system environment, guaranteeing reproducibility anywhere. This is the gold standard.
• data/raw/: This folder should be treated as read-only. It contains the original data exactly as you received it. Never, ever edit files in this directory.
• data/processed/: Your data cleaning scripts (01_clean_data.R in this example) should take data from raw/ and save their clean, tidy output here. This folder can be deleted and regenerated at any time by running your code.
• code/: This is where your analysis lives. Numbering the scripts (e.g., 01_, 02_) is a simple but powerful way to indicate the order of execution. Each script should have a single responsibility: one cleans the data, another runs the statistical models, a third creates visualizations.
• output/: This folder holds the results of your analysis: figures, tables, and any other generated files. Like data/processed/, you should be able to delete this entire folder and regenerate it perfectly by running your code.

For a more streamlined process, you can find excellent tips on using computational notebooks in our post on From Data to Manuscript: A Guide to Computational Notebooks for Research.

How to Write Code for Other Humans (Including Your Future Self)

Reviewers and editors are not just checking if your code runs; they are evaluating the credibility of your methods. Clear, well-documented code signals that you have a deliberate and organized process.

Principles for Writing Reproducible Code

1. Use Relative Paths: Never use absolute file paths like C:/Users/MyUser/Desktop/project/data/raw_data.csv. This will break on anyone else’s machine. Always define paths relative to the project’s root directory.
2. Automate Everything: Your analysis should not require any manual steps. There should be no “open this file in Excel, copy column C, and paste it into a new file.” Every step, from data cleaning to figure generation, must be scripted. Tools like Make or Snakemake can help automate multi-step workflows.
3. Set Random Seeds: If your analysis involves any randomness (e.g., machine learning, bootstrapping, simulations), you must set a random seed at the beginning of your script. Without it, your results will change slightly every time the code is run, destroying reproducibility.
4. Document Dependencies: Explicitly list every package and library your code needs to run, along with the exact version number. Don’t rely on memory. Your environment.yml or equivalent file handles this.
5. Write a “Master” Script: For complex analyses, create a single script in the root directory (e.g., run_all.sh or main.R) that executes all the numbered scripts in the code/ directory in the correct order. This makes reproduction as simple as running a single command.

Using version control from day one is essential. Our Beginner’s Guide to Version Control with Git can help you get started.

Sharing Your Package: Repositories and DOIs

Once your package is organized, you need to share it effectively. Simply emailing a zip file is not a durable or professional solution. Journals expect you to deposit your package in a trusted public repository.

• GitHub/GitLab: Excellent for sharing the code itself and its development history. They are the de facto standard for version control.
• Zenodo, Figshare, or Dryad: These are archival repositories designed for long-term data preservation. A key feature is that they can assign a Digital Object Identifier (DOI) to your package. This makes your dataset and code a citable research output, just like your paper. You can even connect your GitHub repository to Zenodo so that each release is automatically archived and assigned a new DOI.

When you submit your paper, you will include a Data Availability Statement that links directly to your package in the repository using its DOI. This provides a permanent, verifiable link to your work.

Building a reproducible research package isn’t just about satisfying a journal requirement. It’s a fundamental part of producing robust, credible, and impactful science. It forces you to be more organized, makes collaboration easier, and leaves a clear trail for others, and your future self, to follow. The next time an editor asks for your data and code, you won’t have to scramble. You’ll be ready with a professional package that demonstrates the quality of your work before they even read the first page.