Documentation, licenses and citation

CBIO7501 · Lesson 11

Aziz Khan

Today you will

• write a README that a stranger can follow
• license code, text and data deliberately
• make the project citable (CITATION.cff)
• record software versions from the lock file

Rerunnable is not enough

A perfectly versioned, containerized, locked analysis is still useless if nobody can tell what it is, how to run it, what to expect, and whether they may reuse it.

Documentation: the fifth pillar (Ziemann et al. 2023).

Good documentation

Without it, a project is hard to understand, impossible to reproduce and unlikely to be reused. Good documentation:

• explains what the project is about
• links data, code and environment together
• records how each analysis was done
• gives clear instructions to reproduce it
• grows continuously, not the week before submission
• says how to get in touch about the project

Seven questions a README answers

1. What is this project about?
2. Is there a publication?
3. What is in the repository?
4. What hardware does it need?
5. How do I reproduce it? (one command)
6. What outputs should I expect?
7. How do I contact the authors?

Files a reader looks for

File	Answers
README.md	the seven questions
LICENSE	what may I do with it?
CITATION.cff	how do I cite it?
CONTRIBUTING.md	how do I help?
CODE_OF_CONDUCT.md	how do we treat each other?
pixi.toml, pixi.lock	which software?
metadata/	which data, from where?

Our LTEE project has all of them: the template made most, you filled them in.

The license spectrum

CC0 / public domain → MIT, BSD, Apache → GPL (copyleft) → CC BY-NC, BY-ND → no license
  "do anything"        "keep the notice"   "stay open"        "restricted"     "all rights reserved"

• Code: MIT (or BSD, Apache) · Text and figures: CC BY 4.0 · Data: CC0 or CC BY
• No license = others may look, not reuse
• You can only license what you own

Citable software

cff-version: 1.2.0
title: "LTEE variant calling"
authors:
  - given-names: "Ada"
    family-names: "Lovelace"
    orcid: "https://orcid.org/0000-0002-1825-0097"
version: 0.1.0
license: MIT

GitHub shows Cite this repository; Zenodo uses it for the DOI record (lesson 12). Validate it: pixi exec cffconvert --validate.

Think, pair, share

5 minutes. Swap READMEs with a neighbor. Without asking them, write down: the command to reproduce, the expected output, and what you may reuse. What was missing?

Quiz

1. A public GitHub repository has no LICENSE. May you reuse its code in your project? (yes / no)
2. Which license fits a figure you made? (a) MIT (b) CC BY 4.0 (c) GPL
3. Where does the exact samtools version for a methods section come from? (a) memory (b) pixi.lock / pixi list (c) the README of samtools

Answers: 1 no (all rights reserved by default); 2 b; 3 b.

Recap

• README: seven questions, one command to reproduce, measured hardware
• License code, text and data separately
• CITATION.cff, validated; contributing and conduct files
• Versions come from the lock file

Now: tutorial 11.

Sources

• Tools for Reproducible Research, NBIS. CC BY 4.0. https://nbisweden.github.io/workshop-reproducible-research/
• Week 1 slides 94 to 96 (repository hygiene, license spectrum) are the basis; the ENCODEfetch screenshot is not used: the LTEE project is the worked example.
• Lee BD (2018). Ten simple rules for documenting scientific software. PLoS Comput Biol 14:e1006561. https://doi.org/10.1371/journal.pcbi.1006561
• Citation File Format: https://citation-file-format.github.io/

Text and slides CC BY 4.0 unless marked otherwise. Full list: Sources and credits.