DNA STORAGE API

Compact, modular Reed–Solomon pipelines and reproducible benchmarks for DNA data storage experiments. Pure Python 3.9+ — quick to run, easy to extend.

Pipeline overview (visual)

Features (v0.2.0 – December 2025)

• Reed–Solomon encoder/decoder over GF(256) – interpolation-based erasure recovery
• Automatic (k,n) recommendation for given oligo length and overhead (pretty_recommendation)
• Fully pluggable pipeline: Input → Encoder → Mapper → Channel → Aligner → Decoder → Output
• Simple global aligner + per-oligo consensus
• Channel models: substitution, insertion, deletion, coverage dropout
• Safety checks: warns when RS block size exceeds available oligo payload

Note

Current implementation of the library handles only substitutions and deletions. Thus the channel in this iteration of the library is D(eletion)S(ubstitution) channel.

Exciting: the upcoming version 0.3

• If we know that there are no insertions in the sequence we can simply filter the traces by lengths.
• However, real world DNA storage systems introduce insertions thus real-world systems do not feed the raw consensus length to the RS decoder due to insertions and deletions.
• A better idea is to pad the consensus to exactly N symbols that can correct ≤ (n-k)/2, using either some kind of aligner or library edlib for measuring edit distances.
• Next iteration of this library adds an interesting algorithm for trace reconstruction alignment Bidirectional Beam Search in de Bruijn graphs paired smartly with adaptive Markov Models.

Quick start

Clone, create a virtualenv, install, and run the example (copy/paste):

git clone https://github.com/feeka/dna-storage.git
cd dna-storage
# create & activate a venv called .venv (recommended)
source .venv/bin/activate
python3 -m dna_storage.examples.basic_rs_pipeline

As an experiment what is done here (short)

The setup runs a set based on this paper, message-level Reed–Solomon experiments that measure average payload recovery across different outer-RS redundancy levels. Outputs are collected in bench_rs.csv. Representative visualizations below.

Note: the plots show mean percent payload recovered on the Y axis. The error-vs plot uses total DS error S = substitutions + deletions on the X axis (S shown as a percent); the pretty plot uses outer-RS redundancy on the X axis.

-- Full (long) experiment (default):

Very short — likely causes for low recovery

• deletions shift symbol packing → erasures
• RS decoder is erasure-only (no substitution correction)
• low coverage or too-small parity makes recovery fragile

Benchmarks

This repository includes example benchmarking scripts and plotting utilities under examples/ that produce reproducible CSV and PNG artifacts (e.g. bench_rs.csv, bench_rs.png).

Experiment: controlled DS-error experiment (staple behaviour)

A reproducible experiment that runs a series of total per-base error levels (substitutions + deletions) across a fixed set of levels and measures average payload recovery using only message-level (outer) Reed–Solomon is included.

• Toy experiment (quick example — matches current bench_rs.csv)

• Error total S values: 0.02 → 0.10 in steps of 0.02 (0.02, 0.04, 0.06, 0.08, 0.10)

  • NOTE: S is the per-base DS error fraction (S = sub_p + del_p); plots show S on the x-axis as a percentage (S * 100). DSChannel simulates substitutions + deletions.

• Trials per S: 10 (fast sample for debugging and figure previews)

• Payload length per trial L: fixed at 500 bytes

• Error split rule: sub_p ∈ [0.2S, 0.8S] selected per-trial; del_p = S - sub_p

• Coverage (copies): 60 reads per oligo (current run)

• RS redundancy used: 0.15 (15%)

• Pipeline behaviour: exactly the basic_rs_pipeline flow (Reed–Solomon encoder/decoder, rotating mapper, SoupDuplicator, DSChannel, SimpleAligner)

Notes:

• The script uses the constrained split so each trial preserves the requested total error S but varies the ratio of deletion vs substitution.
• The aligner produces a single per-oligo consensus which may be shorter than the original codeword when deletions occur; those missing positions reduce the number of available codeword evaluations and can cause the RS decoder to be unable to reconstruct the message (the current RS decoder requires >= k correct byte-evaluations per block).
• Results are written to bench_rs.csv and plotted with the existing plotting scripts.

Citation

If you use this code in published work, please cite the repository URL and add an entry appropriate to your citation style.

License

MIT – see LICENSE

Issues and pull requests welcome.