Genomic figures from the command line or from Rust: tracks over one 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:
From a shell, a figure like it is one command:
cargo install --git https://github.com/PathoGenOmics-Lab/karyon
karyon rpoB aln.bam H37Rv.fa genes.gff3 calls.vcf.gz -o rpoB.svgThe first word says where: a gene the annotation names, a whole sequence, or a
span such as NC_000962.3:761,000-762,999. Each file is drawn as what its name
says it holds and labelled after itself, and a BAM or a file compressed with
gzip is read as it is. karyon --help fits on one screen, and
karyon help coverage lists what one track takes. The Playground
runs the same program in your browser, with nothing to install.
From Rust, 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-seven track types compose that way, over one region, in the order you
write them. No runtime dependencies, no I/O while drawing beyond an optional
save_svg, and plain SVG 1.1 that opens unchanged in a browser, in Inkscape
and in Illustrator.
Most kinds of plot it draws, on one sheet
The documentation is the manual; this page is the front door.
| If you want to | Go to |
|---|---|
| try it without installing anything | Playground, which is this crate compiled to WebAssembly and running in your own browser |
| draw something in the next five minutes | Start here, then What do you have? for your kind of data |
| find the plot that fits your data | Gallery, which sorts all thirty-seven 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 | Styling |
| 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).