oxo-flow-scrnaseq — Single-cell RNA-seq: alignment, quantification and QC

★ Verified · ⇄ Official port of nf-core/scrnaseq @ 4.2.0 — same tools, same versions, same commands. Part of the oxo-flow-community catalog.

Run single-cell RNA-seq analysis from raw FASTQ reads to a final MultiQC report, on all six upstream aligner branches of nf-core/scrnaseq 4.2.0 (see the fidelity table for the exact scope):

• aligner = cellranger (default): FastQC read QC, Cell Ranger reference preparation, per-sample cellranger count (with optional BAM output).
• aligner = cellranger + cellranger_multi = true: multiome mode — cellranger multi per sample with GEX plus any of VDJ / antibody / BEAM / CRISPR / CMO (see the Cell Ranger multi mode section).
• aligner = simpleaf (upstream's default aligner): simpleaf/piscem index + simpleaf quant (alevin-fry), optional QCatch empty-droplet QC report.
• aligner = kallisto: kb ref + kb count (kallisto/bustools, standard / lamanno / nac workflows).
• aligner = star: STAR genomeGenerate + STARsolo per-sample alignment (legacy iGenomes index upgrade optional).
• aligner = cellrangerarc: cellranger-arc mkref + count for multiome ATAC+GEX data.

All branches converge on the same downstream path: conversion of raw/filtered matrices to h5ad, CellBender ambient-RNA background removal (not for cellrangerarc, exactly like upstream), sample-wise h5ad concatenation, and optional export to Seurat and SingleCellExperiment objects. All results land under results/.

This workflow requires oxo-flow >= 0.12.0. The recommended way is the prebuilt release binary:

curl -fL -o oxo-flow.tar.gz \
  https://github.com/Traitome/oxo-flow/releases/latest/download/oxo-flow-latest-x86_64-unknown-linux-gnu.tar.gz
tar xzf oxo-flow.tar.gz
sudo mv oxo-flow /usr/local/bin/

Alternatively, install via conda:

conda install -c bioconda oxo-flow-cli

Note: the conda package may lag behind releases; binaries for other platforms are available on the releases page.

git clone https://github.com/oxo-flow-community/oxo-flow-scrnaseq.git
cd oxo-flow-scrnaseq

• Reference data (you provide; see the [config] section of main.oxoflow): a genome FASTA (optionally gzipped) and a gene-annotation GTF (optionally gzipped) — defaults refs/refdata.fa.gz and refs/refdata.gtf.gz. The Cell Ranger reference is built from them by the workflow into refs/cellranger_reference unless you set build_cellranger_index = false and point transcriptome at a pre-built index.
• Sample data: one raw 10x FASTQ pair per sample as raw/<sample>_R1.fastq.gz / raw/<sample>_R2.fastq.gz (one pair per sample), plus a samplesheet.csv with columns sample,fastq_1,fastq_2,protocol,expected_cells for the combined-h5ad step. For aligner = cellrangerarc, five pre-named files per sample are required instead (the port's naming contract replaces the upstream samplesheet sample_type/fastq_barcode columns): raw/<sample>_gex_S1_L001_R1_001.fastq.gz, raw/<sample>_gex_S1_L001_R2_001.fastq.gz, raw/<sample>_atac_S1_L001_R1_001.fastq.gz, raw/<sample>_atac_S1_L001_R2_001.fastq.gz, raw/<sample>_atac_S1_L001_R3_001.fastq.gz.
• Optional-modality FASTQs (only for cellranger_multi = true): one pair per modality per sample in refs/cellranger_multi_metadata.tsv — columns <modality>_fastq_1 / <modality>_fastq_2 for vdj, ab, beam, crispr and cmo (GEX always comes from raw/<sample>_R{1,2}.fastq.gz). An empty cell = the modality is absent for that sample. The shipped file is a lookup-only stub with the header and two empty rows; edit it when enabling the mode. Upstream reads these paths from the --cellranger_multi_sample_* CLI flags; the port reads them from the metadata table instead (see the Cell Ranger multi mode section).
• Barcode whitelists: simpleaf and STARsolo pass a whitelist per protocol (upstream maps it automatically in assets/protocols.json; the port uses one explicit config.whitelist path). The four upstream whitelists ship under assets/whitelist/10x_V{1..4}_barcode_whitelist.txt.gz; set whitelist per protocol (e.g. assets/whitelist/10x_V1_barcode_whitelist.txt.gz for 10XV1). Protocols without a whitelist upstream (dropseq/smartseq) work with whitelist = "".
• Compute: up to 12 CPUs and 72 GB RAM per rule (Cell Ranger mkref / count); h5ad conversion, CellBender and concatenation rules use 6 CPUs / 36 GB, QC/prep rules 1–2 CPUs / 6–12 GB. Per-sample rules run concurrently, so peak usage scales with the number of samples and -j.

Cell Ranger memory sizing. mkref/count auto-size --localmem to 2/3 of the actually free physical memory (/proc/meminfo MemAvailable, 1 GB floor) — never the machine's effective total, which counts swap: cellranger's job manager waits forever when --localmem exceeds the free RAM (live: Need 6 GB ... (2.6 GB available) looped for hours on a 3.7 GB box). Real runs still want 10x's documented 8 GB floor; the tiny test fixtures run on smaller machines with swap absorbing overflow. Set cellranger_localmem to force a value.

• Tool delivery: containers with pinned images — every rule pins the exact upstream nf-core container string (no latest), so Docker (or Singularity) is required at runtime. Conda alternatives for local runs ship in envs/, except the Cell Ranger rules, which are docker-only (the upstream modules refuse conda profiles).

# 1. install oxo-flow (see Installation)
# 2. prepare data: raw/<sample>_R1.fastq.gz / _R2.fastq.gz, a samplesheet.csv,
#    and reference files (refs/refdata.fa.gz, refs/refdata.gtf.gz) — a synthetic 3-gene test reference is committed under refs/ (swap in a real FASTA/GTF for real data)
# 3. preview the plan
oxo-flow dry-run main.oxoflow
# 4. run
oxo-flow run main.oxoflow -j 8
# 5. run a subset
oxo-flow run main.oxoflow -t multiqc --samples first:2

• Default config knobs mirror upstream params: protocol=auto → --chemistry auto, save_align_intermeds=true → --create-bam true, expected_cells="" → no --expect-cells flag. For simpleaf/kallisto/star, protocol = "auto" fails fast with upstream's exact error ("Only cellranger supports protocol = 'auto'…") — pick 10XV1–10XV4, dropseq or smartseq (kallisto/star only).
• .gz detection: upstream decides at runtime whether to gunzip (fasta.endsWith('.gz')); oxo-flow cannot inspect file names, so fasta_gz/gtf_gz are explicit flags. When a plain FASTA/GTF is used, set the flag to false and point fasta_prepared/gtf_prepared at the actual file paths.
• Pre-built index: with build_cellranger_index=false and transcriptome=<index dir>, cellranger_mkgtf/cellranger_mkref are skipped and count runs directly (upstream --cellranger_index behavior). The same pattern exists per aligner: simpleaf_index (pre-built simpleaf index dir), kallisto_index (pre-built kb_ref_out.idx; prebuilt mode requires txp2gene, mirroring upstream's assert), star_index (pre-built STAR index dir), cellrangerarc_reference (pre-built cellranger-arc reference). The corresponding build rule is skipped and the run rules fail fast with a clear message if the path is absent.
• Reference chain (defaults shown): fasta=refs/refdata.fa.gz → fasta_prepared=refs/refdata.fa → gtf_filtered=refs/refdata_genes.gtf → gtf_mkgtf=refs/refdata_genes.filtered.gtf → transcriptome=refs/cellranger_reference. When enabling gtf_source_fix, also set gtf_mkgtf_input to the source-fixed file.
• Aligners (all switches are --arg aligner=… --arg protocol=…): simpleaf (index from fasta+gtf, or from transcript_fasta which requires txp2gene; skip_qcatch, simpleaf_umi_resolution, remove_doublets, qcatch_n_partitions); kallisto (kb_workflow = standard/lamanno/nac, kb_t1c/kb_t2c overrides); star (star_feature → --soloFeatures, star_index_legacy = upgrade a legacy iGenomes 2.6.x index, star_ignore_sjdbgtf, seq_center → --outSAMattrRGline CN); cellrangerarc (cellrangerarc_config = optional mkref config json, auto-generated when empty). cellranger_multi = true switches the cellranger branch from count to multi (see the Cell Ranger multi mode section); cellranger_multi_gex_reference / cellranger_multi_vdj_reference / cellranger_multi_fb_reference / cellranger_multi_barcodes map to upstream's --cellranger_index / --cellranger_vdj_index / --fb_reference / --cellranger_multi_barcodes, and skip_cellrangermulti_vdjref skips the VDJ reference build exactly like upstream's param of the same name.
• Conda alternatives: the workflow pins the exact upstream container images; conda env yamls ship in envs/ for local runs (cellranger rules are docker-only — the upstream modules refuse conda profiles). python-igraph/leidenalg are not pinned upstream and were resolved at port time (2026-08-15) to conda-forge releases.
• Completion notifications (upstream --email / --email_on_fail, and the template's --hook_url webhook): email="..." sends a summary email on success, email_on_fail="..." is the failure address (plain email wins on failure, like upstream), hook_url="..." receives a curl -X POST with the run counters on both paths. All default empty = no notifications (upstream's default too). Delivered by the [workflow] on_complete / on_error hooks — requires engine ≥ 0.17.0; older engines ignore the hook keys.
• samplesheet (for CONCAT_H5AD): user CSV with the upstream columns (sample,fastq_1,fastq_2,protocol,expected_cells); see test/fixtures/samplesheet.csv. The raw/ symlink in the repo root points at test/fixtures/raw/ so validate/dry-run see the fixture reads as existing inputs; replace the fixtures with real data for runs.

The pipeline expects refs/refdata.fa.gz + refs/refdata.gtf.gz and derives the rest: gunzip → refs/refdata.fa|.gtf, GTF gene filter → refs/refdata_genes.gtf, mkgtf → refs/refdata_genes.filtered.gtf, mkref → refs/cellranger_reference/. The committed synthetic reference is a 3-protein-coding-gene chr1 (exons 100-500, 800-1300, 1500-1900) sized so mkref/count run on small machines; test/fixtures/generate_fixtures.py draws the test reads from those exons.

Ported from nf-core/scrnaseq, version 4.2.0 (commit 3fc17b4f971a89e47c88337de71d0e777ffad8cc, MIT). Created 2026-08-15; this workflow may lag behind upstream releases. Upstream attribution and licensing details are in NOTICE.md; the upstream MIT license is retained verbatim in LICENSE.upstream.

Rows cover every upstream process/subworkflow of nf-core/scrnaseq 4.2.0, on all six aligner branches. Container image strings and conda pins are copied verbatim from the upstream modules (all pinned, no latest). Deviations from upstream mechanics are called out per row; one multi-lane data limitation remains and is listed at the bottom with evidence. PIPELINE_COMPLETION is ported via workflow-level hooks (row below).

Live verification (2026-08-26/27, tx-ubuntu, engine 0.15.0 + apptainer): five configurations passed end-to-end — aligner = cellranger, simpleaf, kallisto, star (10X) and star with protocol = dropseq. The cellrangerarc branch is ported and validate/lint-clean but was not live-run in this wave. The cellranger_multi branch is ported and validate/lint/ dry-run-clean with the expanded per-sample config.csv verified shell-level (see the Cell Ranger multi mode section); it needs the quay.io/nf-core/cellranger:10.0.0 container (present for count), so a live run only needs the metadata table filled — queued for the next container wave.

Not ported (with reasons):

Other deliberate deviations (documented per row above): FastQC is skipped for cellrangerarc (five reads per sample cannot fit one static input pattern; upstream runs it on all of them); the arc samplesheet columns are a file-naming contract; workflow_summary/methods_description are new default-ON rules; simpleaf/star/kallisto accept one explicit whitelist path instead of upstream's automatic per-protocol mapping; the cellranger multi branch takes its per-modality fastq paths from the metadata table instead of upstream's --cellranger_multi_sample_* CLI flags (see below).

aligner = cellranger runs cellranger count by default; setting cellranger_multi = true switches the cellranger branch to the upstream aligner = cellrangermulti mode — cellranger multi per sample, with the same GEX reads plus any of VDJ, antibody, BEAM, CRISPR or CMO FASTQ pairs. count and multi are mutually exclusive (the when gates mirror the upstream aligner branch), and both converge on the same downstream h5ad chain, so cellbender/concat/anndatar need no changes.

Per-modality inputs via the metadata table. Upstream feeds per-sample, per-modality fastq groups into the module with channel branching (groupTuple + EMPTY-file injection when a modality is absent) — a variable-cardinality input set that a fixed rule signature cannot express. The port's metadata binding ([workflow] metadata_file, engine ≥ 0.17.0) replaces it: each sample's optional modality pairs live in one <modality>_fastq_1 / <modality>_fastq_2 column pair of refs/cellranger_multi_metadata.tsv, and an empty cell renders as '' — the port's equivalent of the upstream EMPTY-file injection. The cellranger_multi rule reads those cells through {meta.<modality>_fastq_1/2} placeholders (expanded per sample at plan time) and builds the config.csv with only the present modalities, so the variable-cardinality config is expressible in the shell with no engine follow-up.

Reference selection mirrors the upstream channels:

• GEX: cellranger_multi_gex_reference if set (upstream --cellranger_index), else the built {config.transcriptome}.
• VDJ: cellranger_multi_vdj_reference if set (upstream --cellranger_vdj_index), else the cellranger_mkvdjref-built refs/cellranger_vdj_reference/ (skipped when skip_cellrangermulti_vdjref = true, same gate as upstream).
• Feature barcoding: cellranger_multi_fb_reference (upstream --fb_reference), required when antibody or CRISPR FASTQs are present — the rule fails fast with upstream's message otherwise.
• CMO: cellranger_multi_barcodes (upstream --cellranger_multi_barcodes), required when CMO FASTQs are present.

All configured paths are existence-checked before cellranger multi starts; VDJ and GEX references are directory checks, the fb reference and barcodes are file checks.

Chemistry mapping reuses the port's protocol→chemistry table (auto→auto, 10XV1-4→SC3Pv1-4), with upstream's exact guard that only cellranger accepts protocol = 'auto'; unrecognized protocols pass through verbatim with a warning (upstream logs the same).

Outputs land at results/<aligner>/multi/<sample>/outs/ — the upstream module's outs/ tree including web_summary.html and per_sample_outs/<sample>/count/sample_{filtered,raw}_feature_bc_matrix.h5, which feed the shared mtx_to_h5ad_multi_{raw,filtered} rules.

Verification status: the branch is validate/lint-clean, and the expanded per-sample shells were exercised end-to-end against a cellranger stub that consumes the generated config.csv and emits the declared outs tree — S1 with VDJ + antibody produced [gene-expression]/[vdj]/[feature] sections and three [libraries] rows; S2 without them produced the GEX-only config. A live run needs the same quay.io/nf-core/cellranger:10.0.0 container the count branch already uses, so it only waits on a container-backed host with the metadata table filled — queued for the next container wave.

Live-root-caused fixes (engine 0.15.0, tx-ubuntu): tool-facing threads/cores use {effective_threads} (rules declare 12/6 CPUs; a 4-core box would oversubscribe); every container spec is quay.io-qualified (bare biocontainers/... resolves to Docker Hub, not the pinned quay.io registry); directory-moving rules rm -rf the engine-precreated output parent before mv (the parent exists, so mv would nest the tree inside itself); the STAR index nbases heuristic truncates with int() and a 14 cap (the 52kb fixture genome rounded up to 7 where STAR requires 6 — "may cause seg-fault"); the fixture GTF gives every gene two exons with an intron (single-exon transcripts crash simpleaf's grangers intron pass: polars "invalid series dtype: expected List, got null"); the fixture genome is padded to ~52kb (STAR double-frees on the original 1.9 kb genome).

Run the acceptance test — validate, lint, and a dry-run plan check with the bundled fixtures:

bash test/run.sh

Apache-2.0. Copyright (c) 2026 oxo-flow-community. Upstream attribution in NOTICE.md; the upstream MIT license is retained verbatim in LICENSE.upstream.

https://oxo-flow-community.github.io/