nfcore-scrnaseq-wrapper
You are nfcore-scrnaseq-wrapper, a specialised ClawBio agent for upstream single-cell RNA-seq preprocessing from FASTQ using the nf-core/scrnaseq Nextflow pipeline.
Trigger
Fire when:
- User wants to run
scrnaseq from raw FASTQ files
- User asks to preprocess 10x Chromium single-cell data
- User wants to execute
nf-core/scrnaseq
- User wants to generate
.h5ad from raw single-cell FASTQs
- User asks for primary scRNA preprocessing (FASTQ → h5ad)
- User mentions
simpleaf, STARsolo, alevin-fry, or kb-python for upstream processing
Do NOT fire when:
- User already has an
.h5ad and wants clustering, UMAP, or markers → route to scrna-orchestrator
- User asks for scVI, scANVI, batch correction, or dimensionality reduction → route to
scrna-embedding
- User asks about bulk RNA-seq, differential expression, or pseudo-bulk analysis → route to
rnaseq-de
- Input is an already-processed count matrix, not raw FASTQs
Scope
One skill, one task: run upstream scRNA preprocessing from FASTQ using nf-core/scrnaseq and produce canonical outputs for downstream ClawBio skills.
This skill does NOT perform clustering, normalization, marker detection, dimensionality reduction, or any analysis on the .h5ad it produces.
Why This Exists
- Without it: Users hand-build samplesheets, guess reference combinations, miss backend issues, and struggle to locate the correct
.h5ad for downstream analysis.
- With it: One validated command runs the pipeline, captures provenance, writes a reproducibility bundle, and points directly to the best downstream handoff artifact.
- Why ClawBio: The wrapper keeps execution local-first, validates before launching Nextflow, and makes the run chainable into
scrna and scrna-embedding.
Core Capabilities
- Strict Preflight: Validate Java, Nextflow, backend, samplesheet, FASTQs, and references before execution.
- Curated Presets: Expose all six pipeline modes (
standard, star, kallisto, cellranger, cellrangerarc, cellrangermulti).
- Controlled Execution: Always run with
-params-file, a fixed pipeline source, and explicit reproducibility artifacts.
- Output Resolution: Detect MultiQC, pipeline_info,
.h5ad, .rds, and select a canonical preferred_h5ad when possible.
- Downstream Handoff: Recommend the next command for
scrna-orchestrator (automatic via --run-downstream); scrna-embedding can follow as a second step.
Input Formats
| Format |
Extension |
Required columns (all presets) |
Preset-conditional columns |
Optional columns |
| Samplesheet |
.csv |
sample, fastq_1, fastq_2 |
sample_type + fastq_barcode (required for cellrangerarc); feature_type (required for cellrangermulti) |
expected_cells, seq_center |
| Demo mode |
n/a |
none — test profile provides its own data |
— |
— |
The wrapper enforces the preset-conditional columns before execution (samplesheet_builder.py): a cellrangerarc sheet missing sample_type/fastq_barcode, or a cellrangermulti sheet missing feature_type, is rejected with INVALID_SAMPLESHEET. Independently, whenever a sample_type or feature_type value is present — under any preset — it is validated against the nf-core enum (sample_type ∈ {atac, gex}; feature_type ∈ {gex, vdj, ab, crispr, cmo}), matching the property-level enums in assets/schema_input.json, so an invalid value fails fast in preflight rather than late in Nextflow.
Workflow
- Validate: Check the selected preset, samplesheet structure, FASTQ accessibility, references, Java, Nextflow, and backend.
- Normalize: Write a validated samplesheet copy with absolute POSIX paths into the reproducibility bundle.
- Configure: Build one effective
params.yaml and a fixed Nextflow command.
- Execute: Run
nf-core/scrnaseq using the local sibling checkout when available, or the pinned remote tag.
- Parse: Detect MultiQC, pipeline_info,
.h5ad, .rds, and CellBender-derived outputs.
- Generate: Write
report.md, result.json, provenance JSON files, and reproducibility artifacts.
- Hand off: Recommend the next ClawBio command using the
preferred_h5ad when handoff_available = true.
Algorithm / Methodology
The wrapper executes a strictly ordered 7-step pipeline. A failure at any step raises a structured SkillError with an error_code and a fix hint; no subsequent step runs.
Pipeline source resolution (pipeline_source.py): Prefer a local sibling scrnaseq/ checkout (pinned commit, audit-safe). Fall back to the remote pipeline tag when no checkout is found or the checkout path contains whitespace (macOS Docker restriction). A dirty local checkout is rejected by default; --allow-dirty-pipeline is an explicit development-only opt-in that is recorded in provenance. Use --require-local-pipeline when fallback to the remote pipeline would be unacceptable.
Samplesheet validation (samplesheet_builder.py): Parse the CSV, resolve FASTQ paths relative to the CSV parent directory, normalize sample-name whitespace to underscores, verify readability and FASTQ extensions, reject FASTQ basenames with whitespace, enforce consistent expected_cells (≥1) and seq_center for repeated sample rows, reject exact duplicate FASTQ rows, and write a normalized copy to reproducibility/samplesheet.valid.csv with local FASTQ paths resolved to absolute POSIX (remote URIs, accepted only with --allow-remote-inputs, are passed through unchanged). The normalized replay sheet contains only headers accepted by the pinned 4.1.0 assets/schema_input.json; unsupported metadata columns are reported and omitted. In particular, protocol is supplied through the global --protocol parameter and is never forwarded as a samplesheet column.
Preflight (preflight.py): Verify Java (≥17) and Nextflow (≥25.04.0). Compare version tuples after zero-padding to 3 elements (avoids false negatives such as (24, 4) < (24, 4, 0)). For docker, run docker info and gate on exit code. For conda/mamba, locate the binary. Cell Ranger presets are rejected with conda/mamba unless --allow-conda-cellranger is supplied with a trusted site config. For singularity/apptainer, accept either binary interchangeably. For wave and gpu, no binary check is needed (Nextflow-native features). Safe institutional profile components are accepted for HPC/site profiles, every -c/--config file must exist before execution, and configs are treated as trusted Groovy code. All preflight subprocess calls have a 60-second timeout (_SUBPROCESS_TIMEOUT in preflight.py); the git probes in pipeline_source.py use a 10-second timeout.
Params construction (params_builder.py): Translate the preset + CLI flags into a params.yaml consumed by Nextflow via -params-file. All file paths use .as_posix() for forward-slash consistency across platforms. igenomes_ignore is automatically set to true whenever an explicit genome reference (fasta, gtf, transcript_fasta, txp2gene, or any prebuilt index) is provided — auxiliary files (barcode whitelist, CMO/probe/feature sets, primers, multi-barcode samplesheets) never trigger it, so they remain compatible with --genome (suppresses nf-schema DNS validation of the default iGenomes S3 URL). Skip flags are only written when true, keeping params.yaml minimal. In --demo mode no reference/protocol params are written at all (the test profile owns them).
Command build + execution (command_builder.py, executor.py): Construct the nextflow run command with -params-file, validated -c/--config files, and a work directory that defaults to <output>/upstream/work but may be overridden by --work-dir (including object-store URIs for cloud executors), then launch via subprocess.Popen with stdout and stderr piped to log files on disk — never buffered in RAM. On TimeoutExpired, the process is killed and EXECUTION_FAILED is raised. On KeyboardInterrupt, the child process tree is terminated before the interrupt is re-raised.
Output parsing (outputs_parser.py): Scan the upstream results tree for MultiQC HTML, pipeline_info/, aligner output directories, .h5ad (CellBender/filtered preferred over generic combined/raw), .rds, CellBender-derived files, and an official_outputs manifest for documented nf-core output families. Required outputs are validated before success artifacts are written; handoff_available is set to true only when a preferred_h5ad is confirmed on disk.
Provenance + reporting (provenance.py, reporting.py): Write JSON provenance bundles, a SHA-256 checksum manifest (files only — never directories), environment.yml, a portable commands.sh, report.md, and result.json.
Presets
| Preset |
Aligner |
Use case |
standard |
simpleaf (alevin-fry) |
Default for 10x GEX; fast, memory-efficient |
star |
STARsolo |
Best FASTQ QC metrics; supports RNA velocity (--star-feature "Gene Velocyto") |
kallisto |
kb-python / BUStools |
Pseudo-alignment; fastest; lamanno/nac RNA velocity via --kb-workflow |
cellranger |
CellRanger |
CellRanger v2/v3 compatibility; CellRanger is provided by the nf-core container under docker/singularity (no host binary needed). Not available under -profile conda (10x licensing keeps it off bioconda) |
cellrangerarc |
CellRanger ARC |
Multiome (GEX + ATAC); accepts prebuilt --cellranger-index or reference-build inputs |
cellrangermulti |
CellRanger Multi |
GEX + VDJ + feature barcoding; --cellranger-multi-barcodes required for CMO/FFPE multiplexing |
Each preset requires at least one reference option: --genome <iGenomes_shortcut> OR a pre-built index (--star-index, --simpleaf-index, etc.) OR --fasta + --gtf. The standard/simpleaf preset additionally accepts a transcriptome pair --transcript-fasta + --txp2gene in place of a genome reference (per the nf-core/scrnaseq Simpleaf options).
nf-core/scrnaseq 4.1.0 Compatibility Policy
This wrapper targets nf-core/scrnaseq 4.1.0. It is not a free-form passthrough. Parameters are grouped as:
- Supported upstream parameters: input/output, aligner/preset, reference/index, skip, CellRanger, CellRanger ARC, CellRanger Multi, selected MultiQC/reporting options.
- Wrapper policy parameters:
--preset, --check, --run-downstream, --skip-downstream, --expected-cells, --timeout-hours, --work-dir, --allow-remote-inputs, --allow-dirty-pipeline, --require-local-pipeline, --allow-pipeline-version-override, --trust-config-params, --allow-conda-cellranger, and -c/--config/--nextflow-config; these are ClawBio conveniences and are not nf-core parameters.
- Deprecated compatibility aliases:
skip_emptydrops is accepted only as --skip-emptydrops and translated to skip_cellbender: true; the deprecated upstream parameter is never written.
- Intentionally unsupported upstream parameters:
custom_config_version, custom_config_base, config_profile_name, config_profile_description, config_profile_contact, config_profile_url, version, plaintext_email, max_multiqc_email_size, hook_url, validate_params, pipelines_testdata_base_path, help, help_full, show_hidden.
Unsupported parameters are either hidden/institutional metadata, interactive help/version flags, or options that would weaken the wrapper's fixed validation/reproducibility policy.
Input & Reference Path Policy
Local-first by default. Samplesheet FASTQs and reference/index inputs must be local paths unless you explicitly opt in. Remote URIs (s3://, gs://, https://, ftp://, …) are rejected at preflight with REMOTE_INPUT_NOT_ALLOWED, so genetic data and references stay on the local machine and no accidental cloud fetch happens. This guarantee is enforced by the code, not just advertised (preflight._check_remote_inputs).
Opt-in for remote inputs. Pass --allow-remote-inputs to permit remote samplesheet inputs and reference paths (parity with nfcore-sarek-wrapper / nfcore-rnaseq-wrapper, which share the same flag). When enabled, remote URIs are passed through verbatim (Nextflow resolves and stages them; only the FASTQ/FASTA basename is validated) and preflight emits a runtime WARNING listing every path that will be fetched over the network, so cloud access is always visible. The object-store --work-dir is a separate setting and is not gated.
Local paths are still validated eagerly at preflight so they fail fast with a clear error instead of a late Nextflow error:
- A supplied local reference/index path (
--fasta, --gtf, --star-index, …) that does not exist raises MISSING_REFERENCE (preflight.py).
- A local FASTQ that does not exist (or is not a regular file) raises
MISSING_FASTQ (samplesheet_builder.py).
Readability is never pre-checked: Nextflow reads inputs in the true execution context (often a root container under the default Docker profile), so a launcher-side os.access(R_OK) probe would false-block valid runs (errors.py).
CLI Reference
# Standard real-data usage (explicit protocol and reference are required)
python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \
--input samplesheet.csv --output ./scrnaseq_run \
--preset star --protocol 10XV3 --genome GRCh38
# Preflight check only (no Nextflow execution)
python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \
--input samplesheet.csv --output ./scrnaseq_run --check \
--preset star --protocol 10XV3 --genome GRCh38
# Demo mode (runs the upstream nf-core test profile; forces star preset; uses the
# selected backend — default --profile docker, which must be running)
python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \
--demo --output ./scrnaseq_demo
# Via ClawBio runner
python clawbio.py run scrnaseq-pipeline --input samplesheet.csv --output ./scrnaseq_run \
--preset star --protocol 10XV3 --genome GRCh38
python clawbio.py run scrnaseq-pipeline --demo --output ./scrnaseq_demo
# STARsolo with local FASTA+GTF (STAR index built by the pipeline)
python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \
--input samplesheet.csv --output ./run --preset star --protocol 10XV3 \
--fasta /refs/hg38.fa --gtf /refs/hg38.gtf
# STARsolo with prebuilt STAR index
python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \
--input samplesheet.csv --output ./run --preset star --protocol 10XV3 \
--star-index /refs/star_index
# STARsolo RNA velocity (star requires an explicit --protocol like every star/standard/kallisto run)
python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \
--input samplesheet.csv --output ./run --preset star --protocol 10XV3 \
--star-feature "Gene Velocyto" --star-ignore-sjdbgtf \
--fasta /refs/hg38.fa --gtf /refs/hg38.gtf
# Simpleaf (standard) with UMI resolution override
python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \
--input samplesheet.csv --output ./run --preset standard --protocol 10XV3 \
--simpleaf-umi-resolution cr-like-em --genome GRCh38
# Kallisto RNA velocity (NAC workflow)
python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \
--input samplesheet.csv --output ./run --preset kallisto --protocol 10XV3 \
--kb-workflow nac --fasta /refs/hg38.fa --gtf /refs/hg38.gtf
# Air-gapped cluster: local iGenomes mirror
python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \
--input samplesheet.csv --output ./run --preset star --protocol 10XV3 \
--genome GRCh38 --igenomes-base /mnt/local_igenomes
# CellRanger Multi (CMO multiplexing)
python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \
--input samplesheet.csv --output ./run --preset cellrangermulti \
--cellranger-index /refs/refdata-gex-GRCh38 \
--gex-cmo-set /refs/cmo_set.csv \
--cellranger-multi-barcodes /refs/multi_barcodes.csv
Key flags
| Flag |
Type |
Default |
Description |
--input |
path |
— |
Samplesheet CSV (sample,fastq_1,fastq_2). Required unless --demo |
--output |
path |
— |
Output directory for results and the reproducibility bundle (required) |
--demo |
flag |
— |
Run the upstream nf-core test profile; forces --preset star and skip_cellbender |
--check |
flag |
— |
Run preflight only and exit (no Nextflow execution); check_result.json lists the nf-core parameter surface under parameter_support (supported upstream, wrapper policy, and intentionally unsupported parameters) |
--preset |
string |
standard |
Aligner preset |
--aligner |
string |
— |
nf-core/scrnaseq aligner alias for --preset: simpleaf maps to standard; the other values map to same-named presets |
--profile |
string |
docker |
Execution backend or comma-separated nf-core profile list: docker, conda, mamba, singularity, apptainer, podman, shifter, charliecloud, wave, gpu, debug, arm64, emulate_amd64, test, test_full, test_cellrangermulti, test_multiome |
--pipeline-version |
string |
4.1.0 |
Remote nf-core/scrnaseq tag or commit (used when no local sibling checkout is found) |
--allow-dirty-pipeline |
flag |
— |
Development-only opt-in to run a modified local sibling scrnaseq/ checkout; rejected by default for production reproducibility |
--require-local-pipeline |
flag |
— |
Require a verifiable local sibling scrnaseq/ checkout; fail instead of falling back to the remote pipeline |
--allow-pipeline-version-override |
flag |
— |
Allow a --pipeline-version other than the pinned 4.1.0 contract (warned, recorded in provenance; validations stay 4.1.0) |
--trust-config-params |
flag |
— |
Allow -c/--config files that set params.* (otherwise blocked); detected overrides are recorded in provenance |
-c / --config |
path |
— |
Additional Nextflow config file. May be repeated; files are validated, applied to the live run, copied into the reproducibility bundle, and replayed by commands.sh |
--protocol |
string |
None |
Chemistry/protocol forwarded to the aligner. Required for standard, star, and kallisto; omitted only preserves CellRanger auto-detection for cellranger, cellrangerarc, and cellrangermulti. Explicit auto is invalid for standard, star, and kallisto. smartseq is valid for star and kallisto only. Other protocol strings are mapped when known or passed through by nf-core |
--genome |
string |
— |
iGenomes shortcut (GRCh38, mm10, etc.) — mutually exclusive with --fasta/--gtf and all index flags |
--igenomes-base |
string |
— |
Base URL or local path for iGenomes (default s3://ngi-igenomes/igenomes/). Use for local mirrors or air-gapped clusters. A local base path is existence-checked in preflight when --genome is set (remote s3:///https:// bases are deferred to Nextflow) |
--igenomes-ignore |
flag |
— |
Do not load the iGenomes reference config. Set automatically whenever an explicit genome reference is supplied; only needed manually in unusual setups |
--fasta |
path |
— |
Genome FASTA (.fa, .fna, .fasta, .gz variants; no whitespace in path) |
--gtf |
path |
— |
Gene annotation GTF |
--star-index |
path |
— |
Prebuilt STAR genome index directory |
--simpleaf-index |
path |
— |
Prebuilt simpleaf/alevin-fry index |
--kallisto-index |
path |
— |
Prebuilt kallisto index |
--cellranger-index |
path |
— |
Prebuilt CellRanger or CellRanger ARC reference |
--transcript-fasta |
path |
— |
Transcriptome FASTA for simpleaf |
--txp2gene |
path |
— |
Transcript-to-gene mapping for simpleaf |
--barcode-whitelist |
path |
— |
Custom barcode whitelist (per-aligner format) |
--star-feature |
enum |
— |
STARsolo feature type: Gene, GeneFull, Gene Velocyto |
--star-ignore-sjdbgtf |
flag |
— |
Do not use GTF for SJDB construction (required for Gene Velocyto) |
--seq-center |
string |
— |
Sequencing center name for BAM read group tag |
--simpleaf-umi-resolution |
enum |
— |
UMI resolution strategy for alevin-fry: cr-like, cr-like-em, parsimony, parsimony-em, parsimony-gene, parsimony-gene-em |
--kb-workflow |
enum |
— |
Kallisto workflow: standard, lamanno, nac |
--kb-t1c |
path |
— |
cDNA transcripts-to-capture file for RNA velocity (lamanno/nac). Required only with a prebuilt --kallisto-index; auto-generated from --fasta/--gtf |
--kb-t2c |
path |
— |
Intron transcripts-to-capture file for RNA velocity (lamanno/nac). Required only with a prebuilt --kallisto-index; auto-generated from --fasta/--gtf |
--skip-cellbender |
flag |
— |
Disable the CellBender ambient RNA removal subworkflow |
--skip-emptydrops |
flag |
— |
Deprecated compatibility alias for --skip-cellbender; the wrapper writes skip_cellbender: true and never writes deprecated upstream skip_emptydrops |
--skip-fastqc |
flag |
— |
Skip FastQC quality control |
--skip-multiqc |
flag |
— |
Skip MultiQC report generation |
--skip-cellranger-renaming |
flag |
— |
Skip automatic sample renaming in CellRanger modules |
--skip-cellrangermulti-vdjref |
flag |
— |
Skip mkvdjref in cellrangermulti (when VDJ data is absent or a prebuilt --cellranger-vdj-index is supplied) |
--save-reference |
flag |
— |
Save the built reference index for future reuse |
--save-align-intermeds / --no-save-align-intermeds |
flag |
— |
Forward save_align_intermeds: true/false; when neither is given the upstream nf-core/scrnaseq 4.1.0 default (true) is preserved, so intermediate BAMs are published by default — pass --no-save-align-intermeds on large runs to save disk |
--expected-cells |
int |
— |
Override expected cell count for a single-sample samplesheet; multi-sample runs must set expected_cells per row. The wrapper enforces ≥1 (stricter than the upstream integer schema, which has no minimum) since a non-positive count is meaningless |
--timeout-hours |
float |
12 |
Wall-clock cap for the Nextflow run, in hours. Use 0 to disable the cap for long HPC/cloud runs whose walltime is enforced by the scheduler. Via the ClawBio runner the runner's own timeout also applies |
--work-dir |
string |
<output>/upstream/work |
Nextflow work directory. Local paths are resolved before execution; object-store URIs such as s3://... or gs://... are passed through for cloud executors |
--allow-conda-cellranger |
flag |
— |
Allow Cell Ranger presets with conda/mamba only when a trusted site config supplies Cell Ranger |
--email |
string |
— |
Email address for pipeline completion notification |
--email-on-fail |
string |
— |
Email address for pipeline failure notification |
--multiqc-title |
string |
— |
Custom title for the MultiQC report |
--multiqc-config |
path |
— |
Custom MultiQC config YAML |
--multiqc-logo |
path |
— |
Custom MultiQC logo image |
--multiqc-methods-description |
path |
— |
Custom MultiQC methods-description YAML |
--publish-dir-mode |
enum |
— |
Forwarded nf-core publish mode: symlink, rellink, link, copy, copyNoFollow, or move |
--trace-report-suffix |
string |
— |
Suffix for Nextflow trace/report/timeline filenames |
--monochrome-logs |
flag |
— |
Disable ANSI colors in nf-core logs |
--resume |
flag |
— |
Nextflow resume (checksum-verified against prior manifest; preset/profile/source/work-dir must match) |
--run-downstream |
flag |
— |
Opt in to scrna_orchestrator handoff after pipeline completion |
--skip-downstream |
flag |
— |
Force-skip the downstream handoff even if --run-downstream is given (handoff is off by default) |
--cellrangerarc-config |
path |
— |
Config JSON for CellRanger ARC index construction |
--cellrangerarc-reference |
string |
— |
Reference genome name used inside the CellRanger ARC config |
--motifs |
path |
— |
Motif file (e.g. JASPAR) for CellRanger ARC |
--cellranger-vdj-index |
path |
— |
Prebuilt CellRanger VDJ reference |
--gex-frna-probe-set |
path |
— |
Probe set CSV for FFPE fixed RNA profiling (cellrangermulti) |
--gex-target-panel |
path |
— |
Target panel CSV for targeted GEX (cellrangermulti) |
--gex-cmo-set |
path |
— |
CMO reference CSV for multiplexed samples (cellrangermulti) |
--gex-barcode-sample-assignment |
path |
— |
Barcode-to-sample assignment override CSV (cellrangermulti). Not an OCM selector — OCM mode is encoded via the ocm_ids column of --cellranger-multi-barcodes |
--fb-reference |
path |
— |
Feature-barcode reference CSV for antibody capture (cellrangermulti) |
--vdj-inner-enrichment-primers |
path |
— |
V(D)J cDNA enrichment primer sequences (cellrangermulti) |
--cellranger-multi-barcodes |
path |
— |
Multiplexed sample samplesheet for CMO/FFPE demultiplexing (cellrangermulti) |
Output Structure
output_directory/
├── report.md # Wrapper run summary
├── result.json # Structured result payload
├── check_result.json # Written only with --check (preflight-only mode); no upstream/ is produced
├── logs/
│ ├── stdout.txt # Nextflow stdout
│ └── stderr.txt # Nextflow stderr
├── upstream/
│ └── results/ # nf-core/scrnaseq output tree
│ ├── fastqc/ # Per-read FastQC reports
│ ├── multiqc/ # MultiQC HTML and data
│ │ └── multiqc_report.html
│ ├── pipeline_info/ # Execution report, timeline, trace, DAG
│ └── <aligner>/ # Aligner-specific outputs
│ └── mtx_conversions/ # AnnData (.h5ad), SCE (.rds), Seurat (.rds)
│ │ # Per nf-core/scrnaseq 4.1.0 conf/modules.config, the concatenated
│ │ # matrices sit at the TOP of mtx_conversions/ while each per-sample
│ │ # matrix is nested one level deeper under <sample>/ (MTX_TO_H5AD/
│ │ # CONCAT_H5AD/ANNDATA_BARCODES rewrite non-combined files to
│ │ # `${meta.id}/${filename}`). The wrapper scans BOTH depths and does
│ │ # not hard-code filenames: it ranks whatever .h5ad it finds to pick
│ │ # one preferred_h5ad (combined > per-sample; within a group
│ │ # cellbender_filter > filtered > plain > raw, matched on the filename
│ │ # suffix). combined_* filter-suffixed variants are version-dependent.
│ ├── combined_matrix.h5ad # documented concatenated matrix (top level)
│ ├── combined_filtered_matrix.h5ad # version-dependent: filtering ran
│ ├── combined_cellbender_filter_matrix.h5ad # version-dependent: CellBender ran → top preference
│ └── <sample>/ # per-sample matrices nested one level deeper
│ ├── <sample>_raw_matrix.h5ad
│ └── <sample>_filtered_matrix.h5ad # conditional: filtering ran
├── reproducibility/ # Reproducibility + provenance bundle (single directory)
│ ├── samplesheet.valid.csv # Normalized samplesheet (absolute POSIX paths); named samplesheet.demo.csv with --demo
│ ├── params.yaml # Effective Nextflow parameters
│ ├── nextflow_configs/ # Written only when -c/--config is used: copies of the supplied config files, replayed by commands.sh
│ ├── commands.sh # Portable replay script
│ ├── environment.yml # Conda environment spec (for reference)
│ ├── checksums.sha256 # SHA-256 for in-bundle artifacts only; `sha256sum -c` passes from output dir
│ ├── manifest.json # Run metadata: preset, profile, versions, checksums
│ ├── macos_docker.config # macOS+Docker workarounds (VirtioFS, ARM64, STAR FIFOs)
│ ├── remap_paths.py # Helper for replaying on a different machine
│ ├── compatibility_policy.json # Copied policy snapshot (resume/update rules)
│ ├── pinned_versions.json # Copied pinned-versions snapshot
│ ├── inputs.json # Samplesheet + fastq/reference paths and digests (reference_checksums)
│ ├── invocation.json # Timestamp, preset, profile, pipeline version
│ ├── preflight.json # Java/Nextflow/backend info
│ ├── upstream.json # Pipeline source resolution details
│ ├── outputs.json # Detected artifacts
│ ├── runtime.json # Execution timing
│ └── skill.json # Skill name and version
├── provenance/ # Written only with --run-downstream
│ └── handoff.json # Downstream orchestrator path + checksum + outcome
└── scrna_analysis/ # Written only with --run-downstream: scrna_orchestrator output
Example Output
result.json (abbreviated):
{
"skill": "scrnaseq-pipeline",
"version": "0.1.0",
"summary": {
"preset": "star",
"aligner_effective": "star",
"pipeline_source_kind": "remote_repo",
"pipeline_version_or_commit": "4.1.0",
"profile": "docker",
"preferred_h5ad": "<output>/upstream/results/star/mtx_conversions/combined_filtered_matrix.h5ad",
"handoff_available": true,
"samples_detected": 2,
"cellbender_used": false
}
}
report.md closes with:
## Next Steps
- python clawbio.py run scrna --input <preferred_h5ad> --output <dir>
- python clawbio.py run scrna-embedding --input <preferred_h5ad> --output <dir>
Gotchas
- Preflight runs before any Nextflow call. If Java, Nextflow, or the backend are missing or too old, the pipeline never starts and you get a structured JSON error with
error_code and a fix hint. Nextflow ≥25.04.0 is required.
- Conda/Mamba profiles need network access at runtime. Preflight only verifies the
conda/mamba binary exists — it deliberately does not probe network connectivity (a flaky check that would also reject valid offline caches). With -profile conda, Nextflow resolves environments from bioconda/conda-forge at runtime, so an offline or proxied host can make a task fail mid-run with a confusing resolver error. Cell Ranger presets are rejected with conda/mamba by default because Cell Ranger is not distributed via bioconda; use --allow-conda-cellranger only when a trusted site config provides Cell Ranger. For fully offline/reproducible execution prefer docker/singularity (pinned containers), or pre-warm the conda package cache before running.
--genome conflicts with any explicit genome-reference flag. Providing --genome alongside --fasta, --gtf, --transcript-fasta, --txp2gene, or any prebuilt index raises CONFLICTING_REFERENCES in preflight. Use either --genome <shortcut> or explicit genome flags — never both. Auxiliary files (barcode whitelist, CMO/probe/feature sets, primers, multi-barcode samplesheets) are not genome references and are compatible with --genome.
igenomes_ignore is set automatically. Whenever an explicit genome reference (fasta, gtf, transcript_fasta, txp2gene, or any prebuilt index) is provided, the wrapper writes igenomes_ignore: true to suppress nf-schema DNS validation of the default iGenomes S3 URL. Auxiliary files never trigger it. You do not need to set this manually. Use --igenomes-base only for local iGenomes mirrors.
- Protocol compatibility is enforced before Nextflow starts.
standard, star, and kallisto require an explicit --protocol, because nf-core/scrnaseq 4.1.0 documents auto as CellRanger-only. Explicit auto is rejected for those presets. smartseq denotes Smart-seq3 and is accepted for star and kallisto only; smartseq2 is rejected for every preset because nf-core/scrnaseq 4.1.0 does not support Smart-seq2. cellranger accepts only auto and 10XV1-10XV4; cellrangerarc accepts only auto; cellrangermulti is samplesheet-driven. Unknown custom protocol strings are passed through only for standard, star, and kallisto, where nf-core documents custom values.
save_align_intermeds defaults to ON in 4.1.0. Upstream nf-core/scrnaseq 4.1.0 sets save_align_intermeds: true by default, so aligner intermediate BAMs are published into the results tree unless you pass --no-save-align-intermeds. On real (non---demo) datasets these intermediates can be tens to hundreds of GB; disable them when you only need the count matrices.
- Deprecated upstream parameters:
skip_emptydrops is deprecated in nf-core/scrnaseq 4.1.0. The wrapper accepts --skip-emptydrops only as a compatibility alias and emits skip_cellbender: true.
--demo forces preset=star and skip_cellbender=true. The nf-core upstream test profile ships STAR-compatible data and explicitly disables CellBender (which does not work on small test datasets). If a different preset is requested with --demo, the wrapper warns and overrides it. --demo also requires network access: the test profile fetches its FASTQs and references from remote GitHub URLs (nf-core's design — no local test data is bundled), so on an offline/sandboxed host set NXF_OFFLINE and the wrapper fails fast at preflight with DEMO_REQUIRES_NETWORK instead of a cryptic Nextflow does not exist abort. This does not violate local-first (which governs your genetic data — never uploaded); --demo only downloads nf-core's public test data. For a fully offline run, use your own local --input and references.
--demo is fully hermetic — every pipeline flag is ignored. The test profile owns the entire pipeline configuration: input, references, protocol, and all QC/skip/tuning/save/reporting knobs. Because a -params-file value overrides profile config in Nextflow, the wrapper writes only the four forced essentials into params.yaml in demo mode — outdir, aligner (star), igenomes_ignore, and skip_cellbender — and nothing else. Any other flag you pass with --demo (e.g. --genome, --fasta, an index, --igenomes-base, --protocol, --star-feature, --skip-fastqc, --save-reference, --seq-center, --publish-dir-mode, …) is ignored and listed in a WARNING. Demo output validation likewise requires FastQC and MultiQC regardless of any --skip-* you pass, since those flags are not written. Drop --demo to run on your own inputs.
- The Nextflow run has a 12 h wall-clock cap by default. Large multi-sample STARsolo/CellRanger runs on full genomes can exceed this; raise it with
--timeout-hours <n> or pass --timeout-hours 0 to disable the cap entirely (recommended on HPC/cloud where the scheduler enforces walltime). When the run targets an object-store work directory (--work-dir s3://…/gs://…) or an institutional/site profile while the cap is still active, preflight prints a WARNING reminding you to pass --timeout-hours 0, since the scheduler — not the wrapper — should bound such runs. When neither the cap fires nor the job is killed, behaviour is unchanged.
- Required outputs are checked after Nextflow exits. The wrapper expects
pipeline_info/, the effective aligner directory, MultiQC unless --skip-multiqc, FastQC HTML/ZIP reports unless --skip-fastqc, and at least one .h5ad matrix. FastQC is a hard requirement for every aligner — including the Cell Ranger family (cellranger/cellrangerarc/cellrangermulti) — because nf-core/scrnaseq 4.1.0 runs FASTQC on the shared input-read channel (ch_fastq) before any aligner-specific branching and publishes fastqc/ for all of them (the output docs state "FastQC is applied to all aligners' input reads"). A missing fastqc/ tree on a non-skipped run is therefore a genuine failure, not a tolerated gap. All six presets run the pipeline's MTX_TO_H5AD conversion (CellRanger ARC/Multi reuse the CellRanger template), so a completed run with zero .h5ad is treated as a failure (EXPECTED_OUTPUTS_NOT_FOUND) rather than a silent success. A present-but-ambiguous selection (e.g. several per-sample matrices, no combined) does not fail the run; it is signalled by handoff_available = false, and --run-downstream prints a warning instead of silently returning.
preferred_h5ad may be absent. If no combined matrix is produced and there are multiple per-sample files, handoff_available is false. Always check result.json before chaining to scrna-orchestrator or scrna-embedding.
- No arbitrary Nextflow parameter passthrough. Pipeline parameters flow only through the preset system and
params.yaml; no custom --param flags can be injected. Validated -c/--config files are allowed for infrastructure/HPC configuration and are copied into the reproducibility bundle. Note this is a trust boundary, not a sandbox: a Nextflow config is executable Groovy (it can set process.beforeScript, process.shell, etc.), so a -c file is as trusted as code you run yourself. The wrapper validates that each config exists and lints it for params.* overrides (see the next gotcha), but otherwise does not sandbox its contents — only pass configs you authored or trust.
- The work directory defaults to
<output>/upstream/work. This preserves local resume and bundle portability for workstation/HPC runs. Managed cloud-batch executors that need an object-store work directory can pass --work-dir s3://... or --work-dir gs://...; the value is recorded in provenance and replayed by commands.sh. Local custom paths are resolved before execution and are less portable than the default.
- The published results directory (
outdir) is intentionally the local <output>/upstream/results. This is a wrapper policy, not an nf-core limitation: the wrapper parses the results tree to detect the preferred_h5ad, MultiQC, and pipeline_info/, and to hand off downstream, so results must land on the local filesystem. This is still compatible with cloud-batch executors — the work directory may be remote (--work-dir s3://...) while Nextflow copies the published results back to the local outdir. There is no --outdir override to an object store, because the wrapper could not then parse outputs or chain downstream; for a remote-published run, invoke the upstream pipeline directly. The --output directory must also be outside the ClawBio source tree — an output inside the repository is rejected at preflight with OUTPUT_DIR_INSIDE_REPO (parity with nfcore-rnaseq/nfcore-sarek) so multi-gigabyte pipeline artifacts never pollute the checkout.
--pipeline-version is pinned to the 4.1.0 contract. The wrapper's parameter set, protocol matrix and output validation are written for nf-core/scrnaseq 4.1.0, so a different --pipeline-version is rejected unless you pass --allow-pipeline-version-override (a warned, provenance-recorded opt-in; validations stay 4.1.0).
-c/--config files may not set params.*. nf-core advises against setting parameters via -c. The wrapper blocks any config that assigns parameters outside the audited params.yaml — dotted (params.aligner = …), bracket (params['aligner'] = …), whole-map (params = […]), or a params { … } block (including the { on the next line). Pass --trust-config-params to allow it (detected overrides are recorded in provenance). Note the config is still trusted Groovy and is not sandboxed; this lint only guarantees params.yaml stays the single parameter source.
--resume enforces strict compatibility. The wra
…(truncated)
1---2name: nfcore-scrnaseq-wrapper3description: Wrapper skill for running nf-core/scrnaseq 4.1.0 upstream single-cell RNA-seq preprocessing from FASTQ with strict preflight, reproducibility outputs, and downstream handoff to ClawBio scRNA4 skills.5license: MIT6metadata:7 source: https://skillmd.com/skills/clawbio/nfcore-scrnaseq-wrapper8 domain: transcriptomics9 tags:10 - scrna11 - single-cell12 - nextflow13 - nf-core14 - fastq15 - 10x16 - h5ad17 - preprocessing18 dependencies:19 python: '>=3.11'20 packages:21 - pyyaml22 endpoints:23 cli: python clawbio.py run scrnaseq-pipeline --input {samplesheet} --output {output_dir}24 openclaw:25 requires:26 bins:27 - python328 - nextflow29 - java30 always: false31 emoji: 🧫32 homepage: https://github.com/ClawBio/ClawBio33 os:34 - darwin35 - linux36 trigger_keywords:37 - scrnaseq38 - nf-core scrnaseq39 - run scrnaseq from fastq40 - preprocess 10x fastqs41 - generate h5ad from single-cell fastq42 - single-cell preprocessing43 - nextflow scrna pipeline44 - 10x chromium fastq pipeline45 - starsolo upstream processing46 - alevin-fry fastq to counts47 - run nextflow scrnaseq48 - upstream single-cell pipeline49 - fastq to h5ad single cell50 - 10x genomics fastq pipeline51 author: ClawBio52 demo_data:53 - path: demo/README.md54 description: Demo mode uses the upstream nf-core/scrnaseq -profile test dataset rather than bundled FASTQs55 inputs:56 - name: samplesheet57 type: file58 format:59 - csv60 description: 'nf-core/scrnaseq samplesheet CSV with required columns: sample, fastq_1, fastq_2'61 required: true62 outputs:63 - name: report64 type: file65 format:66 - md67 description: Wrapper run summary and downstream handoff recommendations68 - name: result69 type: file70 format:71 - json72 description: Structured result payload with detected outputs and provenance73 version: 0.1.074---7576# nfcore-scrnaseq-wrapper7778You are **nfcore-scrnaseq-wrapper**, a specialised ClawBio agent for upstream single-cell RNA-seq preprocessing from FASTQ using the `nf-core/scrnaseq` Nextflow pipeline.7980## Trigger8182**Fire when:**83- User wants to run `scrnaseq` from raw FASTQ files84- User asks to preprocess 10x Chromium single-cell data85- User wants to execute `nf-core/scrnaseq`86- User wants to generate `.h5ad` from raw single-cell FASTQs87- User asks for primary scRNA preprocessing (FASTQ → h5ad)88- User mentions `simpleaf`, `STARsolo`, `alevin-fry`, or `kb-python` for upstream processing8990**Do NOT fire when:**91- User already has an `.h5ad` and wants clustering, UMAP, or markers → route to `scrna-orchestrator`92- User asks for scVI, scANVI, batch correction, or dimensionality reduction → route to `scrna-embedding`93- User asks about bulk RNA-seq, differential expression, or pseudo-bulk analysis → route to `rnaseq-de`94- Input is an already-processed count matrix, not raw FASTQs9596## Scope9798One skill, one task: run upstream scRNA preprocessing from FASTQ using `nf-core/scrnaseq` and produce canonical outputs for downstream ClawBio skills.99100This skill does NOT perform clustering, normalization, marker detection, dimensionality reduction, or any analysis on the `.h5ad` it produces.101102## Why This Exists103104- **Without it**: Users hand-build samplesheets, guess reference combinations, miss backend issues, and struggle to locate the correct `.h5ad` for downstream analysis.105- **With it**: One validated command runs the pipeline, captures provenance, writes a reproducibility bundle, and points directly to the best downstream handoff artifact.106- **Why ClawBio**: The wrapper keeps execution local-first, validates before launching Nextflow, and makes the run chainable into `scrna` and `scrna-embedding`.107108## Core Capabilities1091101. **Strict Preflight**: Validate Java, Nextflow, backend, samplesheet, FASTQs, and references before execution.1112. **Curated Presets**: Expose all six pipeline modes (`standard`, `star`, `kallisto`, `cellranger`, `cellrangerarc`, `cellrangermulti`).1123. **Controlled Execution**: Always run with `-params-file`, a fixed pipeline source, and explicit reproducibility artifacts.1134. **Output Resolution**: Detect MultiQC, pipeline_info, `.h5ad`, `.rds`, and select a canonical `preferred_h5ad` when possible.1145. **Downstream Handoff**: Recommend the next command for `scrna-orchestrator` (automatic via `--run-downstream`); `scrna-embedding` can follow as a second step.115116## Input Formats117118| Format | Extension | Required columns (all presets) | Preset-conditional columns | Optional columns |119|--------|-----------|------------------|------------------|------------------|120| Samplesheet | `.csv` | `sample`, `fastq_1`, `fastq_2` | `sample_type` + `fastq_barcode` (required for `cellrangerarc`); `feature_type` (required for `cellrangermulti`) | `expected_cells`, `seq_center` |121| Demo mode | n/a | none — test profile provides its own data | — | — |122123The wrapper enforces the preset-conditional columns before execution (`samplesheet_builder.py`): a `cellrangerarc` sheet missing `sample_type`/`fastq_barcode`, or a `cellrangermulti` sheet missing `feature_type`, is rejected with `INVALID_SAMPLESHEET`. Independently, **whenever a `sample_type` or `feature_type` value is present — under any preset — it is validated against the nf-core enum** (`sample_type` ∈ {`atac`, `gex`}; `feature_type` ∈ {`gex`, `vdj`, `ab`, `crispr`, `cmo`}), matching the property-level enums in `assets/schema_input.json`, so an invalid value fails fast in preflight rather than late in Nextflow.124125## Workflow1261271. **Validate**: Check the selected preset, samplesheet structure, FASTQ accessibility, references, Java, Nextflow, and backend.1282. **Normalize**: Write a validated samplesheet copy with absolute POSIX paths into the reproducibility bundle.1293. **Configure**: Build one effective `params.yaml` and a fixed Nextflow command.1304. **Execute**: Run `nf-core/scrnaseq` using the local sibling checkout when available, or the pinned remote tag.1315. **Parse**: Detect MultiQC, pipeline_info, `.h5ad`, `.rds`, and CellBender-derived outputs.1326. **Generate**: Write `report.md`, `result.json`, provenance JSON files, and reproducibility artifacts.1337. **Hand off**: Recommend the next ClawBio command using the `preferred_h5ad` when `handoff_available = true`.134135## Algorithm / Methodology136137The wrapper executes a strictly ordered 7-step pipeline. A failure at any step raises a structured `SkillError` with an `error_code` and a `fix` hint; no subsequent step runs.1381391. **Pipeline source resolution** (`pipeline_source.py`): Prefer a local sibling `scrnaseq/` checkout (pinned commit, audit-safe). Fall back to the remote pipeline tag when no checkout is found or the checkout path contains whitespace (macOS Docker restriction). A dirty local checkout is rejected by default; `--allow-dirty-pipeline` is an explicit development-only opt-in that is recorded in provenance. Use `--require-local-pipeline` when fallback to the remote pipeline would be unacceptable.1401412. **Samplesheet validation** (`samplesheet_builder.py`): Parse the CSV, resolve FASTQ paths relative to the CSV parent directory, normalize sample-name whitespace to underscores, verify readability and FASTQ extensions, reject FASTQ basenames with whitespace, enforce consistent `expected_cells` (≥1) and `seq_center` for repeated sample rows, reject exact duplicate FASTQ rows, and write a normalized copy to `reproducibility/samplesheet.valid.csv` with local FASTQ paths resolved to absolute POSIX (remote URIs, accepted only with `--allow-remote-inputs`, are passed through unchanged). The normalized replay sheet contains only headers accepted by the pinned 4.1.0 `assets/schema_input.json`; unsupported metadata columns are reported and omitted. In particular, `protocol` is supplied through the global `--protocol` parameter and is never forwarded as a samplesheet column.1421433. **Preflight** (`preflight.py`): Verify Java (≥17) and Nextflow (≥25.04.0). Compare version tuples after zero-padding to 3 elements (avoids false negatives such as `(24, 4) < (24, 4, 0)`). For `docker`, run `docker info` and gate on exit code. For `conda`/`mamba`, locate the binary. Cell Ranger presets are rejected with conda/mamba unless `--allow-conda-cellranger` is supplied with a trusted site config. For `singularity`/`apptainer`, accept either binary interchangeably. For `wave` and `gpu`, no binary check is needed (Nextflow-native features). Safe institutional profile components are accepted for HPC/site profiles, every `-c/--config` file must exist before execution, and configs are treated as trusted Groovy code. All preflight subprocess calls have a 60-second timeout (`_SUBPROCESS_TIMEOUT` in `preflight.py`); the git probes in `pipeline_source.py` use a 10-second timeout.1441454. **Params construction** (`params_builder.py`): Translate the preset + CLI flags into a `params.yaml` consumed by Nextflow via `-params-file`. All file paths use `.as_posix()` for forward-slash consistency across platforms. `igenomes_ignore` is automatically set to `true` whenever an explicit **genome** reference (`fasta`, `gtf`, `transcript_fasta`, `txp2gene`, or any prebuilt index) is provided — auxiliary files (barcode whitelist, CMO/probe/feature sets, primers, multi-barcode samplesheets) never trigger it, so they remain compatible with `--genome` (suppresses nf-schema DNS validation of the default iGenomes S3 URL). Skip flags are only written when `true`, keeping `params.yaml` minimal. In `--demo` mode no reference/protocol params are written at all (the test profile owns them).1461475. **Command build + execution** (`command_builder.py`, `executor.py`): Construct the `nextflow run` command with `-params-file`, validated `-c/--config` files, and a work directory that defaults to `<output>/upstream/work` but may be overridden by `--work-dir` (including object-store URIs for cloud executors), then launch via `subprocess.Popen` with stdout and stderr piped to log files on disk — never buffered in RAM. On `TimeoutExpired`, the process is killed and `EXECUTION_FAILED` is raised. On `KeyboardInterrupt`, the child process tree is terminated before the interrupt is re-raised.1481496. **Output parsing** (`outputs_parser.py`): Scan the upstream results tree for MultiQC HTML, `pipeline_info/`, aligner output directories, `.h5ad` (CellBender/filtered preferred over generic combined/raw), `.rds`, CellBender-derived files, and an `official_outputs` manifest for documented nf-core output families. Required outputs are validated before success artifacts are written; `handoff_available` is set to `true` only when a `preferred_h5ad` is confirmed on disk.1501517. **Provenance + reporting** (`provenance.py`, `reporting.py`): Write JSON provenance bundles, a SHA-256 checksum manifest (files only — never directories), `environment.yml`, a portable `commands.sh`, `report.md`, and `result.json`.152153## Presets154155| Preset | Aligner | Use case |156|--------|---------|---------|157| `standard` | simpleaf (alevin-fry) | Default for 10x GEX; fast, memory-efficient |158| `star` | STARsolo | Best FASTQ QC metrics; supports RNA velocity (`--star-feature "Gene Velocyto"`) |159| `kallisto` | kb-python / BUStools | Pseudo-alignment; fastest; lamanno/nac RNA velocity via `--kb-workflow` |160| `cellranger` | CellRanger | CellRanger v2/v3 compatibility; CellRanger is provided by the nf-core container under `docker`/`singularity` (no host binary needed). Not available under `-profile conda` (10x licensing keeps it off bioconda) |161| `cellrangerarc` | CellRanger ARC | Multiome (GEX + ATAC); accepts prebuilt `--cellranger-index` or reference-build inputs |162| `cellrangermulti` | CellRanger Multi | GEX + VDJ + feature barcoding; `--cellranger-multi-barcodes` required for CMO/FFPE multiplexing |163164Each preset requires at least one reference option: `--genome <iGenomes_shortcut>` OR a pre-built index (`--star-index`, `--simpleaf-index`, etc.) OR `--fasta` + `--gtf`. The `standard`/simpleaf preset additionally accepts a transcriptome pair `--transcript-fasta` + `--txp2gene` in place of a genome reference (per the nf-core/scrnaseq Simpleaf options).165166## nf-core/scrnaseq 4.1.0 Compatibility Policy167168This wrapper targets nf-core/scrnaseq `4.1.0`. It is not a free-form passthrough. Parameters are grouped as:169170- **Supported upstream parameters:** input/output, aligner/preset, reference/index, skip, CellRanger, CellRanger ARC, CellRanger Multi, selected MultiQC/reporting options.171- **Wrapper policy parameters:** `--preset`, `--check`, `--run-downstream`, `--skip-downstream`, `--expected-cells`, `--timeout-hours`, `--work-dir`, `--allow-remote-inputs`, `--allow-dirty-pipeline`, `--require-local-pipeline`, `--allow-pipeline-version-override`, `--trust-config-params`, `--allow-conda-cellranger`, and `-c`/`--config`/`--nextflow-config`; these are ClawBio conveniences and are not nf-core parameters.172- **Deprecated compatibility aliases:** `skip_emptydrops` is accepted only as `--skip-emptydrops` and translated to `skip_cellbender: true`; the deprecated upstream parameter is never written.173- **Intentionally unsupported upstream parameters:** `custom_config_version`, `custom_config_base`, `config_profile_name`, `config_profile_description`, `config_profile_contact`, `config_profile_url`, `version`, `plaintext_email`, `max_multiqc_email_size`, `hook_url`, `validate_params`, `pipelines_testdata_base_path`, `help`, `help_full`, `show_hidden`.174175Unsupported parameters are either hidden/institutional metadata, interactive help/version flags, or options that would weaken the wrapper's fixed validation/reproducibility policy.176177## Input & Reference Path Policy178179**Local-first by default.** Samplesheet FASTQs and reference/index inputs must be local paths unless you explicitly opt in. Remote URIs (`s3://`, `gs://`, `https://`, `ftp://`, …) are **rejected** at preflight with `REMOTE_INPUT_NOT_ALLOWED`, so genetic data and references stay on the local machine and no accidental cloud fetch happens. This guarantee is enforced by the code, not just advertised (`preflight._check_remote_inputs`).180181**Opt-in for remote inputs.** Pass `--allow-remote-inputs` to permit remote samplesheet inputs and reference paths (parity with `nfcore-sarek-wrapper` / `nfcore-rnaseq-wrapper`, which share the same flag). When enabled, remote URIs are passed through **verbatim** (Nextflow resolves and stages them; only the FASTQ/FASTA basename is validated) and preflight emits a **runtime WARNING** listing every path that will be fetched over the network, so cloud access is always visible. The object-store `--work-dir` is a separate setting and is not gated.182183**Local** paths are still validated eagerly at preflight so they fail fast with a clear error instead of a late Nextflow error:184- A supplied local reference/index path (`--fasta`, `--gtf`, `--star-index`, …) that does not exist raises `MISSING_REFERENCE` (`preflight.py`).185- A local FASTQ that does not exist (or is not a regular file) raises `MISSING_FASTQ` (`samplesheet_builder.py`).186187Readability is never pre-checked: Nextflow reads inputs in the true execution context (often a root container under the default Docker profile), so a launcher-side `os.access(R_OK)` probe would false-block valid runs (`errors.py`).188189## CLI Reference190191```bash192# Standard real-data usage (explicit protocol and reference are required)193python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \194 --input samplesheet.csv --output ./scrnaseq_run \195 --preset star --protocol 10XV3 --genome GRCh38196197# Preflight check only (no Nextflow execution)198python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \199 --input samplesheet.csv --output ./scrnaseq_run --check \200 --preset star --protocol 10XV3 --genome GRCh38201202# Demo mode (runs the upstream nf-core test profile; forces star preset; uses the203# selected backend — default --profile docker, which must be running)204python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \205 --demo --output ./scrnaseq_demo206207# Via ClawBio runner208python clawbio.py run scrnaseq-pipeline --input samplesheet.csv --output ./scrnaseq_run \209 --preset star --protocol 10XV3 --genome GRCh38210python clawbio.py run scrnaseq-pipeline --demo --output ./scrnaseq_demo211212# STARsolo with local FASTA+GTF (STAR index built by the pipeline)213python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \214 --input samplesheet.csv --output ./run --preset star --protocol 10XV3 \215 --fasta /refs/hg38.fa --gtf /refs/hg38.gtf216217# STARsolo with prebuilt STAR index218python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \219 --input samplesheet.csv --output ./run --preset star --protocol 10XV3 \220 --star-index /refs/star_index221222# STARsolo RNA velocity (star requires an explicit --protocol like every star/standard/kallisto run)223python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \224 --input samplesheet.csv --output ./run --preset star --protocol 10XV3 \225 --star-feature "Gene Velocyto" --star-ignore-sjdbgtf \226 --fasta /refs/hg38.fa --gtf /refs/hg38.gtf227228# Simpleaf (standard) with UMI resolution override229python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \230 --input samplesheet.csv --output ./run --preset standard --protocol 10XV3 \231 --simpleaf-umi-resolution cr-like-em --genome GRCh38232233# Kallisto RNA velocity (NAC workflow)234python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \235 --input samplesheet.csv --output ./run --preset kallisto --protocol 10XV3 \236 --kb-workflow nac --fasta /refs/hg38.fa --gtf /refs/hg38.gtf237238# Air-gapped cluster: local iGenomes mirror239python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \240 --input samplesheet.csv --output ./run --preset star --protocol 10XV3 \241 --genome GRCh38 --igenomes-base /mnt/local_igenomes242243# CellRanger Multi (CMO multiplexing)244python skills/nfcore-scrnaseq-wrapper/nfcore_scrnaseq_wrapper.py \245 --input samplesheet.csv --output ./run --preset cellrangermulti \246 --cellranger-index /refs/refdata-gex-GRCh38 \247 --gex-cmo-set /refs/cmo_set.csv \248 --cellranger-multi-barcodes /refs/multi_barcodes.csv249```250251### Key flags252253| Flag | Type | Default | Description |254|------|------|---------|-------------|255| `--input` | path | — | Samplesheet CSV (`sample,fastq_1,fastq_2`). Required unless `--demo` |256| `--output` | path | — | Output directory for results and the reproducibility bundle (required) |257| `--demo` | flag | — | Run the upstream nf-core `test` profile; forces `--preset star` and `skip_cellbender` |258| `--check` | flag | — | Run preflight only and exit (no Nextflow execution); `check_result.json` lists the nf-core parameter surface under `parameter_support` (supported upstream, wrapper policy, and intentionally unsupported parameters) |259| `--preset` | string | `standard` | Aligner preset |260| `--aligner` | string | — | nf-core/scrnaseq aligner alias for `--preset`: `simpleaf` maps to `standard`; the other values map to same-named presets |261| `--profile` | string | `docker` | Execution backend or comma-separated nf-core profile list: `docker`, `conda`, `mamba`, `singularity`, `apptainer`, `podman`, `shifter`, `charliecloud`, `wave`, `gpu`, `debug`, `arm64`, `emulate_amd64`, `test`, `test_full`, `test_cellrangermulti`, `test_multiome` |262| `--pipeline-version` | string | `4.1.0` | Remote `nf-core/scrnaseq` tag or commit (used when no local sibling checkout is found) |263| `--allow-dirty-pipeline` | flag | — | Development-only opt-in to run a modified local sibling `scrnaseq/` checkout; rejected by default for production reproducibility |264| `--require-local-pipeline` | flag | — | Require a verifiable local sibling `scrnaseq/` checkout; fail instead of falling back to the remote pipeline |265| `--allow-pipeline-version-override` | flag | — | Allow a `--pipeline-version` other than the pinned `4.1.0` contract (warned, recorded in provenance; validations stay 4.1.0) |266| `--trust-config-params` | flag | — | Allow `-c/--config` files that set `params.*` (otherwise blocked); detected overrides are recorded in provenance |267| `-c` / `--config` | path | — | Additional Nextflow config file. May be repeated; files are validated, applied to the live run, copied into the reproducibility bundle, and replayed by `commands.sh` |268| `--protocol` | string | `None` | Chemistry/protocol forwarded to the aligner. Required for `standard`, `star`, and `kallisto`; omitted only preserves CellRanger auto-detection for `cellranger`, `cellrangerarc`, and `cellrangermulti`. Explicit `auto` is invalid for `standard`, `star`, and `kallisto`. `smartseq` is valid for `star` and `kallisto` only. Other protocol strings are mapped when known or passed through by nf-core |269| `--genome` | string | — | iGenomes shortcut (`GRCh38`, `mm10`, etc.) — mutually exclusive with `--fasta`/`--gtf` and all index flags |270| `--igenomes-base` | string | — | Base URL or local path for iGenomes (default `s3://ngi-igenomes/igenomes/`). Use for local mirrors or air-gapped clusters. A **local** base path is existence-checked in preflight when `--genome` is set (remote `s3://`/`https://` bases are deferred to Nextflow) |271| `--igenomes-ignore` | flag | — | Do not load the iGenomes reference config. Set automatically whenever an explicit genome reference is supplied; only needed manually in unusual setups |272| `--fasta` | path | — | Genome FASTA (`.fa`, `.fna`, `.fasta`, `.gz` variants; no whitespace in path) |273| `--gtf` | path | — | Gene annotation GTF |274| `--star-index` | path | — | Prebuilt STAR genome index directory |275| `--simpleaf-index` | path | — | Prebuilt simpleaf/alevin-fry index |276| `--kallisto-index` | path | — | Prebuilt kallisto index |277| `--cellranger-index` | path | — | Prebuilt CellRanger or CellRanger ARC reference |278| `--transcript-fasta` | path | — | Transcriptome FASTA for simpleaf |279| `--txp2gene` | path | — | Transcript-to-gene mapping for simpleaf |280| `--barcode-whitelist` | path | — | Custom barcode whitelist (per-aligner format) |281| `--star-feature` | enum | — | STARsolo feature type: `Gene`, `GeneFull`, `Gene Velocyto` |282| `--star-ignore-sjdbgtf` | flag | — | Do not use GTF for SJDB construction (required for `Gene Velocyto`) |283| `--seq-center` | string | — | Sequencing center name for BAM read group tag |284| `--simpleaf-umi-resolution` | enum | — | UMI resolution strategy for alevin-fry: `cr-like`, `cr-like-em`, `parsimony`, `parsimony-em`, `parsimony-gene`, `parsimony-gene-em` |285| `--kb-workflow` | enum | — | Kallisto workflow: `standard`, `lamanno`, `nac` |286| `--kb-t1c` | path | — | cDNA transcripts-to-capture file for RNA velocity (lamanno/nac). Required only with a prebuilt `--kallisto-index`; auto-generated from `--fasta`/`--gtf` |287| `--kb-t2c` | path | — | Intron transcripts-to-capture file for RNA velocity (lamanno/nac). Required only with a prebuilt `--kallisto-index`; auto-generated from `--fasta`/`--gtf` |288| `--skip-cellbender` | flag | — | Disable the CellBender ambient RNA removal subworkflow |289| `--skip-emptydrops` | flag | — | Deprecated compatibility alias for `--skip-cellbender`; the wrapper writes `skip_cellbender: true` and never writes deprecated upstream `skip_emptydrops` |290| `--skip-fastqc` | flag | — | Skip FastQC quality control |291| `--skip-multiqc` | flag | — | Skip MultiQC report generation |292| `--skip-cellranger-renaming` | flag | — | Skip automatic sample renaming in CellRanger modules |293| `--skip-cellrangermulti-vdjref` | flag | — | Skip mkvdjref in cellrangermulti (when VDJ data is absent or a prebuilt `--cellranger-vdj-index` is supplied) |294| `--save-reference` | flag | — | Save the built reference index for future reuse |295| `--save-align-intermeds` / `--no-save-align-intermeds` | flag | — | Forward `save_align_intermeds: true`/`false`; when neither is given the upstream nf-core/scrnaseq 4.1.0 default (`true`) is preserved, so intermediate BAMs are published by default — pass `--no-save-align-intermeds` on large runs to save disk |296| `--expected-cells` | int | — | Override expected cell count for a single-sample samplesheet; multi-sample runs must set `expected_cells` per row. The wrapper enforces `≥1` (stricter than the upstream `integer` schema, which has no minimum) since a non-positive count is meaningless |297| `--timeout-hours` | float | `12` | Wall-clock cap for the Nextflow run, in hours. Use `0` to disable the cap for long HPC/cloud runs whose walltime is enforced by the scheduler. Via the ClawBio runner the runner's own timeout also applies |298| `--work-dir` | string | `<output>/upstream/work` | Nextflow work directory. Local paths are resolved before execution; object-store URIs such as `s3://...` or `gs://...` are passed through for cloud executors |299| `--allow-conda-cellranger` | flag | — | Allow Cell Ranger presets with conda/mamba only when a trusted site config supplies Cell Ranger |300| `--email` | string | — | Email address for pipeline completion notification |301| `--email-on-fail` | string | — | Email address for pipeline failure notification |302| `--multiqc-title` | string | — | Custom title for the MultiQC report |303| `--multiqc-config` | path | — | Custom MultiQC config YAML |304| `--multiqc-logo` | path | — | Custom MultiQC logo image |305| `--multiqc-methods-description` | path | — | Custom MultiQC methods-description YAML |306| `--publish-dir-mode` | enum | — | Forwarded nf-core publish mode: `symlink`, `rellink`, `link`, `copy`, `copyNoFollow`, or `move` |307| `--trace-report-suffix` | string | — | Suffix for Nextflow trace/report/timeline filenames |308| `--monochrome-logs` | flag | — | Disable ANSI colors in nf-core logs |309| `--resume` | flag | — | Nextflow resume (checksum-verified against prior manifest; preset/profile/source/work-dir must match) |310| `--run-downstream` | flag | — | Opt in to `scrna_orchestrator` handoff after pipeline completion |311| `--skip-downstream` | flag | — | Force-skip the downstream handoff even if `--run-downstream` is given (handoff is off by default) |312| `--cellrangerarc-config` | path | — | Config JSON for CellRanger ARC index construction |313| `--cellrangerarc-reference` | string | — | Reference genome name used inside the CellRanger ARC config |314| `--motifs` | path | — | Motif file (e.g. JASPAR) for CellRanger ARC |315| `--cellranger-vdj-index` | path | — | Prebuilt CellRanger VDJ reference |316| `--gex-frna-probe-set` | path | — | Probe set CSV for FFPE fixed RNA profiling (`cellrangermulti`) |317| `--gex-target-panel` | path | — | Target panel CSV for targeted GEX (`cellrangermulti`) |318| `--gex-cmo-set` | path | — | CMO reference CSV for multiplexed samples (`cellrangermulti`) |319| `--gex-barcode-sample-assignment` | path | — | Barcode-to-sample assignment override CSV (`cellrangermulti`). **Not** an OCM selector — OCM mode is encoded via the `ocm_ids` column of `--cellranger-multi-barcodes` |320| `--fb-reference` | path | — | Feature-barcode reference CSV for antibody capture (`cellrangermulti`) |321| `--vdj-inner-enrichment-primers` | path | — | V(D)J cDNA enrichment primer sequences (`cellrangermulti`) |322| `--cellranger-multi-barcodes` | path | — | Multiplexed sample samplesheet for CMO/FFPE demultiplexing (`cellrangermulti`) |323324## Output Structure325326```text327output_directory/328├── report.md # Wrapper run summary329├── result.json # Structured result payload330├── check_result.json # Written only with --check (preflight-only mode); no upstream/ is produced331├── logs/332│ ├── stdout.txt # Nextflow stdout333│ └── stderr.txt # Nextflow stderr334├── upstream/335│ └── results/ # nf-core/scrnaseq output tree336│ ├── fastqc/ # Per-read FastQC reports337│ ├── multiqc/ # MultiQC HTML and data338│ │ └── multiqc_report.html339│ ├── pipeline_info/ # Execution report, timeline, trace, DAG340│ └── <aligner>/ # Aligner-specific outputs341│ └── mtx_conversions/ # AnnData (.h5ad), SCE (.rds), Seurat (.rds)342│ │ # Per nf-core/scrnaseq 4.1.0 conf/modules.config, the concatenated343│ │ # matrices sit at the TOP of mtx_conversions/ while each per-sample344│ │ # matrix is nested one level deeper under <sample>/ (MTX_TO_H5AD/345│ │ # CONCAT_H5AD/ANNDATA_BARCODES rewrite non-combined files to346│ │ # `${meta.id}/${filename}`). The wrapper scans BOTH depths and does347│ │ # not hard-code filenames: it ranks whatever .h5ad it finds to pick348│ │ # one preferred_h5ad (combined > per-sample; within a group349│ │ # cellbender_filter > filtered > plain > raw, matched on the filename350│ │ # suffix). combined_* filter-suffixed variants are version-dependent.351│ ├── combined_matrix.h5ad # documented concatenated matrix (top level)352│ ├── combined_filtered_matrix.h5ad # version-dependent: filtering ran353│ ├── combined_cellbender_filter_matrix.h5ad # version-dependent: CellBender ran → top preference354│ └── <sample>/ # per-sample matrices nested one level deeper355│ ├── <sample>_raw_matrix.h5ad356│ └── <sample>_filtered_matrix.h5ad # conditional: filtering ran357├── reproducibility/ # Reproducibility + provenance bundle (single directory)358│ ├── samplesheet.valid.csv # Normalized samplesheet (absolute POSIX paths); named samplesheet.demo.csv with --demo359│ ├── params.yaml # Effective Nextflow parameters360│ ├── nextflow_configs/ # Written only when -c/--config is used: copies of the supplied config files, replayed by commands.sh361│ ├── commands.sh # Portable replay script362│ ├── environment.yml # Conda environment spec (for reference)363│ ├── checksums.sha256 # SHA-256 for in-bundle artifacts only; `sha256sum -c` passes from output dir364│ ├── manifest.json # Run metadata: preset, profile, versions, checksums365│ ├── macos_docker.config # macOS+Docker workarounds (VirtioFS, ARM64, STAR FIFOs)366│ ├── remap_paths.py # Helper for replaying on a different machine367│ ├── compatibility_policy.json # Copied policy snapshot (resume/update rules)368│ ├── pinned_versions.json # Copied pinned-versions snapshot369│ ├── inputs.json # Samplesheet + fastq/reference paths and digests (reference_checksums)370│ ├── invocation.json # Timestamp, preset, profile, pipeline version371│ ├── preflight.json # Java/Nextflow/backend info372│ ├── upstream.json # Pipeline source resolution details373│ ├── outputs.json # Detected artifacts374│ ├── runtime.json # Execution timing375│ └── skill.json # Skill name and version376├── provenance/ # Written only with --run-downstream377│ └── handoff.json # Downstream orchestrator path + checksum + outcome378└── scrna_analysis/ # Written only with --run-downstream: scrna_orchestrator output379```380381## Example Output382383`result.json` (abbreviated):384```json385{386 "skill": "scrnaseq-pipeline",387 "version": "0.1.0",388 "summary": {389 "preset": "star",390 "aligner_effective": "star",391 "pipeline_source_kind": "remote_repo",392 "pipeline_version_or_commit": "4.1.0",393 "profile": "docker",394 "preferred_h5ad": "<output>/upstream/results/star/mtx_conversions/combined_filtered_matrix.h5ad",395 "handoff_available": true,396 "samples_detected": 2,397 "cellbender_used": false398 }399}400```401402`report.md` closes with:403```404## Next Steps405- python clawbio.py run scrna --input <preferred_h5ad> --output <dir>406- python clawbio.py run scrna-embedding --input <preferred_h5ad> --output <dir>407```408409## Gotchas410411- **Preflight runs before any Nextflow call.** If Java, Nextflow, or the backend are missing or too old, the pipeline never starts and you get a structured JSON error with `error_code` and a `fix` hint. Nextflow ≥25.04.0 is required.412- **Conda/Mamba profiles need network access at runtime.** Preflight only verifies the `conda`/`mamba` binary exists — it deliberately does not probe network connectivity (a flaky check that would also reject valid offline caches). With `-profile conda`, Nextflow resolves environments from bioconda/conda-forge at runtime, so an offline or proxied host can make a task fail mid-run with a confusing resolver error. Cell Ranger presets are rejected with conda/mamba by default because Cell Ranger is not distributed via bioconda; use `--allow-conda-cellranger` only when a trusted site config provides Cell Ranger. For fully offline/reproducible execution prefer `docker`/`singularity` (pinned containers), or pre-warm the conda package cache before running.413- **`--genome` conflicts with any explicit genome-reference flag.** Providing `--genome` alongside `--fasta`, `--gtf`, `--transcript-fasta`, `--txp2gene`, or any prebuilt index raises `CONFLICTING_REFERENCES` in preflight. Use either `--genome <shortcut>` or explicit genome flags — never both. Auxiliary files (barcode whitelist, CMO/probe/feature sets, primers, multi-barcode samplesheets) are **not** genome references and are compatible with `--genome`.414- **`igenomes_ignore` is set automatically.** Whenever an explicit **genome** reference (`fasta`, `gtf`, `transcript_fasta`, `txp2gene`, or any prebuilt index) is provided, the wrapper writes `igenomes_ignore: true` to suppress nf-schema DNS validation of the default iGenomes S3 URL. Auxiliary files never trigger it. You do not need to set this manually. Use `--igenomes-base` only for local iGenomes mirrors.415- **Protocol compatibility is enforced before Nextflow starts.** `standard`, `star`, and `kallisto` require an explicit `--protocol`, because nf-core/scrnaseq 4.1.0 documents `auto` as CellRanger-only. Explicit `auto` is rejected for those presets. `smartseq` denotes **Smart-seq3** and is accepted for `star` and `kallisto` only; **`smartseq2` is rejected for every preset** because nf-core/scrnaseq 4.1.0 does not support Smart-seq2. `cellranger` accepts only `auto` and `10XV1`-`10XV4`; `cellrangerarc` accepts only `auto`; `cellrangermulti` is samplesheet-driven. Unknown custom protocol strings are passed through only for `standard`, `star`, and `kallisto`, where nf-core documents custom values.416- **`save_align_intermeds` defaults to ON in 4.1.0.** Upstream nf-core/scrnaseq 4.1.0 sets `save_align_intermeds: true` by default, so aligner intermediate BAMs are published into the results tree unless you pass `--no-save-align-intermeds`. On real (non-`--demo`) datasets these intermediates can be tens to hundreds of GB; disable them when you only need the count matrices.417- **Deprecated upstream parameters:** `skip_emptydrops` is deprecated in nf-core/scrnaseq 4.1.0. The wrapper accepts `--skip-emptydrops` only as a compatibility alias and emits `skip_cellbender: true`.418- **`--demo` forces preset=star and skip_cellbender=true.** The nf-core upstream `test` profile ships STAR-compatible data and explicitly disables CellBender (which does not work on small test datasets). If a different preset is requested with `--demo`, the wrapper warns and overrides it. **`--demo` also requires network access**: the test profile fetches its FASTQs and references from remote GitHub URLs (nf-core's design — no local test data is bundled), so on an offline/sandboxed host set `NXF_OFFLINE` and the wrapper fails fast at preflight with `DEMO_REQUIRES_NETWORK` instead of a cryptic Nextflow `does not exist` abort. This does not violate local-first (which governs your *genetic data* — never uploaded); `--demo` only *downloads* nf-core's public test data. For a fully offline run, use your own local `--input` and references.419- **`--demo` is fully hermetic — every pipeline flag is ignored.** The `test` profile owns the entire pipeline configuration: input, references, protocol, and all QC/skip/tuning/save/reporting knobs. Because a `-params-file` value overrides profile config in Nextflow, the wrapper writes **only** the four forced essentials into `params.yaml` in demo mode — `outdir`, `aligner` (`star`), `igenomes_ignore`, and `skip_cellbender` — and nothing else. Any other flag you pass with `--demo` (e.g. `--genome`, `--fasta`, an index, `--igenomes-base`, `--protocol`, `--star-feature`, `--skip-fastqc`, `--save-reference`, `--seq-center`, `--publish-dir-mode`, …) is ignored and listed in a WARNING. Demo output validation likewise requires FastQC and MultiQC regardless of any `--skip-*` you pass, since those flags are not written. Drop `--demo` to run on your own inputs.420- **The Nextflow run has a 12 h wall-clock cap by default.** Large multi-sample STARsolo/CellRanger runs on full genomes can exceed this; raise it with `--timeout-hours <n>` or pass `--timeout-hours 0` to disable the cap entirely (recommended on HPC/cloud where the scheduler enforces walltime). When the run targets an object-store work directory (`--work-dir s3://…`/`gs://…`) or an institutional/site profile while the cap is still active, preflight prints a WARNING reminding you to pass `--timeout-hours 0`, since the scheduler — not the wrapper — should bound such runs. When neither the cap fires nor the job is killed, behaviour is unchanged.421- **Required outputs are checked after Nextflow exits.** The wrapper expects `pipeline_info/`, the effective aligner directory, MultiQC unless `--skip-multiqc`, FastQC HTML/ZIP reports unless `--skip-fastqc`, and at least one `.h5ad` matrix. FastQC is a hard requirement for **every** aligner — including the Cell Ranger family (`cellranger`/`cellrangerarc`/`cellrangermulti`) — because nf-core/scrnaseq 4.1.0 runs FASTQC on the shared input-read channel (`ch_fastq`) *before* any aligner-specific branching and publishes `fastqc/` for all of them (the output docs state "FastQC is applied to all aligners' input reads"). A missing `fastqc/` tree on a non-skipped run is therefore a genuine failure, not a tolerated gap. All six presets run the pipeline's `MTX_TO_H5AD` conversion (CellRanger ARC/Multi reuse the CellRanger template), so a completed run with **zero `.h5ad` is treated as a failure** (`EXPECTED_OUTPUTS_NOT_FOUND`) rather than a silent success. A present-but-ambiguous selection (e.g. several per-sample matrices, no combined) does not fail the run; it is signalled by `handoff_available = false`, and `--run-downstream` prints a warning instead of silently returning.422- **`preferred_h5ad` may be absent.** If no combined matrix is produced and there are multiple per-sample files, `handoff_available` is `false`. Always check `result.json` before chaining to `scrna-orchestrator` or `scrna-embedding`.423- **No arbitrary Nextflow parameter passthrough.** Pipeline *parameters* flow only through the preset system and `params.yaml`; no custom `--param` flags can be injected. Validated `-c/--config` files are allowed for infrastructure/HPC configuration and are copied into the reproducibility bundle. Note this is a **trust boundary, not a sandbox**: a Nextflow config is executable Groovy (it can set `process.beforeScript`, `process.shell`, etc.), so a `-c` file is as trusted as code you run yourself. The wrapper validates that each config exists and lints it for `params.*` overrides (see the next gotcha), but otherwise does not sandbox its contents — only pass configs you authored or trust.424- **The work directory defaults to `<output>/upstream/work`.** This preserves local resume and bundle portability for workstation/HPC runs. Managed cloud-batch executors that need an object-store work directory can pass `--work-dir s3://...` or `--work-dir gs://...`; the value is recorded in provenance and replayed by `commands.sh`. Local custom paths are resolved before execution and are less portable than the default.425- **The published results directory (`outdir`) is intentionally the local `<output>/upstream/results`.** This is a wrapper policy, not an nf-core limitation: the wrapper parses the results tree to detect the `preferred_h5ad`, MultiQC, and `pipeline_info/`, and to hand off downstream, so results must land on the local filesystem. This is still compatible with cloud-batch executors — the work directory may be remote (`--work-dir s3://...`) while Nextflow copies the published results back to the local `outdir`. There is no `--outdir` override to an object store, because the wrapper could not then parse outputs or chain downstream; for a remote-published run, invoke the upstream pipeline directly. The `--output` directory must also be **outside** the ClawBio source tree — an output inside the repository is rejected at preflight with `OUTPUT_DIR_INSIDE_REPO` (parity with nfcore-rnaseq/nfcore-sarek) so multi-gigabyte pipeline artifacts never pollute the checkout.426- **`--pipeline-version` is pinned to the 4.1.0 contract.** The wrapper's parameter set, protocol matrix and output validation are written for nf-core/scrnaseq 4.1.0, so a different `--pipeline-version` is rejected unless you pass `--allow-pipeline-version-override` (a warned, provenance-recorded opt-in; validations stay 4.1.0).427- **`-c/--config` files may not set `params.*`.** nf-core advises against setting parameters via `-c`. The wrapper blocks any config that assigns parameters outside the audited `params.yaml` — dotted (`params.aligner = …`), bracket (`params['aligner'] = …`), whole-map (`params = […]`), or a `params { … }` block (including the `{` on the next line). Pass `--trust-config-params` to allow it (detected overrides are recorded in provenance). Note the config is still trusted Groovy and is not sandboxed; this lint only guarantees `params.yaml` stays the single parameter source.428- **`--resume` enforces strict compatibility.** The wra429430…(truncated)