RNAflow User Manual

This manual guides you through every step of an RNA-seq analysis — from installing the app to interpreting your final results. Each section explains what is happening, what good results look like, and how to fix common problems.

⬇️

Installation

macOS, Windows, Linux

🧬

Pipeline Steps

13-step guided workflow

📊

Understanding Results

FastQC, PCA, Volcano, GSEA

🔧

Troubleshooting

Common errors & fixes

Installation

Step 1 — Download RNAflow

Go to rnaflow.bioinfocodex.com and download the version for your operating system.

Platform	File to download	Notes
macOS Apple Silicon (M1/M2/M3)	`RNAflow-*-arm64.dmg`	Most Macs since 2020
macOS Intel	`RNAflow-*.dmg`	Macs before 2020
Windows 10/11	`RNAflow-Setup-*.exe`	Recommended installer
Linux (Ubuntu/Debian)	`rnaflow_*_amd64.deb`	Ubuntu 20.04+
Linux (universal)	`RNAflow-*.AppImage`	Any Linux distribution

Step 2 — Install on macOS

Open the downloaded .dmg file
Drag RNAflow.app into your Applications folder
Double-click RNAflow in Applications to launch it

⚠️

"RNAflow is damaged and can't be opened"

macOS blocks apps that are not notarized with Apple. This is a security warning, not a virus. To fix it, open Terminal (search "Terminal" in Spotlight) and run:

xattr -cr ~/Downloads/RNAflow*.dmg

Then open the DMG again and drag to Applications. Or after dragging:
xattr -cr /Applications/RNAflow.app

Alternatively, right-click the app → Open → click Open in the popup dialog.

Step 3 — Install Miniforge (Conda)

RNAflow uses Conda to install bioinformatics tools. Miniforge is the recommended Conda distribution — it is lighter and faster than Anaconda.

Go to github.com/conda-forge/miniforge/releases
Download the installer for your system
Run the installer and follow the prompts
Restart your Terminal after installation

Verify Conda is installed

conda --version
# Expected output: conda 24.x.x or similar

Step 4 — Create the rnaseq environment

RNAflow expects a Conda environment named rnaseq. Create it before running the pipeline:

conda create -n rnaseq python=3.10 -y
conda activate rnaseq

First Launch

When you open RNAflow, the app starts a small local server in the background — this allows the "Run" buttons to execute commands on your machine. You will see a green connection indicator in the top-right of the sidebar when the server is ready (usually within 2–3 seconds).

App startup sequence — the server is ready in 2–3 seconds

💡

Two modes: Copy and Run

Every step has two buttons. Copy copies the command to your clipboard so you can paste it in your own Terminal. Run executes the command directly inside the app with live output streaming. Both produce identical results.

Interface Overview

RNAflow interface: sidebar navigation on the left, step content and live terminal on the right

Step ✓ — System Check

✓

Verifies your environment before starting. Always run this first.

This step checks that Conda, Python, and the rnaseq environment exist and are accessible. It also checks for conflicting software that could cause problems later.

✅What good output looks like

# Good output
✓ conda found at /opt/miniforge3/bin/conda
✓ rnaseq environment exists
✓ Python 3.10.12 in rnaseq
✓ No conflicting base packages detected

❌

Problem: "conda: command not found"

Conda is not installed or not in your PATH. Install Miniforge from the Requirements section, then restart your Terminal and reopen RNAflow.

Step ⚙ — Configure Project

⚙

Set your organism, sequencing type, and project directory.

Fill in the configuration panel before starting the pipeline. These settings control which genome, annotation, and tools are used throughout all subsequent steps.

Setting	Description	Examples
Organism	The species you are studying	human, mouse, yeast, fly
Base folder	Where all project files will be saved	`/home/user/my_rnaseq`
Sequencing type	Single-end or paired-end reads	PE (most modern datasets)
Strandedness	Library strand specificity	Check kit protocol — usually "reverse"
Aligner	Tool for aligning reads to the genome	STAR (recommended) or HISAT2

💡

Not sure about strandedness?

Check your RNA-seq kit manual. Most modern kits (e.g., Illumina TruSeq) use reverse strand. If unsure, run infer_experiment.py from RSeQC after alignment (Step 6) and it will tell you.

Step 1 — Install Tools

Installs all bioinformatics tools via Conda into the rnaseq environment.

This step installs STAR, HISAT2, Salmon, FastQC, Trimmomatic, MultiQC, featureCounts, and other tools. It only needs to run once — Conda caches packages so reinstalling is fast.

What gets installed

STAR           — splice-aware aligner (fast, accurate)
HISAT2         — alternative aligner (lower memory)
Salmon         — quasi-mapping quantifier
FastQC         — per-read quality metrics
Trimmomatic    — adapter and quality trimming
MultiQC        — aggregate QC report
featureCounts  — gene-level read counting
samtools       — BAM file manipulation
bedtools       — genomic interval operations

⏱

This step can take 10–30 minutes on first run

Conda is downloading and installing large packages. The terminal will show progress. Do not close the app. Subsequent installs are much faster as packages are cached locally.

Step 2 — Download Data

Downloads your reference genome, GTF annotation, and FASTQ files.

You need three things: a reference genome (FASTA), a gene annotation file (GTF), and your raw sequencing reads (FASTQ). RNAflow generates the commands to download all of these from Ensembl, NCBI, or SRA.

File type	Source	Typical size
Genome FASTA	Ensembl / NCBI	700 MB – 3 GB
Gene annotation GTF	Ensembl / NCBI	50 – 200 MB
FASTQ reads (per sample)	SRA / ENA / your sequencer	1 – 20 GB

💡

Downloading from SRA

Public datasets are stored on NCBI SRA. Use the SRA accession number (e.g., SRR12345678) and the fasterq-dump command. RNAflow generates this command for you — just enter your accession numbers.

Step 3 — Quality Control

Assess the quality of your raw reads before analysis.

FastQC generates a per-sample quality report. MultiQC then combines all reports into a single HTML file. Always check this before trimming — it tells you which adapters are present and whether quality drops at the 3' end.

📊

See the next section "Understanding Results → FastQC Report" for a full guide to interpreting FastQC output.

Jump to FastQC Results →

Step 4 — Trimming

Remove adapter sequences and low-quality bases from your reads.

Trimming improves alignment quality by removing adapter contamination and poor-quality bases from the ends of reads. RNAflow uses Trimmomatic (standard) or fastp (faster, with HTML report).

Parameter	Meaning	Default
`LEADING`	Remove bases below this quality from start	3
`TRAILING`	Remove bases below this quality from end	3
`SLIDINGWINDOW`	Trim when window average falls below threshold	4:15
`MINLEN`	Discard reads shorter than this after trimming	36

✅Good trimming result

After trimming you should retain ≥ 90% of reads. If you are losing more than 20% of reads, check that you selected the correct adapter sequences.

97%

Reads surviving

1.2%

Dropped (too short)

75%

Reads surviving — investigate

Step 5 — Genome Index

Build a searchable index from the reference genome for fast alignment.

Before alignment, the genome FASTA must be indexed. This is done once and reused for all samples. STAR indexing requires 30–50 GB of RAM for human/mouse genomes. For smaller organisms (yeast, fly), 8 GB is sufficient.

💾

Memory requirements for STAR genome index

Human / Mouse genome: 32–50 GB RAM required
Yeast / Fly / Worm: 8 GB RAM sufficient

If your machine has less RAM, use HISAT2 instead — it builds a smaller index using only 8 GB for human.

Step 6 — Alignment

Align trimmed reads to the reference genome. Produces BAM files.

STAR aligns reads to the genome, accounting for splicing. Each sample produces a sorted, indexed BAM file. RNAflow runs all samples sequentially and streams STAR's output live in the terminal.

📊STAR alignment log — what to checkLog.final.out

85–95%

Uniquely mapped — excellent

70–84%

Uniquely mapped — acceptable

<70%

Uniquely mapped — investigate

See Understanding Results → Alignment Stats for full interpretation.

Step 7 — Gene Counting

Count reads mapping to each gene. Produces the count matrix.

featureCounts counts how many aligned reads overlap each gene in the annotation GTF. The output is a tab-delimited count matrix with genes as rows and samples as columns — this is the input for DESeq2.

Count matrix format (first few rows)

GeneID          sample1  sample2  sample3  sample4
ENSG00000000003   1234     1089     2341     1876
ENSG00000000005    456      398      821      701
ENSG00000000419   8901     9234    17543    16230

💡

Strandedness matters here

If you set the wrong strandedness in featureCounts, you will get very low assigned reads (<30%). The featureCounts output shows "Assigned" percentage — if it is low, try changing -s 0 (unstranded), -s 1 (forward), or -s 2 (reverse).

Step 9 — DESeq2 Differential Expression

Statistical analysis to find differentially expressed genes.

DESeq2 is an R package that uses a negative binomial model to identify genes that are significantly different between conditions. RNAflow generates the complete R script — you just click Run and the results appear in your project folder.

DESeq2 normalises for library size differences, estimates dispersion, and tests each gene for differential expression. The output is a table of genes with their log2 fold change, p-value, and adjusted p-value (padj).

Column	Meaning	Threshold for significance
`baseMean`	Average normalised count across all samples	— (higher = more reliable)
`log2FoldChange`	Fold change in log2 scale (positive = up in treatment)	\|LFC\| > 1
`pvalue`	Raw statistical p-value	— (use padj instead)
`padj`	P-value adjusted for multiple testing (Benjamini-Hochberg)	< 0.05 (typical)

Step 10 — Plots & Results

After DESeq2, RNAflow generates publication-ready figures automatically. See the full interpretation guide in the Understanding Results section below.

Advanced Steps — Multi-factor Design & GSEA

Multi-factor Design

Use when your experiment has more than one variable — for example, treatment AND time point, or treatment AND batch. The DESeq2 design formula becomes ~ batch + condition to control for the additional variable.

Batch Correction

If samples were sequenced in different batches, technical variation can mask biological signal. RNAflow supports:

ComBat-seq — corrects raw counts directly (recommended for DESeq2)
limma::removeBatchEffect — corrects normalised values for PCA/heatmaps
SVA — estimates hidden batch effects automatically when batch is unknown

GSEA & Pathway Analysis

After finding differentially expressed genes, pathway analysis tells you which biological processes are changed. RNAflow supports:

ORA (Over-Representation Analysis) — tests if your DE gene list is enriched in specific GO terms or KEGG pathways
GSEA (Gene Set Enrichment Analysis) — uses the full ranked gene list, more sensitive than ORA
Databases — GO (Biological Process, Molecular Function, Cellular Component), KEGG, Reactome

Understanding Results: FastQC Report

FastQC generates a report with multiple modules. Each module is marked with a ✅ (pass), ⚠️ (warn), or ❌ (fail). Warnings and fails are not always a problem — some are expected for RNA-seq data.

Per-base quality scores: green = excellent. A slight drop at the 3' end is normal and expected.

FastQC Module	Pass ✅	Warn/Fail — normal for RNA-seq?
Per Base Sequence Quality	Q > 28 across most positions	Slight drop at 3' end is normal
Per Sequence Quality	Peak at Q30+	Low peak = poor run
Per Base Sequence Content	~25% each A, T, G, C	⚠️ Warning is normal for RNA-seq — first ~10 bp are biased
Sequence Duplication	<50% duplicated	⚠️ Warning common in RNA-seq — highly expressed genes duplicate more
Overrepresented Sequences	No hits	❌ Fail = adapter contamination → trim before alignment
Adapter Content	Near zero	❌ Fail = adapter present → trimming required

Understanding Results: Alignment Statistics

After STAR alignment, check Log.final.out for each sample. This file tells you how many reads aligned and where.

Metric	Good value	Problem if…
Uniquely mapped reads %	≥ 85%	< 70% — wrong genome? wrong organism?
Multi-mapped reads %	< 10%	> 20% — repetitive transcriptome, short reads
Unmapped: too short %	< 5%	> 20% — trimming too aggressive, or wrong genome
Unmapped: other %	< 2%	> 10% — contamination, wrong organism

⚠️

Low alignment rate (<70%)? Most common causes:

1. Wrong genome build — make sure genome and GTF versions match (e.g., both GRCh38)
2. Wrong organism — verify your sample came from the organism you expect
3. rRNA contamination — ribosomal RNA wasn't depleted; many reads map to rDNA loci
4. Over-trimming — reads too short after trimming to align uniquely

Understanding Results: Count Matrix

The count matrix from featureCounts should show a reasonable distribution across samples. Check the "Assigned" percentage in featureCounts output — this should be >60% for strand-specific libraries and >50% for unstranded.

❌

Assigned reads <30%? Almost certainly wrong strandedness.

Re-run featureCounts with a different -s value:
-s 0 = unstranded
-s 1 = stranded (forward)
-s 2 = reverse stranded (most common)

The correct setting will jump assignment to >60%.

Understanding Results: PCA Plot

Principal Component Analysis (PCA) shows how similar your samples are to each other. Each dot is one sample. Samples of the same condition should cluster together.

Good PCA: conditions cluster separately, replicates cluster together. PC1 captures most of the variance.

What you see	What it means
Conditions cluster separately	Strong biological signal — your experiment worked
Replicates cluster tightly	Low technical variation — high quality data
One replicate far from its group	Possible outlier — investigate that sample (check QC, alignment stats)
All samples mix together	No separation — biological effect is subtle or absent
Samples cluster by sequencing date not condition	Batch effect — use batch correction before DESeq2

Understanding Results: Volcano Plot

A volcano plot shows all genes with their fold change (x-axis) and statistical significance (y-axis). Significant DEGs are in the upper left (down-regulated) and upper right (up-regulated) corners.

Volcano plot: red = significantly up-regulated, blue = significantly down-regulated. Grey dots are not significant.

Region	Colour	Meaning
Upper right (high LFC, low padj)	Red	Significantly up-regulated in treatment
Upper left (low LFC, low padj)	Blue	Significantly down-regulated in treatment
Centre / bottom	Grey	Not significant — no strong evidence of change
Right but low on y-axis	Any	High fold change but not significant — too few replicates or high variability

Understanding Results: Heatmap

The heatmap shows normalised expression of the top differentially expressed genes across all samples. Each column is a sample, each row is a gene. Samples are clustered hierarchically — similar expression profiles group together.

🔍

Reading the heatmap colour scale

Values shown are VST-transformed (Variance Stabilising Transformation), not raw counts. The colour represents relative expression — dark red = high expression, dark blue = low expression. You should see blocks of similar colour within the same condition.

Understanding Results: GSEA & Pathway Analysis

GSEA tests whether a defined set of genes (e.g., a GO term or KEGG pathway) is enriched at the top or bottom of your ranked gene list.

Term	Definition
NES (Normalized Enrichment Score)	Positive NES = pathway genes tend to be up-regulated. Negative NES = down-regulated.
pvalue / p.adjust	Statistical significance. Use p.adjust < 0.05 as threshold.
qvalue	Alternative FDR estimate. < 0.2 is commonly used for GSEA.
setSize	Number of genes in the pathway. Very small (<5) or very large (>500) sets are less reliable.

Troubleshooting: Installation Issues

⚠️ "RNAflow is damaged and can't be opened" (macOS)

macOS Gatekeeper is blocking the app because it is not notarized with Apple. Fix it by running in Terminal:
xattr -cr /Applications/RNAflow.app
Then launch RNAflow normally.

⚠️ The app opens but shows a blank white screen

The HTML file may not have loaded correctly. Try:
1. Close and reopen the app
2. In the menu bar: View → Reload (Cmd+R on Mac, Ctrl+R on Windows)
3. Check that you have not moved the app after extracting it from the ZIP

⚠️ Windows: "Windows protected your PC" (SmartScreen warning)

Click "More info" then "Run anyway". This appears because the installer is not yet signed with a Windows certificate.

Troubleshooting: Conda Problems

⚠️ "conda: command not found" in the system check

Conda is not in your PATH. Possible fixes:
1. Restart your Terminal after installing Miniforge
2. Run ~/miniforge3/bin/conda init zsh (macOS) or ~/miniforge3/bin/conda init bash (Linux)
3. Restart Terminal again
4. Run the system check again

⚠️ "EnvironmentNotFound: Could not find conda environment: rnaseq"

Create the environment first:
conda create -n rnaseq python=3.10 -y
Then re-run the system check.

⚠️ Conda install takes forever / hangs on "Solving environment"

The conda solver can be slow. Fix with mamba (fast solver):
conda install -n base -c conda-forge mamba -y
Then RNAflow will use mamba automatically for faster installs.

Troubleshooting: Alignment Errors

⚠️ STAR exits with "EXITING because of FATAL ERROR: Genome version is too old"

The STAR version used to build the genome index does not match the STAR version used for alignment. Rebuild the index with the same STAR version:
conda activate rnaseq && STAR --version
Then re-run Step 5 (Genome Index) to regenerate the index.

⚠️ Alignment rate <50%

Common causes and fixes:
1. Wrong genome: confirm FASTA and GTF are from the same organism and build
2. rRNA contamination: check if FastQC shows rRNA sequences in overrepresented sequences
3. Very short reads (<30 bp): adjust --outFilterScoreMinOverLread in STAR settings
4. Wrong read format: single-end vs paired-end mismatch — check your FASTQ files

⚠️ "FATAL ERROR: could not open genome files" (STAR)

STAR cannot find the genome index. Check that:
1. Step 5 (Genome Index) completed successfully
2. The genome index path in your config matches where the index was built
3. You have read permissions on the genome folder

Troubleshooting: R / DESeq2 Errors

⚠️ "there is no package called 'DESeq2'"

Install DESeq2 from Bioconductor in R:
if (!require("BiocManager")) install.packages("BiocManager")
BiocManager::install("DESeq2")
This needs to be done once. RNAflow provides this command in the DESeq2 step.

⚠️ "all genes were filtered out" / no results

DESeq2 filters genes with very low counts. This happens if:
1. Wrong strandedness in featureCounts — most reads were not assigned
2. Too few replicates — DESeq2 needs at least 2 per condition (3+ recommended)
3. Sample mislabeling — check your sample metadata matches your count matrix columns

⚠️ "Error: estimating size factors: every gene contains at least one zero"

Your count matrix has a gene with zero counts in at least one sample in every row. This is rare — check that featureCounts produced a proper matrix (not all zeros). Also verify the GTF and genome build match.

Troubleshooting: macOS-Specific Issues

⚠️ "python3: command not found" inside the app

The local server requires Python 3. On macOS 12+, Python 3 is not pre-installed. Fix:
conda activate base
Or install Python via Homebrew: brew install python
Then restart RNAflow.

⚠️ The server connection dot stays orange/red

The local Python server failed to start. To diagnose:
1. Open the app menu → Server → Server Status to see if it is running
2. Try Server → Start Local Server manually
3. If Python is missing, install it as above
4. In Copy mode (without the server), you can still use all commands — just paste them in your own Terminal

⚠️ STAR genome indexing crashes with "out of memory"

Human and mouse genomes require ~32 GB RAM for STAR indexing. If your Mac has less:
1. Use HISAT2 instead — change the aligner in Step ⚙ Configure. HISAT2 only needs 8 GB.
2. Or reduce STAR memory by adding --genomeSAindexNbases 11 for smaller genomes (yeast etc.)

← Back to Download Page