diataxis

Author: dorien-er

_quarto.yml

@@ -7,7 +7,7 @@ project:
   resources:
     - robots.txt
     # Shared single-cell/spatial flow widget, loaded by index.qmd and
-    # concepts/architecture.qmd via <script src>.
+    # workflows/index.qmd via <script src>.
     - flow.js
   # NOTE: team/ is a hand-curated static page for now (sections + roles the flat
   # author registry can't express). scripts/generate_team.py is kept for the
@@ -39,7 +39,7 @@ website:
       # "Workflows" = the curated available-workflows overview. Page still lives
       # under concepts/ (kept there to avoid breaking cross-links). The advanced
       # developer deep-dive stays in the Concepts hub, not here.
-      - href: concepts/architecture.qmd
+      - href: workflows/index.qmd
         text: Workflows
       # "Documentation" groups the practical, do-it materials. Get started is
       # also the primary landing-page CTA, so it stays reachable from the hero.

concepts/data-state.qmd

@@ -5,7 +5,7 @@ order: 70
 ---
 
 There are two ways to read the pipeline. The [available
-workflows](architecture.qmd) page walks it **by stage**, the way an analyst
+workflows](../workflows/index.qmd) page walks it **by stage**, the way an analyst
 thinks. This page reads it the way the workflows are **actually built**, the view
 you need if you are writing or wiring components. It covers how the data object is
 organized along **two axes** (samples and modalities), what gets **written into

concepts/ecosystem.qmd

@@ -22,7 +22,7 @@ dependency and adds to it rather than forking it.
 
 ## How the packages relate
 
-Every package plugs into the same [pipeline architecture](architecture.qmd):
+Every package plugs into the same [pipeline architecture](../workflows/index.qmd):
 
 - **`openpipeline`** defines all stages, ingestion, QC, processing, integration,
   and downstream, for the RNA, protein, ATAC, VDJ, and GDO modalities.

concepts/index.qmd

@@ -10,7 +10,7 @@ object.
 
 The pages below explain the design choices behind it. Read top to bottom for the
 full picture, or jump to whichever answers your question. For how these ideas play
-out across the actual pipeline, see [Available workflows](architecture.qmd).
+out across the actual pipeline, see [Available workflows](../workflows/index.qmd).
 
 ```{=html}
 <div class="concept-list">

flow.js

@@ -1,5 +1,5 @@
 // Single-cell / spatial pipeline flow widget.
-// Shared by the landing page and the architecture concept page.
+// Shared by the landing page and the workflows overview page.
 // Injects itself into #op-flow. Set window.FLOW_BASE to the site-root-relative
 // prefix (e.g. '../') on pages below the site root so the 'all →' links resolve.
 (function () {
@@ -75,7 +75,7 @@
       '</div>';
   }
 
-  // Detailed variant (architecture page): surface the two optional stages that
+  // Detailed variant (workflows page): surface the two optional stages that
   // the landing overview intentionally leaves out.
   if (detailed) {
     var demux = {

get-started/index.qmd

@@ -13,7 +13,24 @@ This walkthrough uses **local Nextflow**. The exact same workflows run on Seqera
 (`tw launch`) or through the Viash Hub web form, see the
 [execution guides](../guides/index.qmd) for those routes.
 
-## 1 · Set up Nextflow and Docker
+::: {.callout-note appearance="simple"}
+**Before you start**
+
+- **Prerequisites:** a Unix-like shell (macOS, Linux, or WSL2 on Windows). No
+  prior Nextflow or single-cell experience needed, every command is here.
+- **Hardware:** Cell Ranger (step 3) is the heavy step. Budget **~32 GB RAM**,
+  **~8 CPU cores**, and **~50 GB free disk** for the downloads plus Cell Ranger's
+  intermediate files.
+- **Time:** roughly **2–4 hours** end to end on a laptop, almost all of it in Cell
+  Ranger mapping. The processing, integration, and read-output steps are minutes each.
+- **What you'll have at the end:** one batch-corrected, Leiden-clustered `.h5mu`
+  object with a UMAP, built from two public PBMC samples.
+
+Just want to see the shape of a run first? The [Quickstart](quickstart.qmd) skips
+Cell Ranger and takes about 10 minutes on pre-computed counts.
+:::
+
+## 1 · Set up Nextflow and Docker {#sec-setup-nextflow-and-docker}
 
 Everything else ships inside containers, so this is all you install: a Java
 runtime (Nextflow needs it), Nextflow, and Docker.
@@ -91,35 +108,33 @@ EOM
 
 ## 2 · Get the data
 
-The run uses two public 10x Genomics PBMC datasets (5' gene expression + VDJ +
-antibody capture). Each 10x dataset page lists ready-made `curl` commands; the
-loops below fetch both datasets' libraries and unpack them into a local `data/`
-folder:
+The run uses two public 10x Genomics PBMC datasets, each with 5' gene expression
+and VDJ (T- and B-cell) libraries. Each 10x dataset page lists ready-made `curl`
+commands; the loops below fetch both datasets' libraries and unpack them into a
+local `data/` folder:
 
 ```bash
 mkdir -p data && cd data
 
 # Dataset 1 — Human PBMC, 10k cells, 5' v2
 base1="https://cf.10xgenomics.com/samples/cell-vdj/5.0.0/sc5p_v2_hs_PBMC_10k"
-for lib in 5gex t b 5fb; do
+for lib in 5gex t b; do
   curl -O "${base1}/sc5p_v2_hs_PBMC_10k_${lib}_fastqs.tar"
   tar -xf "sc5p_v2_hs_PBMC_10k_${lib}_fastqs.tar"
 done
 
-# Dataset 2 — Human PBMC, 10k cells, TotalSeq-C, 5' GEM-X
-# (confirm the download URL on the dataset page)
+# Dataset 2 — Human PBMC, 10k cells, 5' GEM-X
 base2="https://cf.10xgenomics.com/samples/cell-exp/9.0.0/10k_Human_PBMC_TotalSeqC_5p_gemx"
-for lib in gex tcr ig ab; do
+for lib in gex tcr ig; do
   curl -O "${base2}/10k_Human_PBMC_TotalSeqC_5p_gemx_${lib}_fastqs.tar"
   tar -xf "10k_Human_PBMC_TotalSeqC_5p_gemx_${lib}_fastqs.tar"
 done
 
 cd ..
 ```
 
-The transcriptome, VDJ, and antibody **feature reference** (TotalSeq-C panel) are
-all fetched automatically from URLs in the `param_list` below, so FASTQs are the
-only thing you download by hand.
+The transcriptome and VDJ **references** are fetched automatically from URLs in the
+`param_list` below, so FASTQs are the only thing you download by hand.
 
 After both downloads, `data/` holds one folder per library:
 
@@ -128,11 +143,9 @@ data/
 ├── sc5p_v2_hs_PBMC_10k_5gex_fastqs/                # sample 1 · Gene Expression
 ├── sc5p_v2_hs_PBMC_10k_t_fastqs/                   # sample 1 · VDJ-T
 ├── sc5p_v2_hs_PBMC_10k_b_fastqs/                   # sample 1 · VDJ-B
-├── sc5p_v2_hs_PBMC_10k_5fb_fastqs/                 # sample 1 · Antibody Capture
 ├── 10k_Human_PBMC_TotalSeqC_5p_gemx_gex_fastqs/    # sample 2 · Gene Expression
 ├── 10k_Human_PBMC_TotalSeqC_5p_gemx_tcr_fastqs/    # sample 2 · VDJ-T
-├── 10k_Human_PBMC_TotalSeqC_5p_gemx_ig_fastqs/     # sample 2 · VDJ-B
-└── 10k_Human_PBMC_TotalSeqC_5p_gemx_ab_fastqs/     # sample 2 · Antibody Capture
+└── 10k_Human_PBMC_TotalSeqC_5p_gemx_ig_fastqs/     # sample 2 · VDJ-B
 ```
 
 Each folder holds that library's `*_R1_*.fastq.gz` / `*_R2_*.fastq.gz` files.
@@ -141,8 +154,8 @@ Each folder holds that library's `*_R1_*.fastq.gz` / `*_R2_*.fastq.gz` files.
 
 `ingestion/cellranger_multi` aligns each library and writes one `.h5mu` per
 sample; under the hood OpenPipeline 4.2.0 runs
-[Cell Ranger `multi`](https://www.10xgenomics.com/support/software/cell-ranger/latest/analysis/running-pipelines/cr-5p-multi)
-10. Describe the samples and their libraries in a `param_list`
+[Cell Ranger `multi`](https://www.10xgenomics.com/support/software/cell-ranger/latest/analysis/running-pipelines/cr-5p-multi).
+Describe the samples and their libraries in a `param_list`
 (`params_cellranger.yaml`):
 
 ```yaml
@@ -153,18 +166,15 @@ param_list:
       - data/sc5p_v2_hs_PBMC_10k_5gex_fastqs/*_R*.fastq.gz
       - data/sc5p_v2_hs_PBMC_10k_t_fastqs/*_R*.fastq.gz
       - data/sc5p_v2_hs_PBMC_10k_b_fastqs/*_R*.fastq.gz
-      - data/sc5p_v2_hs_PBMC_10k_5fb_fastqs/*_R*.fastq.gz
-    library_id: [PBMC_10k_5gex, PBMC_10k_t, PBMC_10k_b, PBMC_10k_5fb]
-    library_type: [Gene Expression, VDJ-T, VDJ-B, Antibody Capture]
+    library_id: [PBMC_10k_5gex, PBMC_10k_t, PBMC_10k_b]
+    library_type: [Gene Expression, VDJ-T, VDJ-B]
   - id: 10k_Human_PBMC_TotalSeqC_5p_gemx
     input:
       - data/10k_Human_PBMC_TotalSeqC_5p_gemx_gex_fastqs/*_R*.fastq.gz
       - data/10k_Human_PBMC_TotalSeqC_5p_gemx_tcr_fastqs/*_R*.fastq.gz
       - data/10k_Human_PBMC_TotalSeqC_5p_gemx_ig_fastqs/*_R*.fastq.gz
-      - data/10k_Human_PBMC_TotalSeqC_5p_gemx_ab_fastqs/*_R*.fastq.gz
-    library_id: [TotalSeqC_gex, TotalSeqC_tcr, TotalSeqC_ig, TotalSeqC_ab]
-    library_type: [Gene Expression, VDJ-T, VDJ-B, Antibody Capture]
-feature_reference: "<TotalSeq-C feature-reference CSV URL, from the dataset page>"
+    library_id: [TotalSeqC_gex, TotalSeqC_tcr, TotalSeqC_ig]
+    library_type: [Gene Expression, VDJ-T, VDJ-B]
 gex_reference: https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38-2020-A.tar.gz
 vdj_reference: https://cf.10xgenomics.com/supp/cell-vdj/refdata-cellranger-vdj-GRCh38-alts-ensembl-7.0.0.tar.gz
 publish_dir: results/ingestion

get-started/quickstart.qmd

@@ -0,0 +1,110 @@
+---
+title: "Quickstart"
+description: "See a full run in ~10 minutes, starting from pre-computed counts."
+order: 1
+---
+
+The fastest way to see OpenPipeline work end to end. This skips the heavy
+alignment step (Cell Ranger) and starts from a **pre-computed count matrix** for a
+small, single PBMC sample: convert it to MuData, process it, cluster it, and read
+the result. It runs in about **10 minutes** on a laptop.
+
+When you're ready for a real run, from raw FASTQ files, two samples, and batch
+correction, do the full [Run your first pipeline](index.qmd) walkthrough. This
+Quickstart is the express lane; that page is the real thing.
+
+::: {.callout-note appearance="simple"}
+**You need Nextflow and Docker.** If you don't have them yet, follow
+[step 1 of the full walkthrough](index.qmd#sec-setup-nextflow-and-docker) to
+install them and point Nextflow at the Viash Hub package registry. The version
+pin (`export NXF_VER=25.10.2`) and one-time `~/.nextflow/scm` setup are the same.
+:::
+
+## 1 · Get the data
+
+One small file: the filtered count matrix for 10x Genomics' public **1k PBMC**
+dataset (~1,000 cells, a few MB).
+
+```bash
+mkdir -p data
+curl -o data/pbmc_1k_v3.h5 \
+  https://cf.10xgenomics.com/samples/cell-exp/3.0.0/pbmc_1k_v3/pbmc_1k_v3_filtered_feature_bc_matrix.h5
+```
+
+This is the Cell Ranger output you would otherwise generate yourself. Starting
+from it lets you skip alignment and reference downloads entirely.
+
+## 2 · Convert to MuData
+
+Every OpenPipeline workflow speaks [MuData](../concepts/mudata.qmd). Convert the
+10x HDF5 file to a `.h5mu` with `convert/from_10xh5_to_h5mu`:
+
+```bash
+nextflow run https://packages.viash-hub.com/vsh/openpipeline.git \
+  -r 4.2.0 -latest -profile docker \
+  -main-script target/nextflow/convert/from_10xh5_to_h5mu/main.nf \
+  --id pbmc_1k \
+  --input data/pbmc_1k_v3.h5 \
+  --output pbmc_1k.h5mu \
+  --publish_dir results/
+```
+
+## 3 · Process the sample
+
+`multiomics/process_samples` filters low-quality cells, normalizes, selects
+highly variable genes, and computes a PCA embedding, all in one command:
+
+```bash
+nextflow run https://packages.viash-hub.com/vsh/openpipeline.git \
+  -r 4.2.0 -latest -profile docker \
+  -main-script target/nextflow/workflows/multiomics/process_samples/main.nf \
+  --id pbmc_1k \
+  --input results/pbmc_1k.h5mu \
+  --output pbmc_1k_processed.h5mu \
+  --publish_dir results/
+```
+
+## 4 · Cluster and embed
+
+With one sample there's no batch effect to correct, so you can skip integration
+and cluster directly on the PCA embedding. `multiomics/neighbors_leiden_umap`
+builds the neighbor graph, runs Leiden clustering, and computes a UMAP:
+
+```bash
+nextflow run https://packages.viash-hub.com/vsh/openpipeline.git \
+  -r 4.2.0 -latest -profile docker \
+  -main-script target/nextflow/workflows/multiomics/neighbors_leiden_umap/main.nf \
+  --id pbmc_1k \
+  --input results/pbmc_1k_processed.h5mu \
+  --obsm_input X_pca \
+  --uns_neighbors neighbors \
+  --obs_cluster leiden \
+  --leiden_resolution 1.0 \
+  --obsm_umap X_umap \
+  --output pbmc_1k_clustered.h5mu \
+  --publish_dir results/
+```
+
+## 5 · Read the output
+
+`results/pbmc_1k_clustered.h5mu` holds the whole result for the `rna` modality:
+
+```
+MuData
+ └─ .mod
+     └─ rna
+         ├─ .layers["log_normalized"]   # normalized, log1p counts
+         ├─ .obsm["X_pca"]              # PCA from process_samples
+         ├─ .obs["leiden_1.0"]          # cluster labels (one column per resolution)
+         └─ .obsm["X_umap"]             # UMAP for plotting
+```
+
+The clusters are just numbers so far. Assigning biological identities to them is
+[cell type annotation](../guides/annotate.qmd), a separate step.
+
+## Where to go next
+
+- **The real run:** [Run your first pipeline](index.qmd), raw FASTQ → Cell Ranger
+  → two samples → batch-corrected, integrated object.
+- **Pick individual tasks:** the [task guides](../guides/index.qmd).
+- **Understand the design:** [How it works](../concepts/index.qmd).

guides/annotate.qmd

@@ -1,5 +1,5 @@
 ---
-title: "Cell type annotation"
+title: "Annotate cell types"
 description: "Assign biological cell-type labels to clusters or cells."
 categories: [openpipeline]
 order: 45

guides/cell-cell-communication.qmd

@@ -1,5 +1,5 @@
 ---
-title: "Cell-cell communication"
+title: "Infer cell-cell communication"
 description: "Ligand-receptor interaction inference between cell types (LIANA)."
 categories: [openpipeline]
 order: 60

guides/differential-expression.qmd

@@ -1,5 +1,5 @@
 ---
-title: "Differential expression"
+title: "Run differential expression"
 description: "Pseudobulk differential expression across conditions with DESeq2."
 categories: [openpipeline]
 order: 50