Genomic track plots for Rust. Composable tracks over a shared coordinate axis, rendered to standalone SVG.
Paula Ruiz-Rodriguez1
and Mireia Coscolla1
1. I2SysBio, University of Valencia-CSIC, FISABIO Joint Research Unit Infection and Public Health, Valencia, Spain
General plotting libraries know about points and lines. They do not know that a
position is a base, that a gene has a strand, that a pixel at genome scale
covers two thousand bases, or that a figure is worthless if its tracks do not
line up. karyon is the small amount of code that does know those things.
It draws what a genome browser draws: a stack of tracks over one shared coordinate axis, so read depth, the reference bases, the gene models and the variant calls all agree on where position 761,410 is.
Zoom in and the same tracks show individual bases. Nothing about the tracks changes, only the region:
That figure is this much code:
use karyon::{plot, Feature, Strand, Variant};
let svg = plot("NC_000962.3:761000-761200")?
.title("rpoB resistance determining region")
.add_coverage(depth).label("depth")
.add_sequence(bases).label("reference")
.add_features(genes).label("genes")
.add_variants(calls).label("variants")
.to_svg();Thirty-three track types compose that way, over one region, in the order you
write them. No runtime dependencies, no I/O beyond an optional save_svg, and
plain SVG 1.1 that opens unchanged in a browser, in Inkscape and in Illustrator.
Every kind of plot it draws, on one sheet
The documentation is the manual; this page is the front door.
| If you want to | Go to |
|---|---|
| draw something in the next five minutes | Quick start |
| find the plot that fits your data | Plot catalogue, which sorts all thirty-three tracks by biological question rather than by type name |
| look up one track's exact API | Track reference |
| read files instead of building vectors | File formats: BED, bedGraph, GFF3, VCF, SAM, cytoBand, samtools depth, FASTA and Newick |
| draw trees, traits, support or dN/dS | Phylogenetics |
| put samples on a map | Geographic genomics |
| make it match the rest of your figures | Theming and the visual system |
| use it from a shell instead of Rust | Command line |
| know why a base lands where it does | Coordinates, which is the one thing worth reading before trusting a figure |
| add a track type it lacks | Extending, which is about thirty lines |
| copy a whole worked figure | Recipes |
Positions are 0-based and half-open everywhere, the BED convention. The two
exceptions are the ones a reader sees: locus strings such as
NC_000962.3:761,000-763,000 are 1-based and inclusive, as samtools and IGV
write them, and tick labels are printed the same way. karyon::read does that
subtraction for you, and a property in the test suite checks that the same
interval written as BED and as GFF3 comes back as the same two numbers. The
coordinates page
is the long version.
cargo install --git https://github.com/PathoGenOmics-Lab/karyonOr as a library, until it is published to crates.io:
[dependencies]
karyon = { git = "https://github.com/PathoGenOmics-Lab/karyon" }Building from source needs nothing but a Rust toolchain, 1.74 or newer:
git clone https://github.com/PathoGenOmics-Lab/karyon
cd karyon
cargo testNot implemented yet, in the order they are likely to arrive:
- A figure-level highlight and mask, one column running through every track, so a masked region is visible as a mask rather than as an absence of variants
- PNG output, likely behind a feature flag so the default stays dependency-free
- A release on crates.io
Bug reports, questions and pull requests are all welcome. The contributing guide says what a change needs before it can be merged, and Q&A is the place for anything that is a question rather than a defect.
Please cite the tool and the formats it reads. The citation page has both.
MIT. See LICENSE.
A plotting library is meant to be a dependency, and a copyleft one cannot be used by a tool that is not itself copyleft. The formats it sits beside are permissive for the same reason: noodles and rust-bio are both MIT.
Paula Ruiz-Rodriguez 💻 🔬 🤔 🔣 🎨 🔧 |
Mireia Coscolla 🔍 🤔 🧑🏫 🔬 📓 |
This project follows the all-contributors specification (emoji key).