Good practices for sharing research code

Description

Most research code lives on our laptops in a folder that grows organically over months or years. When the time comes to share it (for a paper, a collaboration, or just our future selves), the folder is hard to clean up and maybe the code does not run anymore. In this one-hour lecture we look at good practices for reproducible and reusable research code and learn how to improve our own repositories.

We will cover three things:

• What makes a good repository: README, license, structure, dependencies, reproducibility, citation metadata.
• Where and how to publish: GitHub, Zenodo for archiving and DOI, and the integration between the two.
• A demo of an AI-assisted repository reviewer that reads a repository and writes a plain-language report of what to fix before publishing.

The lecture is language agnostic and focuses on data analysis repositories rather than scientific software.

You’ll take home a checklist for your own repository, a portable prompt to run a similar audit with your AI tool of choice, and a list of existing tools and references to consult.

Slides in full screen     Download PDF slides

Publication checklist

The checklist from the talk, with examples and links for each item: Publication checklist.

Copy-paste AI prompts

The three prompts from the talk (draft a README, draft a data codebook, audit your repo) are on a separate page: AI prompts for your repository.

Resources

General

• Data- and code-archiving in the British Ecological Society journals: Overview of the state of code sharing, tips on how to structure projects and readmes
• An overview of publications and practical guides to create a research compendium
• The Turing Way: community handbook for reproducible research
• BES Guide to Reproducible Code
• Good enough practices in scientific computing
• Ten principles for reliable, efficient, and adaptable coding in psychology and cognitive neuroscience

Project structure & file naming

• rrtools (R) and computational notebooks (R): research-compendium templates
• Cookiecutter Data Science (Python): a project-structure template
• How to name files: talk by Jenny Bryan

Running the code: dependencies, workflows, paths

• renv (R) and uv (Python): record and restore project dependencies
• pipreqs: list the packages a Python project actually imports
• Rocker (Docker images for R) and repo2docker: containers, the last resort when versions alone are not enough
• targets (R) and Snakemake (any language): workflow tools that run steps in the right order and rerun only what changed
• here (R) and pyprojroot (Python): project-root paths that work on any machine

Licence & citation

• choosealicense.com: pick a licence and copy its text
• The Turing Way on licensing
• A case for CC0: by the Dryad repository
• cffinit: build a CITATION.cff file through a web form

Archiving & DOIs

• Zenodo, Dryad, Figshare: repositories that freeze a version and give you a DOI
• GitHub → Zenodo guide: archive a release and get a DOI