rnaseq
nf-core/rnaseq
RNA sequencing analysis pipeline for gene/isoform quantification and extensive quality control.
Key tools
Run it
nfclaw run rnaseq --input samplesheet.csv --outdir results -profile dockernextflow run pipelines/rnaseq/upstream -profile docker --input samplesheet.csv --outdir resultsnfclaw run rnaseq --demo --outdir results # adds the upstream test profile (-profile test,docker)Inputs
| column | type | required | allowed values | constraints |
|---|---|---|---|---|
sample | string or integer | yes | matches ^\S+$ | |
fastq_1 | string (file path) | yes | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q(\.gz)?$ | |
fastq_2 | string (file path) | no | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q(\.gz)?$ | |
strandedness | string | yes | forward, reverse, unstranded, auto | |
seq_platform | string | no | matches ^\S+$ | |
seq_center | string | no | matches ^\S+$ | |
genome_bam | string (file path) | no | matches ^([\S\s]*\/)?[^\s\/]+\.(bam|BAM)$ | |
transcriptome_bam | string (file path) | no | matches ^([\S\s]*\/)?[^\s\/]+\.(bam|BAM)$ | |
percent_mapped | number | no | ≥ 0; ≤ 100 |
--input must match ^\S+\.csv$.
The samplesheet is a CSV with this header (the columns the schema requires); fill each value per the table above and reference.md (no example value is invented here):
sample,fastq_1,strandednessAny of the optional columns above may be appended to the header when your data needs them: fastq_2, seq_platform, seq_center, genome_bam, transcriptome_bam, percent_mapped.
From data files. --input may also be the data files — a directory (searched recursively), a quoted glob, or files (--input once per file) — from which nfclaw writes this samplesheet: sample from file names; fastq_1/fastq_2 from FastQ files (mates paired by _R1/_R2, or by _1/_2 when their read names show they are mates). Set the required columns no file determines with --sheet-set COLUMN=VALUE (a constant or a {sample}/{lane} template): strandedness (one of forward, reverse, unstranded, auto). Preview it with --check; a run records it in <outdir>/provenance/ for replay.
Reference genome
No reference genome is set by default: supply your own reference. The schema declares AWS iGenomes at s3://ngi-igenomes/igenomes/; selecting --genome <id> uses the paths in the pipeline's reference configuration. Access to that remote source is required. To supply your own reference, use e.g. --fasta; the reference_genome_options group in reference.md lists every reference option. Set --igenomes-ignore true to disable the lookup entirely. Confirm the selected reference's paths and source in the pinned upstream/nextflow.config and upstream/conf/ before running.
Secrets
This release reads Nextflow secrets: SENTIEON_LICENSE_BASE64 (in modules/nf-core/sentieon/rsemcalculateexpression/main.nf, modules/nf-core/sentieon/staralign/main.nf). Set each one a run needs with nextflow secrets set NAME VALUE before launching; a secret that is not set reaches its tasks as an empty value (Nextflow warns that the variable evaluates to an empty value), and a task that needs it then fails. Secrets are not written to nfclaw's provenance.
Resources
Resource requests follow the pipeline's configs and selected profiles. nf-core's resource labels often assume a server — a single step can request far more memory than a workstation has, and retry rules can increase requests. If a run fails with Process requirement exceeds available memory (or CPUs), cap every request, and every retry, at what this machine actually has:
nfclaw run rnaseq --input samplesheet.csv --outdir results -profile docker \ --limit-cpus 4 --limit-memory 15.GBnfclaw turns those into Nextflow's process.resourceLimits and passes them as a -c config — the mechanism nf-core prescribes for exactly this (docs). Set them to the machine's real capacity. --limit-time DURATION also caps how long any one task may run: a task that needs longer is stopped, and so is every retry, so set it only as a deliberate ceiling, never as a guess at how long the analysis takes. The generated config is kept in <outdir>/provenance/, so commands.sh replays the run under the same ceiling.
Nextflow engine
This release declares nextflowVersion = '!>=25.10.4'.
To pin this release's declared minimum engine — useful when a newer Nextflow has incompatible config parsing:
nfclaw run rnaseq ... --nxf-ver 25.10.4--nxf-ver is recorded in <outdir>/provenance/, so the replay uses the same engine. See known-issues.
Demo
nfclaw run rnaseq --demo --outdir results # adds the upstream test profile (-profile test,docker)Samplesheet
A CSV with this header (the columns the schema requires). Fill each value per the constraints below; optional columns from the table may be appended.
sample,fastq_1,strandedness| Column | Type | Required | Allowed / constraints |
|---|---|---|---|
sample | string or integer | required | matches ^\S+$ |
fastq_1 | string (file path) | required | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q(\.gz)?$ |
fastq_2 | string (file path) | optional | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q(\.gz)?$ |
strandedness | string | required | forwardreverseunstrandedauto |
seq_platform | string | optional | matches ^\S+$ |
seq_center | string | optional | matches ^\S+$ |
genome_bam | string (file path) | optional | matches ^([\S\s]*\/)?[^\s\/]+\.(bam|BAM)$ |
transcriptome_bam | string (file path) | optional | matches ^([\S\s]*\/)?[^\s\/]+\.(bam|BAM)$ |
percent_mapped | number | optional | ≥ 0; ≤ 100 |
Required parameters
--inputstring (file path)Path to the sample sheet (CSV) containing metadata about the experimental samples.
Constraint · matches ^\S+\.csv$
--outdirstring (directory path)The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Constraint · length ≥ 1
Parameter explorer
136 parameters · 11 groupsEvery parameter from the pinned nextflow_schema.json. nfclaw checks explicit values before launch; complex rules use the pinned pipeline's runtime validation. Search, filter by group, and expand any parameter for its default, allowed values and constraints.
114 parameters · 22 hidden
Alignment options22
Specifies the alignment algorithm to use - available options are 'star_salmon', 'star_rsem', 'hisat2', and 'bowtie2_salmon'.
Create a CSI index for BAM files instead of the traditional BAI index. This will be required for genomes with larger chromosome sizes.
Extra arguments to pass to Bowtie2 alignment command in addition to defaults defined by the pipeline. Only available when using --aligner bowtie2_salmon.
Extra arguments to pass to HISAT2 alignment command in addition to defaults defined by the pipeline. Only available when using --aligner hisat2.
Extra arguments to pass to Kallisto quant command in addition to defaults defined by the pipeline.
Extra arguments to pass to the Salmon index command in addition to defaults defined by the pipeline.
Extra arguments to pass to Salmon quant command in addition to defaults defined by the pipeline.
Extra arguments to pass to STAR alignment command in addition to defaults defined by the pipeline. Only available for the STAR-Salmon route.
In single-end mode Kallisto requires an estimated fragment length (in base pairs). Specify a default value for that here.
In single-end mode, Kallisto requires an estimated standard error for fragment length (in base pairs). Specify a default value for that here.
Minimum percentage of uniquely mapped reads below which samples are removed from further processing.
Specifies the pseudo aligner to use - available options are 'salmon'. Runs in addition to '--aligner'.
Kmer length passed to indexing step of pseudoaligners
Override Salmon library type inferred based on strandedness defined in meta object.
Sequencing center information to be added to read group of BAM files.
Sequencing platform information to be added to read group of BAM files.
When using pre-built STAR indices do not re-extract and use splice junctions from the GTF file.
The fraction of stranded reads that must be assigned to a strandedness for confident assignment. Must be at least 0.5.
Perform reference-guided de novo assembly of transcripts using StringTie i.e. dont restrict to those in GTF file.
The difference in fraction of stranded reads assigned to 'forward' and 'reverse' below which a sample is classified as 'unstranded'. By default the forward and reverse fractions must differ by less than 0.1 for the sample to be called as unstranded.
Optionally accelerate STAR and MarkDuplicates with Parabricks
Optionally accelerate STAR with Sentieon
Generic options4
Display the help message.
Display the full detailed help message.
Custom MultiQC yaml file containing HTML including a methods description.
Display hidden parameters in the help message (only works when --help or --help_full are provided).
Input Output options4
Email address for completion summary.
Path to the sample sheet (CSV) containing metadata about the experimental samples.
MultiQC report title. Printed as page header, used for filename if not otherwise specified.
The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Optional Outputs10
Save the intermediate BAM files from the alignment step.
If this option is specified, FastQ files split by reference will be saved in the results directory.
Save read-by-read assignments from Kraken2.
Save reads that were not given assignment from Kraken2.
Save FastQ files after merging re-sequenced libraries in the results directory.
If this option is specified, intermediate FastQ files containing non-rRNA reads will be saved in the results directory.
If generated by the pipeline save the STAR index in the results directory.
Save the trimmed FastQ files in the results directory.
If this option is specified, intermediate FastQ and BAM files produced by UMI-tools are also saved in the results directory.
Where possible, save unaligned reads from either STAR, HISAT2 or Salmon to the results directory.
Process Skipping options22
Skip all of the alignment-based processes within the pipeline.
Skip BBSplit for removal of non-reference genome reads.
Skip bigWig file creation.
Skip additional featureCounts process for biotype QC. Has no effect under --use_rustqc (experimental).
Skip DESeq2 PCA and heatmap plotting.
Skip dupRadar. Has no effect under --use_rustqc (experimental).
Skip FastQC.
Skip filtering of GTF for valid scaffolds and/ or transcript IDs.
Skip the 'transcript_id' checking component of the GTF filtering script used in the pipeline. Ensure the GTF file is valid.
Skip linting checks during FASTQ preprocessing and filtering.
Skip picard MarkDuplicates step.
Skip MultiQC.
Skip Preseq.
Skip all of the pseudoalignment-based processes within the pipeline.
Skip all QC steps except for MultiQC.
Skip Qualimap. Has no effect under --use_rustqc (experimental).
Skip cross-sample count merging. Runs tximport per-sample instead of merged, producing individual gene/transcript-level TSVs per sample. Skips SummarizedExperiment and RSEM merge counts. Useful for very large cohorts.
Skip RSeQC. Has no effect under --use_rustqc (experimental).
Skip StringTie.
Skip the adapter trimming step.
Skip the UMI extraction from the read in case the UMIs have been moved to the headers in advance of the pipeline run.
Experimental. Use RustQC instead of dupRadar, featureCounts biotype QC, RSeQC, Preseq, Qualimap, and samtools stats/flagstat/idxstats. Recommend trialling on pilot data first.
Quality Control9
Taxonomic level for Bracken abundance estimations.
Tool to use for detecting contaminants in the selected screening reads - available options are 'sylph', 'kraken2', or 'kraken2_bracken'
Read set to screen for contaminants: aligner-unmapped reads (default), trimmed reads (post-BBSplit/rRNA), post-trim pre-BBSplit reads, or raw reads.
Use vst transformation instead of rlog with DESeq2.
Extra arguments to pass to the fq lint command.
Database when using Kraken2/Bracken for contaminant screening.
Comma-separated list of RSeQC modules to run.
Comma separated list of databases to profile against when using Sylph for contamination detection
Comma separated list of taxonomies when using Sylph for contamination detection
Read Filtering options8
Path to comma-separated file containing a list of reference genomes to filter reads against with BBSplit. You have to also explicitly set --skip_bbsplit false if you want to use BBSplit.
Path to directory or tar.gz archive for pre-built BBSplit index.
Path to directory or tar.gz archive for pre-built Bowtie2 index for rRNA removal.
Enable the removal of reads derived from ribosomal RNA.
Text file containing paths to fasta files (one per line) that will be used to create the database for SortMeRNA.
Tool to use for rRNA removal.
Path to directory or tar.gz archive for pre-built sortmerna index.
Enable GPU acceleration for ribodetector.
Read Trimming options4
Extra arguments to pass to fastp command in addition to defaults defined by the pipeline.
Extra arguments to pass to Trim Galore! command in addition to defaults defined by the pipeline.
Minimum number of trimmed reads below which samples are removed from further processing. Some downstream steps in the pipeline will fail if this threshold is too low.
Specifies the trimming tool to use - available options are 'trimgalore' and 'fastp'.
Reference Genome options21
FASTA file to concatenate to genome FASTA file e.g. containing spike-in sequences.
Path to directory or tar.gz archive for pre-built Bowtie2 index.
Path to FASTA genome file.
By default, the pipeline assigns reads based on the 'exon' attribute within the GTF file.
The attribute type used to group feature types in the GTF file when generating the biotype plot with featureCounts.
Specify if your GTF annotation is in GENCODE format.
Path to BED file containing gene intervals. This will be created from the GTF file if not specified.
Name of a params.genomes catalogue entry (iGenomes or a user-defined catalogue).
Path to GFF3 annotation file.
Use gffread to generate transcript FASTA instead of RSEM.
Path to GTF annotation file.
By default, the pipeline uses the gene_name field to obtain additional gene identifiers from the input GTF file when running Salmon.
Define the attribute type used to group features in the GTF file when running Salmon.
Minimum memory required to use splice sites and exons in the HiSAT2 index build process.
Path to directory or tar.gz archive for pre-built HISAT2 index.
Path to directory or tar.gz archive for pre-built Kallisto index.
Path to directory or tar.gz archive for pre-built RSEM index.
Path to directory or tar.gz archive for pre-built Salmon index.
Splice sites file required for HISAT2.
Path to directory or tar.gz archive for pre-built STAR index.
Path to FASTA transcriptome file.
Umi options10
Specifies the tool to use for UMI deduplication - available options are 'umitools' and 'umicollapse'.
After UMI barcode extraction discard either R1 or R2 by setting this parameter to 1 or 2, respectively.
The UMI barcode pattern to use e.g. 'NNNNNN' indicates that the first 6 nucleotides of the read are from the UMI.
The UMI barcode pattern to use if the UMI is located in read 2.
Filter to primary alignments before UMI-tools dedup.
Generate output stats when running "umi_tools dedup".
UMI pattern to use. Can be either 'string' (default) or 'regex'.
Method to use to determine read groups by subsuming those with similar UMIs. All methods start by identifying the reads with the same mapping position, but treat similar yet nonidentical UMIs differently.
The character that separates the UMI in the read name. Most likely a colon if you skipped the extraction with UMI-tools and used other software.
Enable UMI-based read deduplication.
Outputs
Results land in --outdir; the files and directory layout depend on the selected workflow, parameters and publication settings. Run metadata is normally placed in <outdir>/pipeline_info/ (execution report, software versions), when those outputs are enabled. The pinned tree includes MultiQC support; a report is produced only when its workflow step runs. --skip-multiqc true disables that report. nfclaw run also writes <outdir>/provenance/ with the exact params file and the run log, <outdir>/provenance/logs/run.log — the whole launch, whose last line states the outcome (Nextflow's own log is <outdir>/.nextflow.log); unless --no-provenance it adds a run manifest (pinned version, commit and exact command), input/output SHA-256 checksums, and a replayable commands.sh.
The exact output files and directory layout for this release are documented upstream: github.com/nf-core/rnaseq/blob/3.27.0/docs/output.md
Check a run — in the foreground or the background — with nfclaw status <outdir>: success, still running, how it ended (with the error), or stopped without an outcome; exit 0 success, 3 running, 1 otherwise.
Chaining
Run rnaseq as one stage of a chain: nfclaw chain run starts each stage only after the one before it succeeded, and prepares its inputs from that stage's outputs. Every rule is checked against both pinned schemas.
Feeds into
- differentialabundance — rnaseq's merged gene counts and the gene lengths of the same quantification become differentialabundance's --matrix and --feature-length-matrix (DESeq2 models length bias with them; differentialabundance does not recommend raw counts without lengths) — from the alignment-based quantification when rnaseq ran one, otherwise its pseudo-aligner — with the GTF the rnaseq run used. An rnaseq release that published no lengths for that quantification (before 3.15.0; RSEM before 3.23.0) fails the handoff: hand over its length-scaled counts with an inline handoff instead. The experimental design (--input, sample names as in rnaseq) and --contrasts describe your study and go in the stage's own params.
Fed by
- bamtofastq — bamtofastq publishes converted paired-end reads as reads/<sample>_1.merged.fastq.gz and _2; one rnaseq row per sample, strandedness detected by rnaseq (auto). Single-end conversions are published as reads/<sample>_other.fq.gz: a run with any fails this handoff instead of leaving them out, and needs an inline handoff.
- demultiplex — demultiplex writes samplesheet/rnaseq_samplesheet.csv for its demultiplexed FastQ files (strandedness from its --strandedness, default auto).
- fetchngs — fetchngs downloads the FastQ files and, with --nf-core-pipeline rnaseq, writes samplesheet/samplesheet.csv for rnaseq (absolute FastQ paths; strandedness from --nf-core-rnaseq-strandedness, default auto). Runs whose ENA instrument_platform is not a short-read platform (the ones nf-core/mag accepts as short reads: ILLUMINA, BGISEQ, DNBSEQ, ELEMENT, ULTIMA, ION_TORRENT, LS454, …) are refused: rnaseq analyses short reads, and long-read, capillary or colour-space runs would be processed as if they were.
nfclaw chain edges rnaseq