/star-rna-seq-aligner

name: "star-rna-seq-aligner"
description: "Splice-aware RNA-seq aligner producing sorted BAM and splice junction tables. Builds genome index, runs two-pass alignment for better junctions. Outputs sorted BAM, junctions (SJ.out.tab), stats (Log.final.out), optional gene counts. Use Salmon for fast pseudoalignment; STAR when a BAM is needed for variant calling, IGV, or ENCODE pipelines."
license: "MIT"

STAR — Spliced RNA-seq Aligner

Overview

STAR (Spliced Transcripts Alignment to a Reference) aligns RNA-seq reads to a genome in a splice-aware manner, identifying novel and annotated splice junctions in a single pass. It generates coordinate-sorted BAM files compatible with samtools, IGV, deeptools, and GATK. STAR's 2-pass mode re-aligns reads using junctions discovered in the first pass, improving sensitivity for novel splice sites. With `--quantMode GeneCounts`, STAR simultaneously produces gene-level read count tables without requiring a separate featureCounts or HTSeq step.

When to Use

• Aligning bulk RNA-seq reads to a reference genome when downstream tools require a BAM file (variant calling, visualization, deeptools)
• Running ENCODE-compliant RNA-seq pipelines that mandate genome alignment
• Discovering novel splice junctions and alternative splicing events in the dataset
• Generating gene count tables alongside BAM alignment in a single step with `--quantMode GeneCounts`
• Processing long reads or reads with high mismatch rates by tuning `--outFilterMismatchNmax`
• Use **Salmon** instead when you only need transcript/gene quantification and do not need a BAM file — Salmon is 20-50× faster

Prerequisites

• **Software**: STAR ≥ 2.7.0 (conda or compiled binary)
• **Reference files**: genome FASTA + GTF annotation (same assembly)
• **RAM**: 30–32 GB for human/mouse genome index; 8–16 GB for smaller genomes
• **Disk**: ~25 GB for human genome index, ~5–10 GB per sample BAM

> **Check before installing**: The tool may already be available in the current environment (e.g., inside a `pixi` / `conda` env). Run `command -v STAR` first and skip the install commands below if it returns a path. When running inside a pixi project, invoke the tool via `pixi run STAR` rather than bare `STAR`.

# Install with conda (recommended)
conda install -c bioconda star

# Verify
STAR --version
# STAR_2.7.11a

# Or compile from source
git clone https://github.com/alexdobin/STAR
cd STAR/source && make STAR

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: reference_bundle
    kind: required
    source: user
    ask: "Which species, genome assembly, and matching GTF annotation release should be used?"
    default: null

  - id: D2
    param: --sjdbOverhang
    kind: derived
    source: data
    ask: "What is the longest trimmed read length observed in the FASTQ files?"
    default: "maximum trimmed read length minus 1"

  - id: D3
    param: --quantMode
    kind: derived
    source: upstream
    ask: "Does the downstream workflow require STAR gene counts, transcriptome BAM for RSEM, or only the genomic BAM?"
    default: "no quantMode; emit a coordinate-sorted genomic BAM"

  - id: D4
    param: --twopassMode
    kind: optional
    source: user
    ask: "Should alignment prioritize sensitive discovery of novel splice junctions?"
    default: "None"

  - id: D5
    param: --outFilterMultimapNmax
    kind: optional
    source: user
    ask: "How many genomic loci may a read match before it is treated as too ambiguous to align?"
    default: 10

  - id: D6
    param: --outFilterMismatchNmax
    kind: optional
    source: user
    ask: "Does this assay require a non-default maximum number of alignment mismatches?"
    default: 10

  - id: D7
    param: --alignIntronMax
    kind: optional_conditional
    source: literature
    ask: "Does the organism or assay require an intron-length limit different from the reference bundle's standard setting?"
    default: 1000000

  - id: D8
    param: --genomeSAindexNbases
    kind: never_ask
    source: data
    reason: "Calculated from genome length to size the index; it affects memory use, not the biological result."
    default: "min(14, floor(log2(genome_length) / 2 - 1))"

  - id: D9
    param: --runThreadN
    kind: never_ask
    source: data
    reason: "Affects runtime only, not the alignments"
    default: "min(8, available_cores)"

D2 is measured from the input FASTQ rather than chosen by the user. The GTF, genome FASTA, and STAR index must all come from the same reference release. `GeneCounts` produces STAR's own counts; omit it when featureCounts will produce the count matrix. `TranscriptomeSAM` is for transcriptome-BAM consumers such as RSEM, not ordinary Salmon quantification.

Quick Start

# 1. Generate genome index (~30 min, run once)
STAR --runMode genomeGenerate \
     --runThreadN 8 \
     --genomeDir genome/star_index \
     --genomeFastaFiles genome/GRCh38.fa \
     --sjdbGTFfile genome/gencode.v47.gtf \
     --sjdbOverhang 100    # ReadLength - 1

# 2. Align paired-end reads (~10-20 min)
STAR --runThreadN 8 \
     --genomeDir genome/star_index \
     --readFilesIn sample_R1.fastq.gz sample_R2.fastq.gz \
     --readFilesCommand zcat \
     --outSAMtype BAM SortedByCoordinate \
     --outFileNamePrefix results/sample/

# 3. Index the BAM
samtools index results/sample/Aligned.sortedByCoord.out.bam

Workflow

Step 1: Prepare Reference Files

Download a genome FASTA and matching GTF annotation (same assembly version).

# Download GRCh38 genome and GENCODE annotation
wget https://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_human/release_47/GRCh38.primary_assembly.genome.fa.gz
wget https://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_human/release_47/gencode.v47.primary_assembly.annotation.gtf.gz

gunzip GRCh38.primary_assembly.genome.fa.gz gencode.v47.primary_assembly.annotation.gtf.gz
mkdir -p genome/star_index

echo