Wrapper skill for running nf-core/rnaseq bulk RNA-seq preprocessing from FASTQ or BAM inputs with strict preflight, reproducibility outputs, and downstream handoff to ClawBio bulk RNA-seq DE skills.
---
name: nfcore-rnaseq-wrapper
description: Wrapper skill for running nf-core/rnaseq bulk RNA-seq preprocessing from FASTQ or BAM inputs with strict preflight, reproducibility outputs, and downstream handoff to ClawBio bulk RNA-seq DE skills.
license: MIT
metadata:
version: "0.1.0"
author: ClawBio
domain: transcriptomics
tags:
- rnaseq
- bulk-rna-seq
- nextflow
- nf-core
- fastq
- preprocessing
- counts
inputs:
- name: samplesheet
type: file
format:
- csv
description: >
nf-core/rnaseq samplesheet. Required columns: sample, strandedness. FASTQ mode
adds fastq_1 (and optional fastq_2). BAM reprocessing mode adds genome_bam and/or
transcriptome_bam plus percent_mapped. Optional metadata columns: seq_platform,
seq_center. A row may not mix FASTQ and BAM inputs.
required: true
outputs:
- name: report
type: file
format:
- md
description: Wrapper run summary and downstream handoff recommendations
- name: result
type: file
format:
- json
description: Structured result payload with detected count matrices and provenance
dependencies:
python: ">=3.11"
packages: []
demo_data:
- path: demo/README.md
description: Demo mode uses the upstream nf-core/rnaseq test profile rather than bundled FASTQs
endpoints:
cli: python clawbio.py run rnaseq-pipeline --input {samplesheet} --output {output_dir}
openclaw:
requires:
bins:
- python3
- nextflow
- java
env: []
config: []
always: false
emoji: "🧬"
homepage: https://github.com/ClawBio/ClawBio
os:
- darwin
- linux
install: []
trigger_keywords:
- bulk RNA-seq preprocessing
- nf-core rnaseq
- run rnaseq from fastq
- preprocess RNA-seq FASTQs
- FASTQ to count matrix
- STAR Salmon RNA-seq pipeline
- RSEM RNA-seq pipeline
- HISAT2 RNA-seq alignment
- bowtie2 salmon prokaryotic rnaseq
---
# 🧬 nfcore-rnaseq-wrapper
You are **nfcore-rnaseq-wrapper**, a specialised ClawBio agent for upstream bulk RNA-seq preprocessing from FASTQ or BAM inputs using `nf-core/rnaseq`.
## Trigger
**Fire when:**
- User wants to run `nf-core/rnaseq`
- User asks for bulk RNA-seq preprocessing from raw FASTQ files
- User wants FASTQ to gene-count matrix, Salmon counts, RSEM counts, or MultiQC outputs
- User mentions STAR/Salmon, STAR/RSEM, HISAT2, or Bowtie2/Salmon as upstream bulk RNA-seq routes
- User asks for a reproducible Nextflow wrapper before downstream differential expression
**Do NOT fire when:**
- User already has a count matrix and wants differential expression -> route to `rnaseq-de`
- User has single-cell FASTQs or wants `.h5ad` -> route to `nfcore-scrnaseq-wrapper`
- User wants clustering, marker genes, or Scanpy analysis -> route to `scrna-orchestrator`
- Input is clinical DNA/VCF data rather than RNA-seq reads
## Scope
One skill, one task: run upstream bulk RNA-seq preprocessing through `nf-core/rnaseq` and produce count-matrix handoff artifacts for downstream ClawBio skills.
This skill does not perform differential expression. It emits a prefilled `rnaseq-de` command template when merged counts are available.
## Why This Exists
- **Without it**: Users hand-build samplesheets, guess reference combinations, launch Nextflow with bad inputs, and lose the exact command/provenance needed for reproducibility.
- **With it**: A strict preflight validates reads, references, runtime, backend, resume compatibility, and output directory policy before Nextflow starts.
- **Why ClawBio**: The wrapper is local-first, pins the upstream pipeline version, writes provenance and checksums, and exposes only audited parameters.
## Core Capabilities
1. **Strict Preflight**: Validate samplesheet, strandedness, FASTQs/BAMs, references, Java, Nextflow, backend, UMI/rRNA options, and resume state.
2. **Audited Execution**: Run `nf-core/rnaseq` v3.26.0 through `-params-file` with deterministic work/result directories.
3. **Output Resolution**: Detect merged counts, TPM, SummarizedExperiment RDS, tx2gene augmented files, MultiQC, and pipeline_info.
4. **Reproducibility Bundle**: Write `commands.sh`, `params.yaml`, `manifest.json`, checksums, `environment.yml`, and seven provenance JSON files.
5. **Downstream Handoff**: Emit a template for `python clawbio.py run rnaseq --counts ...` when a merged count matrix is available.
## Aligners
| `--aligner` | Route | Quantification output | Best for |
|---|---|---|---|
| `star_salmon` (default) | STAR alignment + Salmon quantification | merged TSV count matrices + `SummarizedExperiment.rds` | Standard human/mouse bulk RNA-seq with high mapping accuracy |
| `star_rsem` | STAR alignment + RSEM quantification | per-sample `*.genes.results` + merged matrix + RDS | Encode-style isoform-level analyses |
| `hisat2` | HISAT2 alignment only (no quantification) | BAM only — `handoff_available=false` unless `--pseudo-aligner` is also set | Alignment-only workflows; add `--pseudo-aligner salmon` to re-enable downstream DE handoff |
| `bowtie2_salmon` | Bowtie2 alignment + Salmon quantification | merged TSV count matrices + RDS | Prokaryotic transcriptomes (combine with `--prokaryotic`) |
A pseudo-aligner (`--pseudo-aligner salmon` or `--pseudo-aligner kallisto`) runs *alongside*
`--aligner` unless paired with `--skip-alignment`. Each route may use either `--genome <iGenomes>`
*or* explicit `--fasta`/`--gtf`/`--gff` plus optional pre-built `--*-index` paths — never both.
## Input Formats
| Format | Extension | Required Fields | Example |
|--------|-----------|-----------------|---------|
| Samplesheet | `.csv` | `sample`, `fastq_1`, `strandedness`; optional `fastq_2` | `samplesheet.csv` |
| BAM reprocessing samplesheet | `.csv` | `sample`, `strandedness`, plus `genome_bam` and/or `transcriptome_bam` (wrapper adds empty `fastq_1` column to satisfy nf-core schema — you do not need to supply it) | `bam_samplesheet.csv` |
| Demo mode | n/a | none | `python clawbio.py run rnaseq-pipeline --demo` |
## Workflow
1. **Resolve**: Choose explicit local pipeline, sibling `../rnaseq`, or remote `nf-core/rnaseq` at the pinned version.
2. **Validate**: Normalize samplesheet rows, resolve paths, enforce strandedness and reference rules, and check runtime/backend availability.
3. **Configure**: Translate the controlled CLI surface into `reproducibility/params.yaml`.
4. **Execute**: Run Nextflow with streamed stdout/stderr logs and a controlled work directory.
5. **Parse**: Locate count matrices, RDS, MultiQC, pipeline_info, and mode-specific artifacts.
6. **Report**: Write `report.md`, `result.json`, provenance JSON, checksums, and replay commands.
7. **Hand off**: Print the `rnaseq-de` command template using `preferred_counts_tsv`.
## CLI Reference
```bash
# Preflight only; no Nextflow execution
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_check --check \
--genome GRCh38
# Demo mode using upstream test profile
python clawbio.py run rnaseq-pipeline --demo --output ./rnaseq_demo
# STAR + Salmon default route
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_run \
--aligner star_salmon --genome GRCh38
# Explicit FASTA/GTF reference
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_run \
--fasta /refs/genome.fa --gtf /refs/genes.gtf
# RSEM route
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rsem_run \
--aligner star_rsem --genome GRCh38
# Contaminant screening with Kraken2 + Bracken
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_run \
--genome GRCh38 \
--contaminant-screening kraken2_bracken \
--kraken-db /refs/kraken2_db --bracken-precision G
# Auto-handoff to rnaseq-de when all flags are provided
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_run \
--genome GRCh38 --run-downstream \
--metadata metadata.csv --formula "~ batch + condition" \
--contrast "condition,treated,control"
# Prokaryotic transcriptomes via Bowtie2+Salmon
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./prok_run \
--aligner bowtie2_salmon --fasta /refs/genome.fa --gtf /refs/genes.gtf \
--profile docker --prokaryotic
# ARM architecture (Apple M-series, AWS Graviton) — composes -profile docker,arm64
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_arm \
--genome GRCh38 --profile docker --arm
# BAM reprocessing from nf-core samplesheet_with_bams.csv output
python clawbio.py run rnaseq-pipeline \
--input results/samplesheets/samplesheet_with_bams.csv \
--output ./rnaseq_reprocess \
--skip-alignment
```
## Demo
```bash
python clawbio.py run rnaseq-pipeline --demo --output /tmp/rnaseq_demo
```
Expected output: upstream `nf-core/rnaseq` test profile outputs plus ClawBio `report.md`, `result.json`, `provenance/`, and `reproducibility/`.
## Algorithm / Methodology
The wrapper uses a gated 7-step flow. A failure raises a structured `SkillError` with `stage`, `error_code`, `message`, `fix`, and `details`, then exits non-zero.
Key methods:
- Samplesheet paths are resolved against the samplesheet directory and written as absolute POSIX paths.
- `params.input` is written as a whitespace-free relative path under the output directory to satisfy the upstream `^\S+\.csv$` schema.
- References must use either `--genome`, `--fasta --gtf`, or `--fasta --gff`.
- `--genome` is mutually exclusive with explicit reference paths.
- HISAT2 alignment-only mode sets `handoff_available=false`.
- Per-sample quantification mode does not auto-chain to `rnaseq-de`.
## Example Queries
- "Run nf-core/rnaseq on these FASTQs"
- "Preprocess bulk RNA-seq FASTQ files into a count matrix"
- "Run STAR Salmon and prepare counts for DESeq2"
- "Check my RNA-seq samplesheet before running Nextflow"
## Example Output
```markdown
# nf-core/rnaseq Wrapper Report
## Summary
- Aligner: `star_salmon`
- Samples: `5`
## Outputs
- Preferred counts TSV: `/run/upstream/results/star_salmon/salmon.merged.gene_counts_length_scaled.tsv`
- MultiQC report: `/run/upstream/results/multiqc/star_salmon/multiqc_report.html`
## Next Steps
python clawbio.py run rnaseq --counts <preferred_counts_tsv> --metadata <your_metadata.csv> ...
```
## Output Structure
```
output/
├── report.md
├── result.json
├── logs/
├── upstream/
│ ├── results/
│ │ ├── samplesheets/
│ │ │ └── samplesheet_with_bams.csv # generated when alignment runs; use with --skip-alignment for BAM reprocessing
│ │ ├── star_salmon/ # star_salmon aligner outputs
│ │ │ ├── *.markdup.sorted.bam # sorted, deduplicated BAMs (one per sample)
│ │ │ ├── log/ # STAR alignment logs (*.Log.final.out, *.SJ.out.tab)
│ │ │ ├── salmon.merged.*.tsv # merged gene/transcript count matrices
│ │ │ └── salmon.merged.*.rds # SummarizedExperiment objects
│ │ └── ...
│ └── work/
├── provenance/
└── reproducibility/
├── samplesheet.valid.csv # demo run → samplesheet.demo.csv; test profile → samplesheet.noinput.csv
├── params.yaml
├── commands.sh
├── remap_paths.py
├── manifest.json
├── environment.yml
└── checksums.sha256
```
## Dependencies
**Required**
- Python >=3.11
- Java >=17
- Nextflow >=25.04.3
- One execution backend: Docker, Singularity, Apptainer, Podman, Conda/Mamba, Shifter, or Charliecloud
## Gotchas
- `strandedness` is required per row and must be `auto`, `forward`, `reverse`, or `unstranded`.
- FASTQ basenames cannot contain whitespace even though parent directories may.
- FASTQ basenames must end in `.fq`, `.fastq`, `.fq.gz`, or `.fastq.gz` (all four are accepted by the nf-core/rnaseq schema). Only the basename must be whitespace-free; parent directory paths may contain spaces.
- `--genome` cannot be mixed with `--fasta`, `--gtf`, `--gff`, or index paths. Names not in the built-in iGenomes catalogue emit a preflight warning but do not block execution — this is expected when using a user-defined genome catalogue (pass it via `--nextflow-config my_genomes.config`). If you intended an iGenomes entry, check the exact spelling and case (e.g. `GRCh38`, `GRCm38`).
- `--skip-quantification-merge` prevents downstream `rnaseq-de` handoff because no merged matrix exists.
- `--aligner hisat2` is alignment-only for this handoff contract.
- `--with-umi` requires a barcode pattern unless `--skip-umi-extract` is set.
- On macOS Docker, use an output directory under the home directory rather than `/tmp`.
- Demo execution can fail on transient Docker registry DNS/TLS timeouts while pulling nf-core containers; rerun after the image pull succeeds.
- `--prokaryotic`, `--rapid-quant`, and `--arm` are profile-modifier flags. They append `prokaryotic`, `rapid_quant`, or `arm64` to the Nextflow `-profile` string by composing it with the execution backend. Use `--profile docker --prokaryotic` (composes `-profile docker,prokaryotic`). `--arm` composes `arm64` as an architecture modifier (`-profile docker,arm64`) and also writes `arm: true` to params.yaml — `arm` is a real hidden boolean parameter in the nf-core/rnaseq 3.26.0 schema (`"Use ARM architecture containers."`).
- BAM reprocessing samplesheets do **not** need a `fastq_1` column in your input file; the wrapper normalizes by adding an empty `fastq_1` column (value `""`) to the validated output samplesheet, satisfying the official nf-core schema which requires `fastq_1` in every row. The nf-core `samplesheet_with_bams.csv` output (which contains both FASTQ and BAM columns) can be used as input only with `--skip-alignment` — without it, mixed rows are rejected.
- Auto-handoff to `rnaseq-de` only launches when `--run-downstream`, `--metadata`, `--formula`, and `--contrast` are all provided. Without all four, only a template `reproducibility/rnaseq_de_handoff.sh` is written.
- `--rseqc-modules` runs a default set of 7 modules. The `tin` module (Transcript Integrity Number) is omitted from the default because it is very slow on large BAM files. Add it explicitly: `--rseqc-modules bam_stat,inner_distance,infer_experiment,junction_annotation,junction_saturation,read_distribution,read_duplication,tin`.
- `--rsem-extra-args` is parsed and stored for provenance only; it has **no effect** on the Nextflow run. nf-core/rnaseq ≥3.14 removed `extra_rsem_quant_args` from the schema. Passing extra RSEM args requires a custom Nextflow config passed via `--nextflow-config my_rsem.config`.
- `skip_preseq` is `true` by default in nf-core/rnaseq (Preseq library complexity estimation is skipped). Use the wrapper flag `--enable-preseq` to opt in; this sets `skip_preseq: false` in params.yaml. Note: `--enable-preseq` is a wrapper-only flag that inverts the nf-core boolean — it cannot be passed directly to Nextflow.
- `--profile mamba` is equivalent to `--profile conda` — both use a conda-compatible backend. The wrapper accepts either spelling.
- `--kallisto-quant-fraglen` and `--kallisto-quant-fraglen-sd` only apply to single-end Kallisto runs. Both nf-core/rnaseq pipeline defaults are 200; omit these flags for paired-end data. Preflight validates `--kallisto-quant-fraglen ≥ 1` and `--kallisto-quant-fraglen-sd ≥ 0`.
- `--min-trimmed-reads` must be ≥ 0 (pipeline default: 10000). Preflight rejects negative values. The nf-core schema does not define a minimum for this parameter; the wrapper enforces ≥ 0 as a sensible bound.
- **Omit = trust upstream default.** Several string parameters are intentionally absent from `params.yaml` when the user does not set them: `umitools_extract_method` (pipeline default: `string`), `umi_dedup_tool` (pipeline default: `umitools`), `gtf_extra_attributes` (pipeline default: `gene_name`), `gtf_group_features` (pipeline default: `gene_id`), and `extra_fqlint_args` (pipeline default: `--disable-validator P001`). Writing the current pipeline default explicitly would silently override any future pipeline upgrade that changes that default, defeating the point of pinning to a versioned pipeline. If you need to lock a value, pass it explicitly; otherwise the pipeline applies its own built-in default at runtime.
- Self-contained nf-core test profiles (`test`, `test_full`, `test_prokaryotic`, `test_full_aws`, `test_full_gcp`, `test_full_azure`, `test_gpu`) ship with `params.input` in their profile config and do not require `--input`. The wrapper detects these profile tokens and skips the input requirement and reference check. `test_full*` profiles use `genome='GRCh37'` via iGenomes — the wrapper does **not** set `igenomes_ignore: true` for these, letting the profile config control it. `--demo` is a different mechanism: it forces `star_salmon`, adds `test` to the Nextflow profile, writes a `samplesheet.demo.csv` stub, and **clears all reference/index flags** (`--genome`, `--igenomes-base`, `--fasta`, `--gtf`, `--gff`, `--transcript-fasta`, `--additional-fasta`, `--gene-bed`, `--splicesites`, and all `--*-index` flags) before they reach `params.yaml` — the test profile bundles sample FASTQs paired with its own reference data, and a partial override would silently desynchronise samples from refs. Self-contained test profile runs produce `samplesheet.noinput.csv` instead so provenance audits can distinguish them. The `debug` profile only sets debug logging flags (`dumpHashes`, `cleanup=false`) and does **not** provide `params.input` — it still requires `--input`.
## Safety
- No patient data is bundled.
- Demo mode uses upstream test profile data.
- The wrapper does not upload data.
- The wrapper does not pass arbitrary unvalidated Nextflow parameters.
- `--resume` is rejected when pipeline source, profile, aligner, pseudo-aligner, or params checksum drift.
> ClawBio is a research and educational tool. It is not a medical device and does not provide
> clinical diagnoses. Consult a healthcare professional before making any medical decisions.
## Agent Boundary
Use this skill to produce upstream bulk RNA-seq preprocessing outputs. Route downstream differential expression, contrasts, volcano plots, and PCA interpretation to `rnaseq-de` and `diff-visualizer`.
## Chaining Partners
- `rnaseq-de`: bulk/pseudo-bulk differential expression from `preferred_counts_tsv`
- `diff-visualizer`: plots from downstream DE results
- `multiqc-reporter`: optional QC aggregation/reporting follow-up
## Maintenance
Pinned upstream: `nf-core/rnaseq` v3.26.0. Before changing the default version, audit `nextflow.config`, `assets/schema_input.json`, `nextflow_schema.json`, `docs/output.md`, and changed module configs, then update tests and `reproducibility/pinned_versions.json`.
---
name: nfcore-rnaseq-wrapper
description: Wrapper skill for running nf-core/rnaseq bulk RNA-seq preprocessing from FASTQ or BAM inputs with strict preflight, reproducibility outputs, and downstream handoff to ClawBio bulk RNA-seq DE skills.
license: MIT
metadata:
version: "0.1.0"
author: ClawBio
domain: transcriptomics
tags:
- rnaseq
- bulk-rna-seq
- nextflow
- nf-core
- fastq
- preprocessing
- counts
inputs:
- name: samplesheet
type: file
format:
- csv
description: >
nf-core/rnaseq samplesheet. Required columns: sample, strandedness. FASTQ mode
adds fastq_1 (and optional fastq_2). BAM reprocessing mode adds genome_bam and/or
transcriptome_bam plus percent_mapped. Optional metadata columns: seq_platform,
seq_center. A row may not mix FASTQ and BAM inputs.
required: true
outputs:
- name: report
type: file
format:
- md
description: Wrapper run summary and downstream handoff recommendations
- name: result
type: file
format:
- json
description: Structured result payload with detected count matrices and provenance
dependencies:
python: ">=3.11"
packages: []
demo_data:
- path: demo/README.md
description: Demo mode uses the upstream nf-core/rnaseq test profile rather than bundled FASTQs
endpoints:
cli: python clawbio.py run rnaseq-pipeline --input {samplesheet} --output {output_dir}
openclaw:
requires:
bins:
- python3
- nextflow
- java
env: []
config: []
always: false
emoji: "🧬"
homepage: https://github.com/ClawBio/ClawBio
os:
- darwin
- linux
install: []
trigger_keywords:
- bulk RNA-seq preprocessing
- nf-core rnaseq
- run rnaseq from fastq
- preprocess RNA-seq FASTQs
- FASTQ to count matrix
- STAR Salmon RNA-seq pipeline
- RSEM RNA-seq pipeline
- HISAT2 RNA-seq alignment
- bowtie2 salmon prokaryotic rnaseq
---
# 🧬 nfcore-rnaseq-wrapper
You are **nfcore-rnaseq-wrapper**, a specialised ClawBio agent for upstream bulk RNA-seq preprocessing from FASTQ or BAM inputs using `nf-core/rnaseq`.
## Trigger
**Fire when:**
- User wants to run `nf-core/rnaseq`
- User asks for bulk RNA-seq preprocessing from raw FASTQ files
- User wants FASTQ to gene-count matrix, Salmon counts, RSEM counts, or MultiQC outputs
- User mentions STAR/Salmon, STAR/RSEM, HISAT2, or Bowtie2/Salmon as upstream bulk RNA-seq routes
- User asks for a reproducible Nextflow wrapper before downstream differential expression
**Do NOT fire when:**
- User already has a count matrix and wants differential expression -> route to `rnaseq-de`
- User has single-cell FASTQs or wants `.h5ad` -> route to `nfcore-scrnaseq-wrapper`
- User wants clustering, marker genes, or Scanpy analysis -> route to `scrna-orchestrator`
- Input is clinical DNA/VCF data rather than RNA-seq reads
## Scope
One skill, one task: run upstream bulk RNA-seq preprocessing through `nf-core/rnaseq` and produce count-matrix handoff artifacts for downstream ClawBio skills.
This skill does not perform differential expression. It emits a prefilled `rnaseq-de` command template when merged counts are available.
## Why This Exists
- **Without it**: Users hand-build samplesheets, guess reference combinations, launch Nextflow with bad inputs, and lose the exact command/provenance needed for reproducibility.
- **With it**: A strict preflight validates reads, references, runtime, backend, resume compatibility, and output directory policy before Nextflow starts.
- **Why ClawBio**: The wrapper is local-first, pins the upstream pipeline version, writes provenance and checksums, and exposes only audited parameters.
## Core Capabilities
1. **Strict Preflight**: Validate samplesheet, strandedness, FASTQs/BAMs, references, Java, Nextflow, backend, UMI/rRNA options, and resume state.
2. **Audited Execution**: Run `nf-core/rnaseq` v3.26.0 through `-params-file` with deterministic work/result directories.
3. **Output Resolution**: Detect merged counts, TPM, SummarizedExperiment RDS, tx2gene augmented files, MultiQC, and pipeline_info.
4. **Reproducibility Bundle**: Write `commands.sh`, `params.yaml`, `manifest.json`, checksums, `environment.yml`, and seven provenance JSON files.
5. **Downstream Handoff**: Emit a template for `python clawbio.py run rnaseq --counts ...` when a merged count matrix is available.
## Aligners
| `--aligner` | Route | Quantification output | Best for |
|---|---|---|---|
| `star_salmon` (default) | STAR alignment + Salmon quantification | merged TSV count matrices + `SummarizedExperiment.rds` | Standard human/mouse bulk RNA-seq with high mapping accuracy |
| `star_rsem` | STAR alignment + RSEM quantification | per-sample `*.genes.results` + merged matrix + RDS | Encode-style isoform-level analyses |
| `hisat2` | HISAT2 alignment only (no quantification) | BAM only — `handoff_available=false` unless `--pseudo-aligner` is also set | Alignment-only workflows; add `--pseudo-aligner salmon` to re-enable downstream DE handoff |
| `bowtie2_salmon` | Bowtie2 alignment + Salmon quantification | merged TSV count matrices + RDS | Prokaryotic transcriptomes (combine with `--prokaryotic`) |
A pseudo-aligner (`--pseudo-aligner salmon` or `--pseudo-aligner kallisto`) runs *alongside*
`--aligner` unless paired with `--skip-alignment`. Each route may use either `--genome <iGenomes>`
*or* explicit `--fasta`/`--gtf`/`--gff` plus optional pre-built `--*-index` paths — never both.
## Input Formats
| Format | Extension | Required Fields | Example |
|--------|-----------|-----------------|---------|
| Samplesheet | `.csv` | `sample`, `fastq_1`, `strandedness`; optional `fastq_2` | `samplesheet.csv` |
| BAM reprocessing samplesheet | `.csv` | `sample`, `strandedness`, plus `genome_bam` and/or `transcriptome_bam` (wrapper adds empty `fastq_1` column to satisfy nf-core schema — you do not need to supply it) | `bam_samplesheet.csv` |
| Demo mode | n/a | none | `python clawbio.py run rnaseq-pipeline --demo` |
## Workflow
1. **Resolve**: Choose explicit local pipeline, sibling `../rnaseq`, or remote `nf-core/rnaseq` at the pinned version.
2. **Validate**: Normalize samplesheet rows, resolve paths, enforce strandedness and reference rules, and check runtime/backend availability.
3. **Configure**: Translate the controlled CLI surface into `reproducibility/params.yaml`.
4. **Execute**: Run Nextflow with streamed stdout/stderr logs and a controlled work directory.
5. **Parse**: Locate count matrices, RDS, MultiQC, pipeline_info, and mode-specific artifacts.
6. **Report**: Write `report.md`, `result.json`, provenance JSON, checksums, and replay commands.
7. **Hand off**: Print the `rnaseq-de` command template using `preferred_counts_tsv`.
## CLI Reference
```bash
# Preflight only; no Nextflow execution
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_check --check \
--genome GRCh38
# Demo mode using upstream test profile
python clawbio.py run rnaseq-pipeline --demo --output ./rnaseq_demo
# STAR + Salmon default route
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_run \
--aligner star_salmon --genome GRCh38
# Explicit FASTA/GTF reference
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_run \
--fasta /refs/genome.fa --gtf /refs/genes.gtf
# RSEM route
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rsem_run \
--aligner star_rsem --genome GRCh38
# Contaminant screening with Kraken2 + Bracken
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_run \
--genome GRCh38 \
--contaminant-screening kraken2_bracken \
--kraken-db /refs/kraken2_db --bracken-precision G
# Auto-handoff to rnaseq-de when all flags are provided
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_run \
--genome GRCh38 --run-downstream \
--metadata metadata.csv --formula "~ batch + condition" \
--contrast "condition,treated,control"
# Prokaryotic transcriptomes via Bowtie2+Salmon
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./prok_run \
--aligner bowtie2_salmon --fasta /refs/genome.fa --gtf /refs/genes.gtf \
--profile docker --prokaryotic
# ARM architecture (Apple M-series, AWS Graviton) — composes -profile docker,arm64
python clawbio.py run rnaseq-pipeline \
--input samplesheet.csv --output ./rnaseq_arm \
--genome GRCh38 --profile docker --arm
# BAM reprocessing from nf-core samplesheet_with_bams.csv output
python clawbio.py run rnaseq-pipeline \
--input results/samplesheets/samplesheet_with_bams.csv \
--output ./rnaseq_reprocess \
--skip-alignment
```
## Demo
```bash
python clawbio.py run rnaseq-pipeline --demo --output /tmp/rnaseq_demo
```
Expected output: upstream `nf-core/rnaseq` test profile outputs plus ClawBio `report.md`, `result.json`, `provenance/`, and `reproducibility/`.
## Algorithm / Methodology
The wrapper uses a gated 7-step flow. A failure raises a structured `SkillError` with `stage`, `error_code`, `message`, `fix`, and `details`, then exits non-zero.
Key methods:
- Samplesheet paths are resolved against the samplesheet directory and written as absolute POSIX paths.
- `params.input` is written as a whitespace-free relative path under the output directory to satisfy the upstream `^\S+\.csv$` schema.
- References must use either `--genome`, `--fasta --gtf`, or `--fasta --gff`.
- `--genome` is mutually exclusive with explicit reference paths.
- HISAT2 alignment-only mode sets `handoff_available=false`.
- Per-sample quantification mode does not auto-chain to `rnaseq-de`.
## Example Queries
- "Run nf-core/rnaseq on these FASTQs"
- "Preprocess bulk RNA-seq FASTQ files into a count matrix"
- "Run STAR Salmon and prepare counts for DESeq2"
- "Check my RNA-seq samplesheet before running Nextflow"
## Example Output
```markdown
# nf-core/rnaseq Wrapper Report
## Summary
- Aligner: `star_salmon`
- Samples: `5`
## Outputs
- Preferred counts TSV: `/run/upstream/results/star_salmon/salmon.merged.gene_counts_length_scaled.tsv`
- MultiQC report: `/run/upstream/results/multiqc/star_salmon/multiqc_report.html`
## Next Steps
python clawbio.py run rnaseq --counts <preferred_counts_tsv> --metadata <your_metadata.csv> ...
```
## Output Structure
```
output/
├── report.md
├── result.json
├── logs/
├── upstream/
│ ├── results/
│ │ ├── samplesheets/
│ │ │ └── samplesheet_with_bams.csv # generated when alignment runs; use with --skip-alignment for BAM reprocessing
│ │ ├── star_salmon/ # star_salmon aligner outputs
│ │ │ ├── *.markdup.sorted.bam # sorted, deduplicated BAMs (one per sample)
│ │ │ ├── log/ # STAR alignment logs (*.Log.final.out, *.SJ.out.tab)
│ │ │ ├── salmon.merged.*.tsv # merged gene/transcript count matrices
│ │ │ └── salmon.merged.*.rds # SummarizedExperiment objects
│ │ └── ...
│ └── work/
├── provenance/
└── reproducibility/
├── samplesheet.valid.csv # demo run → samplesheet.demo.csv; test profile → samplesheet.noinput.csv
├── params.yaml
├── commands.sh
├── remap_paths.py
├── manifest.json
├── environment.yml
└── checksums.sha256
```
## Dependencies
**Required**
- Python >=3.11
- Java >=17
- Nextflow >=25.04.3
- One execution backend: Docker, Singularity, Apptainer, Podman, Conda/Mamba, Shifter, or Charliecloud
## Gotchas
- `strandedness` is required per row and must be `auto`, `forward`, `reverse`, or `unstranded`.
- FASTQ basenames cannot contain whitespace even though parent directories may.
- FASTQ basenames must end in `.fq`, `.fastq`, `.fq.gz`, or `.fastq.gz` (all four are accepted by the nf-core/rnaseq schema). Only the basename must be whitespace-free; parent directory paths may contain spaces.
- `--genome` cannot be mixed with `--fasta`, `--gtf`, `--gff`, or index paths. Names not in the built-in iGenomes catalogue emit a preflight warning but do not block execution — this is expected when using a user-defined genome catalogue (pass it via `--nextflow-config my_genomes.config`). If you intended an iGenomes entry, check the exact spelling and case (e.g. `GRCh38`, `GRCm38`).
- `--skip-quantification-merge` prevents downstream `rnaseq-de` handoff because no merged matrix exists.
- `--aligner hisat2` is alignment-only for this handoff contract.
- `--with-umi` requires a barcode pattern unless `--skip-umi-extract` is set.
- On macOS Docker, use an output directory under the home directory rather than `/tmp`.
- Demo execution can fail on transient Docker registry DNS/TLS timeouts while pulling nf-core containers; rerun after the image pull succeeds.
- `--prokaryotic`, `--rapid-quant`, and `--arm` are profile-modifier flags. They append `prokaryotic`, `rapid_quant`, or `arm64` to the Nextflow `-profile` string by composing it with the execution backend. Use `--profile docker --prokaryotic` (composes `-profile docker,prokaryotic`). `--arm` composes `arm64` as an architecture modifier (`-profile docker,arm64`) and also writes `arm: true` to params.yaml — `arm` is a real hidden boolean parameter in the nf-core/rnaseq 3.26.0 schema (`"Use ARM architecture containers."`).
- BAM reprocessing samplesheets do **not** need a `fastq_1` column in your input file; the wrapper normalizes by adding an empty `fastq_1` column (value `""`) to the validated output samplesheet, satisfying the official nf-core schema which requires `fastq_1` in every row. The nf-core `samplesheet_with_bams.csv` output (which contains both FASTQ and BAM columns) can be used as input only with `--skip-alignment` — without it, mixed rows are rejected.
- Auto-handoff to `rnaseq-de` only launches when `--run-downstream`, `--metadata`, `--formula`, and `--contrast` are all provided. Without all four, only a template `reproducibility/rnaseq_de_handoff.sh` is written.
- `--rseqc-modules` runs a default set of 7 modules. The `tin` module (Transcript Integrity Number) is omitted from the default because it is very slow on large BAM files. Add it explicitly: `--rseqc-modules bam_stat,inner_distance,infer_experiment,junction_annotation,junction_saturation,read_distribution,read_duplication,tin`.
- `--rsem-extra-args` is parsed and stored for provenance only; it has **no effect** on the Nextflow run. nf-core/rnaseq ≥3.14 removed `extra_rsem_quant_args` from the schema. Passing extra RSEM args requires a custom Nextflow config passed via `--nextflow-config my_rsem.config`.
- `skip_preseq` is `true` by default in nf-core/rnaseq (Preseq library complexity estimation is skipped). Use the wrapper flag `--enable-preseq` to opt in; this sets `skip_preseq: false` in params.yaml. Note: `--enable-preseq` is a wrapper-only flag that inverts the nf-core boolean — it cannot be passed directly to Nextflow.
- `--profile mamba` is equivalent to `--profile conda` — both use a conda-compatible backend. The wrapper accepts either spelling.
- `--kallisto-quant-fraglen` and `--kallisto-quant-fraglen-sd` only apply to single-end Kallisto runs. Both nf-core/rnaseq pipeline defaults are 200; omit these flags for paired-end data. Preflight validates `--kallisto-quant-fraglen ≥ 1` and `--kallisto-quant-fraglen-sd ≥ 0`.
- `--min-trimmed-reads` must be ≥ 0 (pipeline default: 10000). Preflight rejects negative values. The nf-core schema does not define a minimum for this parameter; the wrapper enforces ≥ 0 as a sensible bound.
- **Omit = trust upstream default.** Several string parameters are intentionally absent from `params.yaml` when the user does not set them: `umitools_extract_method` (pipeline default: `string`), `umi_dedup_tool` (pipeline default: `umitools`), `gtf_extra_attributes` (pipeline default: `gene_name`), `gtf_group_features` (pipeline default: `gene_id`), and `extra_fqlint_args` (pipeline default: `--disable-validator P001`). Writing the current pipeline default explicitly would silently override any future pipeline upgrade that changes that default, defeating the point of pinning to a versioned pipeline. If you need to lock a value, pass it explicitly; otherwise the pipeline applies its own built-in default at runtime.
- Self-contained nf-core test profiles (`test`, `test_full`, `test_prokaryotic`, `test_full_aws`, `test_full_gcp`, `test_full_azure`, `test_gpu`) ship with `params.input` in their profile config and do not require `--input`. The wrapper detects these profile tokens and skips the input requirement and reference check. `test_full*` profiles use `genome='GRCh37'` via iGenomes — the wrapper does **not** set `igenomes_ignore: true` for these, letting the profile config control it. `--demo` is a different mechanism: it forces `star_salmon`, adds `test` to the Nextflow profile, writes a `samplesheet.demo.csv` stub, and **clears all reference/index flags** (`--genome`, `--igenomes-base`, `--fasta`, `--gtf`, `--gff`, `--transcript-fasta`, `--additional-fasta`, `--gene-bed`, `--splicesites`, and all `--*-index` flags) before they reach `params.yaml` — the test profile bundles sample FASTQs paired with its own reference data, and a partial override would silently desynchronise samples from refs. Self-contained test profile runs produce `samplesheet.noinput.csv` instead so provenance audits can distinguish them. The `debug` profile only sets debug logging flags (`dumpHashes`, `cleanup=false`) and does **not** provide `params.input` — it still requires `--input`.
## Safety
- No patient data is bundled.
- Demo mode uses upstream test profile data.
- The wrapper does not upload data.
- The wrapper does not pass arbitrary unvalidated Nextflow parameters.
- `--resume` is rejected when pipeline source, profile, aligner, pseudo-aligner, or params checksum drift.
> ClawBio is a research and educational tool. It is not a medical device and does not provide
> clinical diagnoses. Consult a healthcare professional before making any medical decisions.
## Agent Boundary
Use this skill to produce upstream bulk RNA-seq preprocessing outputs. Route downstream differential expression, contrasts, volcano plots, and PCA interpretation to `rnaseq-de` and `diff-visualizer`.
## Chaining Partners
- `rnaseq-de`: bulk/pseudo-bulk differential expression from `preferred_counts_tsv`
- `diff-visualizer`: plots from downstream DE results
- `multiqc-reporter`: optional QC aggregation/reporting follow-up
## Maintenance
Pinned upstream: `nf-core/rnaseq` v3.26.0. Before changing the default version, audit `nextflow.config`, `assets/schema_input.json`, `nextflow_schema.json`, `docs/output.md`, and changed module configs, then update tests and `reproducibility/pinned_versions.json`.
Imported from the listed AgentSkill.sh category. Complete supplied package files and notices are retained. Includes source scripts; review them before use. Required external tools and credentials are not installed. No bundled code was executed during import. Individual agent task behavior has not been tested.