Using the library
The spearfish crate is the library behind the command line (spearfish = "0.2" in
Cargo.toml). Its default features read FASTA/FASTQ (fasta) and write RAD files (rad); an
embedding that needs neither, such as oarfish’s, can turn them off.
use std::sync::Arc;use spearfish::{Index, IndexOptions, MapSettings, Preset};
// Build an index in memory (or open one written by `spearfish index`).let txs = spearfish::read_transcripts("transcripts.fa.gz".as_ref())?;let opts = IndexOptions::builder().scheme("lcp:K=3").build();let (index, report) = Index::build(txs, &opts)?;let index = Arc::new(index);
// A preset, and the settings to change from it.let mapper = MapSettings::builder(Preset::Hifi) .extend_ends(true) .tie_kappa(5.0) .mapper(index.clone())?;
let read = mapper.map(b"ACGT...");for hit in &read.hits { println!("{} {} {}", index.tx_name(hit.tx), hit.score, hit.reverse);}-
MapSettingsholds a preset and one optional field per setting; unset fields keep the preset’s value.resolve()gives the completeMapOptions(which serialize to JSON), and rejects settings that contradict each other. -
MapperisSend + Sync: share one across threads. -
Preset,Hit,MappedRead,IndexOptionsandMapSettingsare#[non_exhaustive], so that a release can add a preset or a field without breaking callers: match aPresetwith a wildcard arm, and buildIndexOptionsandMapSettingswith their builders. -
Hitcoordinates are raw bases: query spans on the read’s forward strand, transcript spans on the transcript. Score differences convert to probabilities withexp(-d / spearfish::SCORE_DENOM). -
Index::manifest()andIndex::id()give an index’s provenance and identifier;spearfish::provenance::BuildInfo::current()the library’s version and git revision. -
spearfish::outputwrites mapped reads asspearfish mapdoes: TSV (TSV_HEADER,tsv_lines), PAF (paf_lines) and, with the defaultradfeature, RAD records for oarfish (rad_writer,rad_record). The text writers append to a byte buffer, so each thread can format its own batch. -
The allocator behind
spearfish map’s per-thread arenas (--bump-alloc, on by default in the binary) is a crate of its own,nudgy(crates/nudgyin the repository):nudgy::Bumpwraps a program’s global allocator and serves small blocks from per-thread arenas. The library never turns them on, and the Python package does without them. Only a program can choose its global allocator, so an embedding opts in itself: it depends onnudgy, declaresBumparound the allocator it uses, and callsnudgy::enable()before mapping. Until that call every allocation goes to the wrapped allocator. Afterwardsnudgy::stats()says how many arenas were in use and how often a thread went without one. An arena serves blocks of up to 8 KB, the best limit forspearfish map;nudgy::enable_with(nudgy::Config::new().with_max_block(bytes))turns the arenas on with another, for a program whose other allocations make another one better.use nudgy::Bump;#[global_allocator]static GLOBAL: Bump<std::alloc::System> = Bump::new(std::alloc::System);fn main() {nudgy::enable();// build a Mapper and map reads}
The API documentation is cargo doc -p spearfish --open.