Skip to content

01-quickstart.md

Latest commit

 

History

History
74 lines (54 loc) · 2.6 KB

01-quickstart.md

File metadata and controls

74 lines (54 loc) · 2.6 KB
Raw

Tutorial 1: index, align, and read the provenance

This walkthrough uses only the committed toy data (test-data/toy/). You do not need to read any source code to follow it. Everything here is also runnable as one script:

bash docs/tutorials/run_tutorial.sh

The command line is STAR's exactly (flat --optionName flags, operation chosen by --runMode), so every command below runs verbatim on upstream STAR too.

1. Build a genome index

STAR --runMode genomeGenerate \
  --genomeDir index \
  --genomeFastaFiles test-data/toy/genome.fa \
  --genomeSAindexNbases 7

This writes index/index.starrs (a versioned suffix-array index) and two provenance files: index.starrs.prov.json (what produced the index) and run.prov.json / run.prov.dot (the run graph). Building the same FASTA again yields a byte-identical index (its SHA-256 is stable).

2. Align single-end reads

STAR --runMode alignReads \
  --genomeDir index \
  --readFilesIn test-data/toy/reads.fq \
  --outFileNamePrefix ./ \
  --runThreadN 8

(alignReads is the default --runMode, so it can be omitted.)

This writes Aligned.out.sam. Because determinism is a first-class requirement, the output is byte-identical regardless of --runThreadN: try 1, 8, 16 and compare with shasum -a 256 Aligned.out.sam. Unmapped reads are not written (as in STAR by default), so the sixth toy read (r6_unmapped) does not appear.

3. Read the provenance

Every output has a sidecar. Aligned.out.sam.prov.json records the SHA-256 of the exact inputs that produced the SAM (the index and the reads, and nothing unrelated), the effective parameters, the tool version and git commit, and the run timestamp:

cat Aligned.out.sam.prov.json

The run graph ties the steps together and can be rendered with Graphviz:

STAR --runMode graph --graphManifest run.prov.json   # STAR-rs extension: prints the DOT
dot -Tsvg run.prov.dot -o run.prov.svg               # if graphviz is installed

4. Compare against the STAR oracle

If STAR 2.7.11b is installed, the differential test runs both tools on this toy data and checks that they agree on every read's placement (the 11 mandatory SAM fields), with the known, intentional differences recorded in DIVERGENCES.md:

cargo test -p star-cli --test differential_toy

What to read next

  • README.md for the reproducibility positioning.
  • DIVERGENCES.md if you are comparing to upstream STAR.
  • ROADMAP.md for what lands next (splicing, paired-end, multimapping, Solo).