slow5lib 0.1.0

Rust re-implementation of slow5lib: read and write SLOW5/BLOW5 nanopore sequencing files
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

# Contributing

## Pull requests

Open PRs against the `dev` branch, not `main`. The `dev` branch does not exist yet -- it will be created after the first release is cut.

## Running tests

```bash
cargo test                           # all tests
cargo test <name>                    # single test by name substring
cargo fmt --check                    # formatting (matches CI)
cargo clippy -- -D clippy::all      # lints (matches CI)
cargo doc --no-deps --all-features  # docs must be warning-free
```

## Parity tests

`tests/parity.rs` compares Rust writer output against committed reference files produced by slow5tools v1.3.0. These are byte-identical for deterministic compression combos and value-level for Zstd/Zlib.

`tests/c_parity.rs` runs live against `slow5tools` on PATH. Tests skip automatically if `slow5tools` is not found or `tests/data/small.blow5` is absent. They do not need the `#[ignore]` attribute.

## Fuzz targets

Requires nightly and `cargo-fuzz`:

```bash
cargo +nightly fuzz run blow5_reader
cargo +nightly fuzz run slow5_reader
cargo +nightly fuzz run svbzd_decode
```

Corpus and artifacts live under `fuzz/corpus/` and `fuzz/artifacts/`.

## Re-validating after upstream releases

When `hasindu2008/slow5lib` or `slow5tools` cuts a new release, re-run `tests/c_parity.rs` against it and check for wire-format or behavioural changes before assuming continued compatibility. Note any resulting changes (new compression methods, format version bumps, field changes) in `CHANGELOG.md` and `TODO.md`, even if no code change is needed yet.

## Filing bugs upstream

If you suspect a bug in `hasindu2008/slow5lib` or `slow5tools` while working on this crate, verify it manually against the C tool first -- rule out a bug in this reimplementation and rule out malformed input before filing. Do not file a report based solely on an AI-generated test case or reproduction; reproduce it yourself and include the exact command line, upstream version, and a minimal input file in the report.

## Benchmarks

```bash
cargo bench --bench throughput                  # sequential read throughput
cargo bench --bench indexed                     # indexed random access
cargo bench --bench parallel --features rayon  # parallel decompression
```

Criterion HTML reports land in `target/criterion/`.

## Rules

- Wire compatibility with hasindu2008/slow5lib is non-negotiable. Changes to encode/decode logic must be validated against the C library output. Where the SLOW5 spec and the C implementation disagree, follow the C implementation.
- No `mmap` anywhere. Use `BufReader<File>` for sequential reads and `FileExt::read_at` for indexed random access.
- All CI jobs must pass: fmt, clippy, test (Linux x86-64, Linux AArch64, macOS ARM), MSRV (1.87), doc.

## AI assistance

This library was developed with AI assistance (Claude). The architecture decisions, wire-compatibility validation, and algorithm choices are the author's own; AI tooling served as an accelerator over existing skill, not a replacement for it.