Release Notes
Added
--mapper spearfish: spearfish as a read-mode
backend. Maps reads to the transcriptome in process with spearfish (crates spearfish and
long-read-rad, 0.1), building its index from --annotated/--novel or opening a .sfi
given as --index. The preset follows --seq-tech; hits are weighted by their score
difference from the read's best, and with --model-truncation spans are extended to the read
ends. Transcriptome read mode only.- RAD input:
oarfish -a mappings.rad quantifies the bulk_long_read RAD files that
spearfish map --rad writes, taking the transcripts, score scale, preset and span settings
from the file.
--model-truncation: a learned placement model. Each alignment's score probability is
multiplied by the probability of where it lands on the transcript under a mixture of
3'-anchored, 5'-anchored, full-length and uniformly placed reads, whose weights, read-length
laws and end-gap laws are learned in the EM; the fitted mixture is logged. It adapts to the
protocol without settings. Compared with the default model, on a direct-RNA spike-in run it
raises isoform-level Spearman from 0.820 to 0.882; against a spike-in reference padded with
fabricated isoforms it cuts the mass placed on them from 9.4% to 0.5%; on simulated reads
Spearman goes from 0.953 to 0.956. Against short-read TPM on 16 matched samples, it agrees
better than the default model on all 8 direct-RNA samples and on 6 of 8 cDNA samples (all 8
on expressed transcripts). It works with bootstraps and in genome mode, and conflicts with
--model-coverage. (Supersedes the 3'-anchored model proposed in #75, which mis-ranked
isoforms whenever reads were not 3'-anchored.)--presence-model spike-slab|bayes (experimental). A per-transcript presence posterior
that discounts low-evidence transcripts during the EM; reduces false positives at some cost to
true low-abundance transcripts. Off by default.meta_info.json records the oarfish version and the run's start and end
times, in the same fields and format as salmon (oarfish_version,
start_time, end_time; e.g. "Tue Jan 15 11:10:00 2019", local time), for
bulk and single-cell runs.
Changed
- Coverage model (
logistic): corrected bin arithmetic. Coverage was filled on bins of rounded
width but read weights were looked up on a fixed 100-nt grid, so the two disagreed about where
bins lie; the bin where each read ends was dropped by accident; and the overlap was computed in
unsigned integers that could underflow. Both now use one exact bin layout (len / nbins), with
the one behaviour the accident encoded made a stated rule: a read's partly covered end bin is
left out of both its coverage and its weight when it fully covers another bin (counting it
costs accuracy). Versus 0.10.3's coverage model, Spearman moves by at most 0.001 on simulated
reads and spike-ins, except for a gain of 0.013 against an over-annotated spike-in reference;
agreement with short-read TPM improves on 12 of 17 matched samples.
--coverage-model none|logistic|truncation selects the positional model in one flag;
--model-coverage and --model-truncation remain as shorthands. Contradictory combinations,
and the truncation model in single-cell mode (previously ignored silently), are errors.--score-prob-denom defaults to 3 (was 5). Sharper weighting of a read's alignments toward
the best-scoring one. On simulated reads with exact truth it raises Spearman slightly (0.950 to
0.953 for the default model, 0.954 to 0.956 with --model-truncation); against short-read TPM
it improved 27 of 28 matched samples in a held-out sweep. On spike-ins it raises Spearman but
slightly worsens MARD. --score-prob-denom 5 restores the previous behaviour exactly.- Tail-neutral alignment scores, for all models. The score credit a read's poly(A) tail earns
by aligning to an annotated A-run at a transcript's end is removed, using the aligner's match
score (from the minimap2 @PG line or the rammap preset). On simulated reads with poly(A)
tails this improves the default model (Spearman 0.948 to 0.950, and 22% fewer false
positives, with --score-prob-denom held at 5); outputs on data without poly(A) tails are
unchanged.
- EM engines. Without a per-read model term, the EM runs over equivalence classes (CSR
layout); per-read models use an atomic-free CSR layout (OARFISH_READ_EM=local|atomic selects
the alternatives; --per-read-em forces the per-read EM). Estimates match the previous
release up to summation order.
- Reads are ordered by likeliest transcript before the per-read and truncation EMs, which
speeds them up; --write-assignment-probs still lists reads in input order.
Performance
Versus 0.10.3, from transcriptome BAMs of 35M and 75M alignments at 16 threads:
|
time |
peak memory |
| default model |
15–16× faster |
27–33% lower |
| coverage model |
9–10× faster |
2–22% lower |
| truncation model (new) |
about 2× the default model's time |
about the coverage model's |
- BAM parsing about 4.5× faster than 0.10.3. Parsing is serial (only BGZF decompression is
threaded), so per-record work is wall time: records are now read undecoded into reused
buffers, the CIGAR, tags and sequence are read from their bytes only where a filter needs
them, and records are no longer cloned.
- Lower peak memory: the per-alignment record shrinks from 24 to 16 bytes (an unused field
removed); coverage probabilities exist only under the coverage model; the per-read EM reads the
alignment store instead of copying it; the truncation EM keeps its frozen weights in store order.
- EM engines: the equivalence-class and per-read EMs run without atomics (see above); the
truncation EM fits its placement parameters on a 1M-read sample when there are more reads,
then holds them fixed and accelerates the abundance updates (SQUAREM); estimates match a fit on
all reads (OARFISH_TRUNC_SAMPLE=0).
- Deterministic: the truncation EM (and the spike-slab presence model) give byte-identical
output from run to run and across thread counts.
- All parallel work stays within
--threads (the store reorder and coverage normalization
previously used every core).
- Genome-BAM and raw-read modes are as fast or faster than 0.10.3 with the same memory (genome
BAMs about 2.3× faster).
Install oarfish 0.11.0
Install prebuilt binaries via shell script
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/COMBINE-lab/oarfish/releases/download/v0.11.0/oarfish-installer.sh | sh
Download oarfish 0.11.0
