STAR-rs

An independent, clean-room reimplementation of the STAR RNA-seq aligner in Rust, reproducible by design. STAR-rs emulates STAR 2.7.11b and reproduces its output byte-for-byte. It is not affiliated with or endorsed by the official STAR project, and is not a "STAR 3" release.

STAR-rs is built on a single principle: the same inputs, code and environment must produce byte-identical output, independent of thread count, with enough provenance in every artifact to reproduce and audit it. Correctness is defined against native STAR 2.7.11b and enforced by continuous differential testing.

Status

STAR-rs reproduces STAR 2.7.11b byte-for-byte across effectively the whole 2.7.11b surface, emitting output that is identical regardless of thread count. All 200 user-facing STAR parameters are recognized (a real STAR command line runs verbatim). The implemented, oracle-locked feature set:

• Core align. Genome index (incl. sparse --genomeSAsparseD); single- and paired-end alignment; splice junctions and the annotated junction database (sjdb); indels; multimapping; 2-pass; PE mate-overlap merge (--peOverlapNbasesMin).
• Output. SAM and BAM (Unsorted + SortedByCoordinate); the full --outSAMattributes set; signal tracks (--outWigType); --outFilterType BySJout; unmapped reads (SAM/FASTX).
• Quant. Per-gene counts (--quantMode GeneCounts); transcriptome projection (TranscriptomeSAM, SE + PE).
• Chimeric. Chimeric.out.junction (both strands, WithinBAM, PE), multimapping chimeras (--chimMultimapNmax), PE-merged chimeras.
• STARsolo. CB_UMI_Simple, CB_UMI_Complex, SmartSeq; raw + filtered matrices; all six UMI dedup modes; every --soloCBmatchWLtype barcode-correction mode (Exact/1MM/1MM_multi/ 1MM_multi_pseudocounts/1MM_multi_Nbase_pseudocounts, the last being CellRanger's, with STAR's quality-weighted posterior); --soloMultiMappers; features Gene/GeneFull/SJ/Velocyto/ Transcript3p; EmptyDrops_CR cell calling; Summary.csv/*.stats; CB/UB BAM tags.
• 10x chemistry auto-detection (a convenience beyond STAR): --soloChemistry auto picks the 10x chemistry CellRanger-style from a sample of the barcode reads (or name it, --soloChemistry SC3Pv3), filling in the barcode geometry + strand + whitelist; it only selects parameters, so every output byte stays exactly STAR's. Whitelists are supplied via --soloCBwhitelistDir.
• WASP allele-specific filtering (vW/vA/vG).
• Run modes. inputAlignmentsFromBAM (coverage signal + bamRemoveDuplicates); liftOver; soloCellFiltering; genome transform (--genomeTransformType, Haploid + Diploid, with SAM/SJ/ Quant back-transform); --genomeType SuperTranscriptome; on-the-fly insertSequences.
• STARlong: the long-read chaining-DP binary (STARlong), incl. chimeric.

Every intentional difference from native STAR is recorded and locked by a test in DIVERGENCES.md; the residual scope (a set of recognized-but-value-restricted knobs, and a ~0.05% low-complexity real-data enumeration tail) is in docs/unsupported-parameters.md and ROADMAP.md.

Performance

On a human GIAB RNA-seq sample against the full GRCh38 genome (Apple M4 Max, 16 cores), STAR-rs reproduces native STAR 2.7.11b's alignment placement byte-for-byte and is ~1.8× faster at 8 threads and ~2.2× faster at 16 threads, within ~4% single-threaded, with markedly better thread scaling (4.1× vs 1.8× from 1→16 cores). Index generation is also substantially faster (multi-core). Full methodology and numbers are in docs/BENCHMARK.md.

Quickstart

STAR-rs's CLI is STAR's verbatim: the operation is chosen by --runMode (default alignReads) and every option is a flat --optionName flag. The binary is STAR (and STARlong), a drop-in for native STAR 2.7.11b: the same command name, so an existing STAR command line runs unchanged. If you also have native STAR installed, keep it on your PATH and point the differential harness at it with STAR_BIN=/path/to/native/STAR (the harness prefers $STAR_BIN, then /opt/homebrew/bin/STAR, before falling back to PATH).

# Clone, then build the `STAR` binary (a drop-in for native STAR 2.7.11b).
git clone https://github.com/IPNP-BIPN/STAR-rs && cd STAR-rs
cargo build --release --workspace           # -> target/release/STAR
cargo install --path crates/star-cli        # optional: puts `STAR` on your PATH (~/.cargo/bin)

# Run the full local quality gate (fmt + clippy-as-errors + all tests).
bash scripts/check.sh

# Provenance-quality version string (SemVer + commit + emulated reference + toolchain).
STAR --version

# Build a genome index, then align the toy reads. These are STAR's exact flags: a real STAR
# command line runs unchanged.
STAR --runMode genomeGenerate --genomeDir idx \
  --genomeFastaFiles test-data/toy/genome.fa --genomeSAindexNbases 7
STAR --genomeDir idx --readFilesIn test-data/toy/reads.fq \
  --outFileNamePrefix ./ --runThreadN 8      # alignReads is the default --runMode

Not installed? Use ./target/release/STAR …, or cargo run -p star-cli -- … from the workspace.

For a guided, self-checking walkthrough (index, align, read the provenance, run the differential), see the executable tutorial docs/tutorials/01-quickstart.md (bash docs/tutorials/run_tutorial.sh).

What makes it reproducible

• Deterministic output. The SAM (and every artifact) is byte-identical whether you use 1 thread or 16. Parallelism never changes order or content; observable order is always an explicit, total sort.
• Provenance in the output. Alignment carries its provenance in the SAM/BAM header, like STAR: the @PG / @CO lines record the tool identity, the emulated STAR version (VN:2.7.11b) and the exact command line. genomeGenerate additionally writes an index provenance sidecar listing the SHA-256 of the inputs that produced it, the effective parameters, the tool version and git commit, and the index format version, so an index can always be traced back to what built it.
• Differential testing against the oracle. star-diff runs the native STAR 2.7.11b binary and STAR-rs on the same inputs and compares normalized SAM. Any difference is either fixed or recorded in DIVERGENCES.md with a locking test.

Architecture

A workspace of small crates, each with one job and a typed, documented I/O contract:

Crate	Role
star-core	Shared vocabulary (2-bit DNA, strand, interval, CIGAR, record, score). No logic.
star-io	FASTA/FASTQ reading, SAM (text) and BAM writing.
star-index	Suffix-array index + prefix table; versioned on-disk format.
star-seed	Maximal Mappable Prefix (MMP) seeding.
star-align	Stitch seeds into scored alignments; canonical tie-breaking.
star-filter	Read-level filter contracts; the coverage/multimapping logic itself lives in star-align.
star-solo	Single-cell contract crate; STARsolo (--soloType) is implemented in star-cli's solo module.
star-provenance	SHA-256 sidecars + run graph.
star-diff	SAM normalization + native STAR oracle harness.
star-cli	The STAR / STARlong binaries: orchestration, provenance, and the quant / transcriptome / WASP / chimeric / solo output stages.

The crate-dependency graph is generated from the workspace (never hand-drawn): docs/architecture/crates.dot, regenerated and drift-checked by scripts/check.sh.

Comparing to upstream STAR

If you are comparing STAR-rs output to STAR, read DIVERGENCES.md first: it lists every intentional difference and how each is locked by a test. STAR-rs "fixes STAR's bugs" reproducibly by making each such choice explicit, documented and tested, never silent.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project shall be dual-licensed as above, without any additional terms or conditions.

Acknowledgements and citation

STAR-rs is an independent, clean-room reimplementation. It is not affiliated with, endorsed by, or derived from the source code of the official STAR project, and is not a "STAR 3" release. All credit for the STAR algorithm belongs to its authors. If you use STAR-rs in published work, please cite the original STAR:

Dobin A, Davis CA, Schlesinger F, Drenkow J, Zaleski C, Jha S, Batut P, Chaisson M, Gingeras TR. STAR: ultrafast universal RNA-seq aligner. Bioinformatics. 2013;29(1):15–21. doi:10.1093/bioinformatics/bts635

To cite STAR-rs itself (the reimplementation), use the metadata in CITATION.cff at the repository root; a DOI is minted from the archived release. STAR-rs reproduces STAR's results, so scientific credit for the algorithm remains with the STAR authors cited above.