Write Readme

Write README

Overview

A fixed, proven README structure. A reader should understand what the repo is, why it exists, what it found, and how to rerun it in under one minute of scrolling, without opening a single file.

Core principles:

• Tables over prose. Every section after the header is a table, a diagram, a code block, or an image. Prose is at most one sentence introducing a figure
• Real numbers only. Every count, rate, runtime, and threshold comes from files in the repo (output CSVs, notebook source, logs). Never invent, estimate, or round beyond what the source shows
• Show, don't list. Key results are embedded as PNG previews, not linked
• Scannable at two depths. The essentials are visible; secondary figures and style rules live in <details> blocks
• One emoji per row or heading, used as a signpost. Never decorative runs of emoji

Workflow

1. Gather facts before writing

Read, do not guess:

Also note inconsistencies found while reading (e.g. prose says resolution = 2, code says 0.5). Do not paper over them in the README: omit the disputed value and report the mismatch to the user.

2. Render figure previews

GitHub does not render PDFs inline. Convert the chosen figures to compact PNGs:

mkdir -p docs/images
pdftoppm -png -singlefile -scale-to 1400 write/figures/<step>/<figure>.pdf docs/images/<figure>
magick docs/images/<figure>.png -strip -colors 256 PNG8:docs/images/<figure>.png

• Target 15 to 150 KB per image. Keep the source figure's kebab-case name

• View each PNG after rendering to confirm it is legible and not blank

• If .gitignore uses an ignore-everything-then-whitelist pattern, whitelist previews explicitly:

  !docs/
  !docs/images/*.png
  

• Choose 2 hero figures for the main body (the result that answers "did it work?" and the most biologically interesting output). Put 3 to 6 supporting figures in the collapsible block

3. Write the README using the template below

Keep the section order exactly. Drop a section only if it truly has no content (e.g. no figures in a pure package repo), never reorder.

4. Verify before committing

• git add -A && git status --short: only code, docs, and previews staged; no data, renders, or secrets
• Every relative link and image path resolves (ls each one)
• Every number in the README traces to a file
• Mermaid block uses <br/> for line breaks and quotes labels containing punctuation

Template

Section order and formatting are fixed. Replace <placeholders>; delete the guidance comments.

<div align="center">

# <one emoji> <Project Title>

**<one-line subtitle: what was done to what>**

![R](https://img.shields.io/badge/R-4.x-276DC3?logo=r&logoColor=white)
![<Core tool>](https://img.shields.io/badge/<Core%20tool>-<version>-8A2BE2)
![Quarto](https://img.shields.io/badge/Quarto-notebooks-75AADB?logo=quarto&logoColor=white)
![<Key package>](https://img.shields.io/badge/<Ecosystem>-<package>-1A81C2)
![Status](https://img.shields.io/badge/status-<step%2001%20complete>-success)

</div>

---

## 📌 At a Glance

| | |
|---|---|
| **What** | <data type and origin, one line> |
| **Why** | <the problem this repo solves, one line> |
| **Species** | <organism, with the gene naming convention that follows from it> |
| **Current cohort** | <subset analysed so far>: <n> samples, **<total> cells** |
| **Notebooks** | <format>, run in numeric order, each reading the previous step's checkpoint |
| **Outputs** | <checkpoints, figures, tables, apps> |

---

## 🗺️ Pipeline

```mermaid
flowchart LR
    A[("📦 <Input><br/><format>")] --> B["🔄 <Step><br/><key function><br/><key choice>"]
    B --> C["🔗 <Step><br/>..."]
    C --> D["📊 <Step><br/>..."]
    D --> Z[("🖥️ <Final output>")]

    classDef io fill:#e8f1fb,stroke:#276DC3,color:#0b2545
    classDef step fill:#f4f0fb,stroke:#8A2BE2,color:#2d0a4e
    class A,Z io
    class B,C,D step
```

| Step | Notebook | Status |
|:---:|---|:---:|
| 01 | [`scripts/01-<name>.qmd`](scripts/01-<name>.qmd): <comma list of what it does> | ✅ |
| 02+ | <what comes next> | 🔜 |

---

## 🧪 <Samples | Inputs> (<cohort name>)

| Sample | Cells | Median genes/cell | Median % mito | <Key per-sample metric> |
|---|---:|---:|---:|---:|
| `<sample_id>` | <n> | <n> | <n> | <n> (<pct>%) |
| **Total** | **<sum>** | | | **<sum> (<pct>%)** |

---

## 🔑 Key Design Decisions

> [!IMPORTANT]
> **<The single most important invariant, in bold.>** <One or two sentences on why it matters to anyone using the outputs.>

| Decision | Rationale |
|---|---|
| <emoji> **<Short decision>** | <Why, in one or two sentences, grounded in the data or method> |

---

## 🖼️ Results Preview

### <Hero figure 1 title: the "did it work" result>

<One sentence stating what to see.>

<p align="center">
  <img src="docs/images/<figure-1>.png" width="85%" alt="<descriptive alt text>">
</p>

| <Comparison column> | <Metric> | <Relative metric> |
|---|---:|---:|
| ⚡ <best option> | <value> | 1× |

### <Hero figure 2 title: the most interesting output>

<One sentence stating what to see.>

<p align="center">
  <img src="docs/images/<figure-2>.png" width="85%" alt="<descriptive alt text>">
</p>

<details>
<summary><b>📊 More figures: <comma list></b></summary>

#### <Figure title>
<img src="docs/images/<figure>.png" alt="<alt text>">

</details>

---

## 📁 Repository Layout

```
<repo>/
├── 📄 README.md
├── ⚙️ .gitignore                  # <its policy in one phrase>
├── 🧭 <project>.Rproj             # <what it anchors>
├── 📓 scripts/
│   └── 01-<name>.qmd
├── 🖼️ docs/images/                # PNG previews used in this README
│
│   ── not tracked (local only) ──────────────────────────
├── read/                          # <purpose>
├── checkpoints/                   # <purpose>
└── write/
    ├── figures/<step>/            # <contents>
    └── tables/<step>/             # <contents>
```

> [!NOTE]
> Data and generated output are **never committed**. <Data volume and largest file size, and why they cannot be on GitHub.>

---

## 🚀 Reproducing

```bash
# 1. Clone
git clone git@github.com:<owner>/<repo>.git <dir>
cd <dir>

# 2. Recreate the untracked directories
mkdir -p <dirs>

# 3. Place inputs
#    <exact location and naming pattern, with one example filename>

# 4. Render
quarto render scripts/01-<name>.qmd

# 5. <Explore / next action>
<command>
```

<One sentence on how steps can be rerun in isolation, if true.>

---

## 📦 Dependencies

| Area | Packages |
|---|---|
| 🧬 <Area> | `<pkg>`, `<pkg>` |

---

## ✍️ Code Conventions

<details>
<summary>Style rules used across notebooks</summary>

- **<Rule name>**: <rule in one line>

</details>

---

<div align="center">

**<Author>** · <Lab / Group> · <Institution>

</div>

Section Rules

Adapting to Repo Type

The section order stays fixed; the content of three sections flexes:

Common Mistakes