1 Start here

Use this chapter if you are about to submit a paper and need to get the code behind it ready to share. It covers the minimum steps to turn your project folder into an archive that someone else can download, open and run.

Work through the project roughly in this order: fix the paths and file types, annotate the scripts, write the README, and ask a colleague to run the whole thing. Then archive it and get a DOI. Archiving last means the DOI points to the version that has already been checked.

1.1 The pre-submission checklist

Try doing all of these to make the dog happy.

TADA covers your code. The data have their own short list. Tick every box and see what happens.

Code (TADA)

Condensed from the TADA guidelines.

Transferable — full chapter

• Every script is saved with a standard code extension (.R, .py, .cpp, …), not inside a .docx or .pdf
• No setwd() (R) or os.chdir() (Python) appears anywhere in the code
• No absolute paths (/Users/you/…, C:/Users/you/…) remain; paths are relative
• Data, code and materials all live in one project directory
• The project has been opened from a clean start and still runs

Available — full chapter

• Code is deposited in an immutable repository that mints a persistent identifier (Zenodo, Figshare, …)
• The DOI is cited in the manuscript text and reference list
• If the code was developed on GitHub, a release has been created and linked to Zenodo, since GitHub does not produce DOIs

Documented — full chapter

• A README.md (or README.txt) sits at the top of the project
• It names the manuscript, the authors, a contact address, and any funders
• It lists software and version (e.g. R v4.3.3) and key packages and versions (e.g. ggplot2 v3.5.1)
• It states the licence
• It says where the data are, ideally with their own DOI
• It says what each file is, what order to run things in, what the code needs and what it produces
• It flags anything slow or resource-hungry
• A licence is actually attached to the deposit

Annotated — full chapter

• Code is broken into labelled chunks
• Each chunk says what it does, why, and which result it produces
• Signposts point at the manuscript (“produces Figure 3B”, “Table 2, column 4”)

Before you submit — full chapter

• Someone else has run the whole project from the archived files, successfully
• set.seed() / random.seed() is set before anything stochastic (SORTEE Stage 6, Pick et al. 2026; not a TADA requirement; see Code review)

Data

This is the data counterpart to the code checklist, condensed from the SORTEE guidelines and the Data & code sharing chapter, where every point is explained in full.

Archived & citable — Available

• Data deposited in an immutable repository with a DOI, cited in the manuscript text and reference list
• Nothing lives only in supplementary material

Present & complete — what to share

• Raw data archived — or a sample plus the processed data, or a documented route to obtaining them
• Processed and filtered data archived, or the code that produces them

Interoperable format — file formats

• Data in .csv, .tsv, .txt or .parquet, not .xls, .sav or .pdf

Documented — metadata

• A data README or dictionary describes every file and every variable, with units
• Collection date and location, funders, and any derived-data sources are recorded

Licensed — data licences

• A data licence is chosen and stated (CC0 or CC BY are the usual choices)

The most useful check on this page is to download your own archived deposit into a fresh, empty folder, ideally on a different machine, and run it. It catches the failures the SORTEE guidelines group under Stage 5: wrong paths, missing packages and missing files (Pick et al. 2026). It will not catch Stage 6 failures, such as stochasticity and version sensitivity. Those need a seed and a documented environment.

1.2 A project layout that works

The two conventions in the tree below come from Ivimey-Cook et al. (2023, §3.1).

The layout itself is our own suggestion. The exact layout matters less than whether a reader can see the order and purpose of every file without asking you.

my-project/
├── README.md                 <- start here: what this is, how to run it
├── LICENSE                   <- how others may use the code
├── my-project.Rproj          <- or a Python virtual environment
├── data/
│   ├── raw/                  <- never edited by any script
│   │   └── caterpillars_2024.csv
│   └── processed/            <- written by 01_, read by 02_
│       └── caterpillars_clean.csv
├── R/                        <- or scripts/, or src/
│   ├── 01_clean_data.R
│   ├── 02_fit_models.R
│   └── 03_make_figures.R
├── functions/                <- helpers sourced by the scripts above
│   └── utils.R
└── output/
    ├── figures/
    └── models/               <- saved model objects for slow fits

Two conventions do most of the work.

1. Numbered scripts. A reader knows the order to run things in without being told: 01_, 02_, 03_.
2. data/raw/ is read-only. Cleaning writes to data/processed/. Raw data are never modified or overwritten by a script, so a botched cleaning step cannot destroy the original.

1.3 Three common causes of failure

The first two rows come from the TADA guidelines and the third from the SORTEE guidelines (Pick et al. 2026, Stage 6).

Mistake	Why it breaks	Fix
setwd("C:/Users/ed/Desktop/analysis")	The path exists on exactly one computer	Open the project through its .Rproj file, or start Python inside the project folder, and build paths with here() / pyprojroot
Code shared as a .pdf or .docx	Copy-pasting silently mangles apostrophes, quotes and whitespace, and drags in line numbers and headers	Save as .R / .py; see Transferable
No set.seed() before a simulation or MCMC run	Results change every run, so nobody can tell a real mismatch from noise	Set a seed at the top of each independently runnable section

1.4 The README

Copy templates/README-template.md into your project and replace the angle-bracketed parts. The Documented chapter explains each field and why it is there.

Or generate one with READMEBuilder (devtools::install_github("EIvimeyCook/READMEBuilder"), then build_readme()), a Shiny app that fills in these fields from your project and writes the README.md.

1.5 What happens next

If your target journal has a data editor, someone will check your deposit against something close to the SORTEE guidelines (Pick et al. 2026). These have six stages, from whether the code is archived under a licence to whether the results reproduce. Read that chapter to see what the checks are before they are applied to your submission.

If your journal has no data editor, the checks still matter. They fall to you and your co-authors, through code review.