## Your Paper is Only Half the Story For decades, the final output of a research project was a PDF. We poured months or years of work into a manuscript, submitted it, and the associated code and data gathered dust on a local hard drive. That era is over. Journals, funders, and fellow researchers now expect more than just the narrative; they expect the engine that produced the results. They want a **reproducible research package**. Creating one might sound like a chore you do at the very end of a project, but it's actually a mindset that improves your research from day one. Thinking about reproducibility from the start makes your work more organized, transparent, and trustworthy. It also makes your future self's life easier when you need to revisit an analysis six months later. This guide breaks down how to create a research compendium—a complete package of your data, code, and environment—that will satisfy reviewers, accelerate publication, and make your work more valuable to the scientific community. ## What is a Reproducible Research Package (or Research Compendium)? A reproducible research package, often called a "research compendium," is a collection of all the digital components of your study, organized so that another person can easily reproduce your results. It moves beyond the "what" of your findings to reveal the "how." Computational reproducibility means that given the same data and the same analysis code, anyone can generate the exact same figures, tables, and statistics that appear in your paper. The core principle is simple: separate your data, methods, and output. Think of it as delivering not just a cake, but the recipe, the ingredients, and a description of the oven you used. A well-structured package typically contains: * **Data:** Both the raw, untouched data and any cleaned or processed data. * **Code:** The scripts (e.g., in R or Python) that perform the analysis, generate figures, and produce tables. * **Documentation:** A README file that serves as the map to your project. * **Environment:** A specification of the software environment (e.g., package versions) needed to run the code. ## The Five Core Components of a Research Compendium Building a reproducible research package isn't about using one specific tool. It's about organizing your project files logically. Here is a battle-tested structure that works for most computational projects. ### 1. A Sensible Directory Structure Organization is the foundation. Instead of a single folder with dozens of cryptically named files, use a clear, conventional folder structure. A great starting point looks like this: ``` my-awesome-project/ ├── data/ │ ├── raw/ │ │ └── measurements.csv │ └── processed/ │ └── cleaned_data.csv ├── code/ │ ├── 01_data_cleaning.R │ ├── 02_analysis.R │ └── 03_figure_generation.R ├── output/ │ ├── figures/ │ │ └── figure1_scatterplot.png │ └── tables/ │ └── table1_summary_stats.csv ├── manuscript/ │ └── my_awesome_paper.docx ├── environment.yml └── README.md ``` This structure clearly separates inputs (`data`), processes (`code`), and results (`output`). It’s instantly understandable to a collaborator or reviewer. For an even deeper dive on organizing your project, check out our guide on [Git for researchers](/blog/git-your-research-together-a-beginners-guide-to-version-control/). ### 2. The Data (Raw and Tidy) Always, always keep your raw data read-only. Never edit it directly. Your data cleaning process should be a script that takes the raw data as input and produces a new, clean data file as output. This creates a transparent and auditable trail from raw measurements to final analysis. * **`data/raw/`**: This folder contains the original, untouched data. Once it's in here, never modify it. * **`data/processed/`**: This is where your scripted cleaning process saves its output. Your analysis scripts should only ever read from this folder. This separation is a core tenet of good [research data management](/blog/research-data-management-fair-guide/), ensuring the integrity of your source data. ### 3. The Code (Documented and Ordered) Your code tells the story of your analysis. * **Number your scripts:** Prefixing your script names with numbers (e.g., `01_`, `02_`) indicates the order in which they should be run. This removes ambiguity and makes your workflow explicit. * **Comment your code:** Explain the *why*, not just the *what*. Assume a colleague (or your future self) will be reading it. What was the purpose of that complex data transformation? Why did you choose that statistical test? * **Automate everything:** Avoid any manual steps, like opening a spreadsheet to delete a column. If a step is part of your analysis, it must be in a script. This ensures the entire process, from raw data to final figure, is captured. ### 4. The Environment Specification "It worked on my machine" is the enemy of reproducibility. Differences in software versions are a common reason why analyses fail to reproduce. You must precisely document the computational environment. * **For Python:** Create a `requirements.txt` or `environment.yml` file. This can be generated automatically with `pip freeze > requirements.txt` or `conda env export > environment.yml`. * **For R:** Use a tool like `renv` to create a `renv.lock` file that captures the exact versions of all the R packages you used. For ultimate reproducibility, you can use containers like Docker, which package the entire operating system and all its software into a self-contained unit. Services like Binder can then use this file to create an executable environment in the cloud that anyone can access with a single click. ### 5. The README File: Your Project's User Manual The README is arguably the most critical piece of documentation. It’s the first file someone will open, and it should guide them through the entire project. A great README file includes: * **Project Title and Author(s):** Who did this work? * **Brief Project Description:** What is the main research question? * **File Manifest:** A brief description of each file and folder. * **System Requirements:** What software is needed (e.g., Python 3.9, R 4.3)? Point to the environment specification file. * **Instructions for Reproduction:** Provide the exact, step-by-step commands needed to run the analysis from start to finish. Be explicit. ## How to Share Your Reproducible Research Package Once you've assembled your package, you need to share it in a way that is persistent and citable. While putting code on GitHub is great for collaboration, it's not a permanent archive. For publication, you should deposit your package in a trusted digital repository. * **Zenodo:** Integrates directly with GitHub. You can create a "release" on GitHub, and Zenodo will automatically archive it and issue a permanent Digital Object Identifier (DOI). * **Figshare:** Another excellent, widely used repository that provides DOIs. * **Open Science Framework (OSF):** A platform for managing and archiving the entire research lifecycle. Depositing your package in one of these repositories ensures it will be available for the long term. You then cite the DOI in your manuscript's "Code and Data Availability Statement," linking your paper directly to its underlying evidence. This practice is increasingly required by top journals. By making your research truly reproducible, you're not just ticking a box for a journal. You're adopting a workflow that makes your science more robust, transparent, and impactful. You're providing the full story, enabling others to build on your work and accelerating the pace of discovery.